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)¶
将源文件编译为字节码并写入字节码缓存文件。源代码从名为 file 的文件中加载。字节码写入 cfile，默认路径符合 PEP 3147/PEP 488 规范，以
.pyc结尾。例如，如果 file 是/foo/bar/baz.py，则对于 Python 3.2，cfile 将默认为/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 为 true，则会引发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与源文件的一致性。当
.pyc文件由 Python 外部的某个系统（如构建系统）保持最新时，此选项很有用。
命令行接口¶
此模块可以作为脚本调用以编译多个源文件。在 filenames 中命名的文件将被编译，并且生成的字节码将以通常的方式缓存。此程序不搜索目录结构以查找源文件；它只编译显式命名的文件。如果其中一个文件无法编译，则退出状态码为非零。
- -q, --quiet¶
抑制错误输出。
版本 3.2 中更改: 添加了对 - 的支持。
版本 3.10 中更改: 添加了对 -q 的支持。
参见
- 模块
compileall 用于编译目录树中所有 Python 源文件的实用程序。