1:mod:`py_compile` --- Compile Python source files 2================================================= 3 4.. module:: py_compile 5 :synopsis: Generate byte-code files from Python source files. 6 7.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> 8.. documentation based on module docstrings 9 10**Source code:** :source:`Lib/py_compile.py` 11 12.. index:: pair: file; byte-code 13 14-------------- 15 16The :mod:`py_compile` module provides a function to generate a byte-code file 17from a source file, and another function used when the module source file is 18invoked as a script. 19 20Though not often needed, this function can be useful when installing modules for 21shared use, especially if some of the users may not have permission to write the 22byte-code cache files in the directory containing the source code. 23 24 25.. exception:: PyCompileError 26 27 Exception raised when an error occurs while attempting to compile the file. 28 29 30.. function:: compile(file, cfile=None, dfile=None, doraise=False, optimize=-1, invalidation_mode=PycInvalidationMode.TIMESTAMP, quiet=0) 31 32 Compile a source file to byte-code and write out the byte-code cache file. 33 The source code is loaded from the file named *file*. The byte-code is 34 written to *cfile*, which defaults to the :pep:`3147`/:pep:`488` path, ending 35 in ``.pyc``. 36 For example, if *file* is ``/foo/bar/baz.py`` *cfile* will default to 37 ``/foo/bar/__pycache__/baz.cpython-32.pyc`` for Python 3.2. If *dfile* is 38 specified, it is used as the name of the source file in error messages 39 instead of *file*. If *doraise* is true, a :exc:`PyCompileError` is raised 40 when an error is encountered while compiling *file*. If *doraise* is false 41 (the default), an error string is written to ``sys.stderr``, but no exception 42 is raised. This function returns the path to byte-compiled file, i.e. 43 whatever *cfile* value was used. 44 45 The *doraise* and *quiet* arguments determine how errors are handled while 46 compiling file. If *quiet* is 0 or 1, and *doraise* is false, the default 47 behaviour is enabled: an error string is written to ``sys.stderr``, and the 48 function returns ``None`` instead of a path. If *doraise* is true, 49 a :exc:`PyCompileError` is raised instead. However if *quiet* is 2, 50 no message is written, and *doraise* has no effect. 51 52 If the path that *cfile* becomes (either explicitly specified or computed) 53 is a symlink or non-regular file, :exc:`FileExistsError` will be raised. 54 This is to act as a warning that import will turn those paths into regular 55 files if it is allowed to write byte-compiled files to those paths. This is 56 a side-effect of import using file renaming to place the final byte-compiled 57 file into place to prevent concurrent file writing issues. 58 59 *optimize* controls the optimization level and is passed to the built-in 60 :func:`compile` function. The default of ``-1`` selects the optimization 61 level of the current interpreter. 62 63 *invalidation_mode* should be a member of the :class:`PycInvalidationMode` 64 enum and controls how the generated bytecode cache is invalidated at 65 runtime. The default is :attr:`PycInvalidationMode.CHECKED_HASH` if 66 the :envvar:`SOURCE_DATE_EPOCH` environment variable is set, otherwise 67 the default is :attr:`PycInvalidationMode.TIMESTAMP`. 68 69 .. versionchanged:: 3.2 70 Changed default value of *cfile* to be :PEP:`3147`-compliant. Previous 71 default was *file* + ``'c'`` (``'o'`` if optimization was enabled). 72 Also added the *optimize* parameter. 73 74 .. versionchanged:: 3.4 75 Changed code to use :mod:`importlib` for the byte-code cache file writing. 76 This means file creation/writing semantics now match what :mod:`importlib` 77 does, e.g. permissions, write-and-move semantics, etc. Also added the 78 caveat that :exc:`FileExistsError` is raised if *cfile* is a symlink or 79 non-regular file. 80 81 .. versionchanged:: 3.7 82 The *invalidation_mode* parameter was added as specified in :pep:`552`. 83 If the :envvar:`SOURCE_DATE_EPOCH` environment variable is set, 84 *invalidation_mode* will be forced to 85 :attr:`PycInvalidationMode.CHECKED_HASH`. 86 87 .. versionchanged:: 3.7.2 88 The :envvar:`SOURCE_DATE_EPOCH` environment variable no longer 89 overrides the value of the *invalidation_mode* argument, and determines 90 its default value instead. 91 92 .. versionchanged:: 3.8 93 The *quiet* parameter was added. 94 95 96.. class:: PycInvalidationMode 97 98 A enumeration of possible methods the interpreter can use to determine 99 whether a bytecode file is up to date with a source file. The ``.pyc`` file 100 indicates the desired invalidation mode in its header. See 101 :ref:`pyc-invalidation` for more information on how Python invalidates 102 ``.pyc`` files at runtime. 103 104 .. versionadded:: 3.7 105 106 .. attribute:: TIMESTAMP 107 108 The ``.pyc`` file includes the timestamp and size of the source file, 109 which Python will compare against the metadata of the source file at 110 runtime to determine if the ``.pyc`` file needs to be regenerated. 111 112 .. attribute:: CHECKED_HASH 113 114 The ``.pyc`` file includes a hash of the source file content, which Python 115 will compare against the source at runtime to determine if the ``.pyc`` 116 file needs to be regenerated. 117 118 .. attribute:: UNCHECKED_HASH 119 120 Like :attr:`CHECKED_HASH`, the ``.pyc`` file includes a hash of the source 121 file content. However, Python will at runtime assume the ``.pyc`` file is 122 up to date and not validate the ``.pyc`` against the source file at all. 123 124 This option is useful when the ``.pycs`` are kept up to date by some 125 system external to Python like a build system. 126 127 128.. function:: main(args=None) 129 130 Compile several source files. The files named in *args* (or on the command 131 line, if *args* is ``None``) are compiled and the resulting byte-code is 132 cached in the normal manner. This function does not search a directory 133 structure to locate source files; it only compiles files named explicitly. 134 If ``'-'`` is the only parameter in args, the list of files is taken from 135 standard input. 136 137 .. versionchanged:: 3.2 138 Added support for ``'-'``. 139 140When this module is run as a script, the :func:`main` is used to compile all the 141files named on the command line. The exit status is nonzero if one of the files 142could not be compiled. 143 144 145.. seealso:: 146 147 Module :mod:`compileall` 148 Utilities to compile all Python source files in a directory tree. 149