# `py_compile` --- 编译 Python 源文件

源代码: Lib/py_compile.py

`py_compile` 模块提供了用来从源文件生成字节码的函数和另一个用于当模块源文件作为脚本被调用时的函数。

虽然不太常用，但这个函数在安装共享模块时还是很有用的，特别是当一些用户可能没有权限在包含源代码的目录中写字节码缓存文件时。

exception `py_compile.``PyCompileError`

  当编译文件过程中发生错误时，抛出的异常。

`py_compile.``compile`(file, cfile=None, dfile=None, doraise=False, optimize=-1, invalidation_mode=PycInvalidationMode.TIMESTAMP, quiet=0)

  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.py` cfile will default to `/foo/bar/__pycache__/baz.cpython-32.pyc` for Python 3.2. If dfile is specified, it is used as the name of the source file in error messages instead of file. If doraise is true, a `PyCompileError` is 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.

  The doraise and quiet arguments determine how errors are handled while compiling file. If quiet is 0 or 1, and doraise is false, the default behaviour is enabled: an error string is written to `sys.stderr`, and the function returns `None` instead of a path. If doraise is true, a `PyCompileError` is raised instead. However if quiet is 2, no message is written, and doraise has no effect.

  If the path that cfile becomes (either explicitly specified or computed) is a symlink or non-regular file, `FileExistsError` will 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 `-1` selects the optimization level of the current interpreter.

  invalidation_mode should be a member of the `PycInvalidationMode` enum and controls how the generated bytecode cache is invalidated at runtime. The default is `PycInvalidationMode.CHECKED_HASH` if the `SOURCE_DATE_EPOCH` environment variable is set, otherwise the default is `PycInvalidationMode.TIMESTAMP`.

  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.

  3.4 版更變: Changed code to use `importlib` for the byte-code cache file writing. This means file creation/writing semantics now match what `importlib` does, e.g. permissions, write-and-move semantics, etc. Also added the caveat that `FileExistsError` is raised if cfile is a symlink or non-regular file.

  3.7 版更變: The invalidation_mode parameter was added as specified in PEP 552. If the `SOURCE_DATE_EPOCH` environment variable is set, invalidation_mode will be forced to `PycInvalidationMode.CHECKED_HASH`.

  3.7.2 版更變: The `SOURCE_DATE_EPOCH` environment variable no longer overrides the value of the invalidation_mode argument, and determines its default value instead.

  3.8 版更變: The quiet parameter was added.

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 `.pyc` file indicates the desired invalidation mode in its header. See 已缓存字节码的失效 for more information on how Python invalidates `.pyc` files at runtime.

  3.7 版新加入.

  `TIMESTAMP`

    The `.pyc` file 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 `.pyc` file needs to be regenerated.

  `CHECKED_HASH`

    The `.pyc` file includes a hash of the source file content, which Python will compare against the source at runtime to determine if the `.pyc` file needs to be regenerated.

  `UNCHECKED_HASH`

    Like `CHECKED_HASH`, the `.pyc` file includes a hash of the source file content. However, Python will at runtime assume the `.pyc` file is up to date and not validate the `.pyc` against the source file at all.

    This option is useful when the `.pycs` are 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.

  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.

也參考

模块 `compileall`

  编译一个目录树中所有 Python 源文件的工具。