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 (a] 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 16 The :mod:`py_compile` module provides a function to generate a byte-code file 17 from a source file, and another function used when the module source file is 18 invoked as a script. 19 20 Though not often needed, this function can be useful when installing modules for 21 shared use, especially if some of the users may not have permission to write the 22 byte-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) 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 when 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 If the path that *cfile* becomes (either explicitly specified or computed) 46 is a symlink or non-regular file, :exc:`FileExistsError` will be raised. 47 This is to act as a warning that import will turn those paths into regular 48 files if it is allowed to write byte-compiled files to those paths. This is 49 a side-effect of import using file renaming to place the final byte-compiled 50 file into place to prevent concurrent file writing issues. 51 52 *optimize* controls the optimization level and is passed to the built-in 53 :func:`compile` function. The default of ``-1`` selects the optimization 54 level of the current interpreter. 55 56 *invalidation_mode* should be a member of the :class:`PycInvalidationMode` 57 enum and controls how the generated bytecode cache is invalidated at 58 runtime. The default is :attr:`PycInvalidationMode.CHECKED_HASH` if 59 the :envvar:`SOURCE_DATE_EPOCH` environment variable is set, otherwise 60 the default is :attr:`PycInvalidationMode.TIMESTAMP`. 61 62 .. versionchanged:: 3.2 63 Changed default value of *cfile* to be :PEP:`3147`-compliant. Previous 64 default was *file* + ``'c'`` (``'o'`` if optimization was enabled). 65 Also added the *optimize* parameter. 66 67 .. versionchanged:: 3.4 68 Changed code to use :mod:`importlib` for the byte-code cache file writing. 69 This means file creation/writing semantics now match what :mod:`importlib` 70 does, e.g. permissions, write-and-move semantics, etc. Also added the 71 caveat that :exc:`FileExistsError` is raised if *cfile* is a symlink or 72 non-regular file. 73 74 .. versionchanged:: 3.7 75 The *invalidation_mode* parameter was added as specified in :pep:`552`. 76 If the :envvar:`SOURCE_DATE_EPOCH` environment variable is set, 77 *invalidation_mode* will be forced to 78 :attr:`PycInvalidationMode.CHECKED_HASH`. 79 80 .. versionchanged:: 3.7.2 81 The :envvar:`SOURCE_DATE_EPOCH` environment variable no longer 82 overrides the value of the *invalidation_mode* argument, and determines 83 its default value instead. 84 85 86 .. class:: PycInvalidationMode 87 88 A enumeration of possible methods the interpreter can use to determine 89 whether a bytecode file is up to date with a source file. The ``.pyc`` file 90 indicates the desired invalidation mode in its header. See 91 :ref:`pyc-invalidation` for more information on how Python invalidates 92 ``.pyc`` files at runtime. 93 94 .. versionadded:: 3.7 95 96 .. attribute:: TIMESTAMP 97 98 The ``.pyc`` file includes the timestamp and size of the source file, 99 which Python will compare against the metadata of the source file at 100 runtime to determine if the ``.pyc`` file needs to be regenerated. 101 102 .. attribute:: CHECKED_HASH 103 104 The ``.pyc`` file includes a hash of the source file content, which Python 105 will compare against the source at runtime to determine if the ``.pyc`` 106 file needs to be regenerated. 107 108 .. attribute:: UNCHECKED_HASH 109 110 Like :attr:`CHECKED_HASH`, the ``.pyc`` file includes a hash of the source 111 file content. However, Python will at runtime assume the ``.pyc`` file is 112 up to date and not validate the ``.pyc`` against the source file at all. 113 114 This option is useful when the ``.pycs`` are kept up to date by some 115 system external to Python like a build system. 116 117 118 .. function:: main(args=None) 119 120 Compile several source files. The files named in *args* (or on the command 121 line, if *args* is ``None``) are compiled and the resulting byte-code is 122 cached in the normal manner. This function does not search a directory 123 structure to locate source files; it only compiles files named explicitly. 124 If ``'-'`` is the only parameter in args, the list of files is taken from 125 standard input. 126 127 .. versionchanged:: 3.2 128 Added support for ``'-'``. 129 130 When this module is run as a script, the :func:`main` is used to compile all the 131 files named on the command line. The exit status is nonzero if one of the files 132 could not be compiled. 133 134 135 .. seealso:: 136 137 Module :mod:`compileall` 138 Utilities to compile all Python source files in a directory tree. 139
