py_compile — Compile Python source files¶
Source code: Lib/py_compile.py
The py_compile module provides a function to generate a byte-code file
from a source file, and another function used when the module source file is
invoked as a script.
Though not often needed, this function can be useful when installing modules for shared use, especially if some of the users may not have permission to write the byte-code cache files in the directory containing the source code.
- 
exception py_compile.PyCompileError¶
- Exception raised when an error occurs while attempting to compile the file. 
- 
py_compile.compile(file, cfile=None, dfile=None, doraise=False, optimize=-1, invalidation_mode=PycInvalidationMode.TIMESTAMP)¶
- Compile a source file to byte-code and write out the byte-code cache file. The source code is loaded from the file named file. The byte-code is written to cfile, which defaults to the PEP 3147/PEP 488 path, ending in - .pyc. For example, if file is- /foo/bar/baz.pycfile will default to- /foo/bar/__pycache__/baz.cpython-32.pycfor Python 3.2. If dfile is specified, it is used as the name of the source file in error messages when instead of file. If doraise is true, a- PyCompileErroris raised when an error is encountered while compiling file. If doraise is false (the default), an error string is written to- sys.stderr, but no exception is raised. This function returns the path to byte-compiled file, i.e. whatever cfile value was used.- If the path that cfile becomes (either explicitly specified or computed) is a symlink or non-regular file, - FileExistsErrorwill be raised. This is to act as a warning that import will turn those paths into regular files if it is allowed to write byte-compiled files to those paths. This is a side-effect of import using file renaming to place the final byte-compiled file into place to prevent concurrent file writing issues.- optimize controls the optimization level and is passed to the built-in - compile()function. The default of- -1selects the optimization level of the current interpreter.- invalidation_mode should be a member of the - PycInvalidationModeenum and controls how the generated bytecode cache is invalidated at runtime. The default is- PycInvalidationMode.CHECKED_HASHif the- SOURCE_DATE_EPOCHenvironment variable is set, otherwise the default is- PycInvalidationMode.TIMESTAMP.- Changed in version 3.2: Changed default value of cfile to be PEP 3147-compliant. Previous default was file + - 'c'(- 'o'if optimization was enabled). Also added the optimize parameter.- Changed in version 3.4: Changed code to use - importlibfor the byte-code cache file writing. This means file creation/writing semantics now match what- importlibdoes, e.g. permissions, write-and-move semantics, etc. Also added the caveat that- FileExistsErroris raised if cfile is a symlink or non-regular file.- Changed in version 3.7: The invalidation_mode parameter was added as specified in PEP 552. If the - SOURCE_DATE_EPOCHenvironment variable is set, invalidation_mode will be forced to- PycInvalidationMode.CHECKED_HASH.- Changed in version 3.7.2: The - SOURCE_DATE_EPOCHenvironment variable no longer overrides the value of the invalidation_mode argument, and determines its default value instead.
- 
class py_compile.PycInvalidationMode¶
- A enumeration of possible methods the interpreter can use to determine whether a bytecode file is up to date with a source file. The - .pycfile indicates the desired invalidation mode in its header. See Cached bytecode invalidation for more information on how Python invalidates- .pycfiles at runtime.- New in version 3.7. - 
TIMESTAMP¶
- The - .pycfile includes the timestamp and size of the source file, which Python will compare against the metadata of the source file at runtime to determine if the- .pycfile needs to be regenerated.
 - 
CHECKED_HASH¶
- The - .pycfile includes a hash of the source file content, which Python will compare against the source at runtime to determine if the- .pycfile needs to be regenerated.
 - 
UNCHECKED_HASH¶
- Like - CHECKED_HASH, the- .pycfile includes a hash of the source file content. However, Python will at runtime assume the- .pycfile is up to date and not validate the- .pycagainst the source file at all.- This option is useful when the - .pycsare kept up to date by some system external to Python like a build system.
 
- 
- 
py_compile.main(args=None)¶
- Compile several source files. The files named in args (or on the command line, if args is - None) are compiled and the resulting byte-code is cached in the normal manner. This function does not search a directory structure to locate source files; it only compiles files named explicitly. If- '-'is the only parameter in args, the list of files is taken from standard input.- Changed in version 3.2: Added support for - '-'.
When this module is run as a script, the main() is used to compile all the
files named on the command line.  The exit status is nonzero if one of the files
could not be compiled.
See also
- Module compileall
- Utilities to compile all Python source files in a directory tree. 
