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，则 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 为 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 版本中更改: 根据 PEP 552 的规定，添加了 invalidation_mode 参数。如果设置了
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 源文件的实用工具。