py_compile — 编译 Python 源文件 — Python 文档

py_compile — 编译 Python 源文件

源代码： :source:`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)

将源文件编译为字节码并写出字节码缓存文件。 源代码从名为 file 的文件加载。 字节码写入cfile，默认为PEP 3147/PEP 488路径，以 .pyc 结尾。 例如，如果 file 是 /foo/bar/baz.py cfile 对于 Python 3.2 将默认为 /foo/bar/__pycache__/baz.cpython-32.pyc。 如果指定了 dfile，它将被用作错误消息中的源文件名，而不是 file。 如果 doraise 为 true，则在编译 file 时遇到错误时会引发 PyCompileError。 如果 doraise 为 false（默认值），则会将错误字符串写入 sys.stderr，但不会引发异常。 此函数返回字节编译文件的路径，即 无论使用什么 cfile 值。

doraise 和 quiet 参数决定了编译文件时如何处理错误。 如果 quiet 为 0 或 1，且 doraise 为 false，则启用默认行为：将错误字符串写入 sys.stderr，函数返回 None 而不是路径。 如果 doraise 为真，则会引发 PyCompileError。 但是，如果 quiet 为 2，则不会写入任何消息，并且 doraise 不起作用。

如果 cfile 变为（明确指定或计算）的路径是符号链接或非常规文件，则将引发 FileExistsError。 这是为了警告如果允许将字节编译的文件写入这些路径，导入会将这些路径转换为常规文件。 这是使用文件重命名将最终字节编译文件放置到位以防止并发文件写入问题的导入的副作用。

optimize 控制优化级别并传递给内置的 compile() 函数。 -1 默认选择当前解释器的优化级别。

invalidation_mode 应该是 PycInvalidationMode 枚举的成员，并控制生成的字节码缓存在运行时如何失效。 如果设置了 SOURCE_DATE_EPOCH 环境变量，则默认为 PycInvalidationMode.CHECKED_HASH，否则默认为 PycInvalidationMode.TIMESTAMP。

在 3.2 版中更改：将 cfile 的默认值更改为 PEP 3147 兼容。 以前的默认值为 file + 'c'（如果启用了优化，则为 'o'）。 还添加了 optimize 参数。

3.4 版更改： 更改代码以使用 importlib 进行字节码缓存文件写入。 这意味着文件创建/写入语义现在匹配 importlib 所做的，例如 权限、写入和移动语义等。 还添加了警告，如果 cfile 是符号链接或非常规文件，则会引发 FileExistsError。

3.7 版更改： invalidation_mode 参数已按照 PEP 552 中的规定添加。 如果设置了 SOURCE_DATE_EPOCH 环境变量，invalidation_mode 将被强制为 PycInvalidationMode.CHECKED_HASH。

3.7.2 版更改： SOURCE_DATE_EPOCH 环境变量不再覆盖 invalidation_mode 参数的值，而是确定其默认值.

3.8 版更改： 添加了 quiet 参数。

class py_compile.PycInvalidationMode

解释器可以用来确定字节码文件是否与源文件是最新的可能方法的枚举。 .pyc 文件在其标题中指示所需的失效模式。 有关 Python 如何在运行时使 .pyc 文件失效的更多信息，请参阅 缓存字节码失效 。

3.7 版中的新功能。

TIMESTAMP

.pyc 文件包含源文件的时间戳和大小，Python 会在运行时与源文件的元数据进行比较，以确定是否需要重新生成 .pyc 文件。

CHECKED_HASH

.pyc 文件包含源文件内容的哈希值，Python 将在运行时与源文件内容进行比较，以确定是否需要重新生成 .pyc 文件。

UNCHECKED_HASH

与 CHECKED_HASH 一样，.pyc 文件包含源文件内容的哈希值。 但是，Python 会在运行时假定 .pyc 文件是最新的，并且根本不会根据源文件验证 .pyc。

当 .pycs 由 Python 外部的某些系统（如构建系统）保持最新时，此选项很有用。

py_compile.main(args=None)

编译几个源文件。 在 args 中命名的文件（或在命令行上，如果 args 是 None）被编译并以正常方式缓存生成的字节码。 此功能不搜索目录结构来定位源文件； 它只编译显式命名的文件。 如果 '-' 是 args 中的唯一参数，则文件列表取自标准输入。

3.2 版更改： 增加了对 '-' 的支持。

当此模块作为脚本运行时，main() 用于编译命令行上命名的所有文件。 如果无法编译文件之一，则退出状态为非零。

也可以看看

模块 compileall

用于编译目录树中所有 Python 源文件的实用程序。