py_compile —编译 Python 源文件

源代码： Lib/py_compile.py

---

py_compile模块提供了从源文件生成字节码文件的Function，以及在将模块源文件作为脚本调用时使用的另一个Function。

尽管并不经常需要，但此Function在安装模块以供共享使用时很有用，尤其是在某些用户可能无权在包含源代码的目录中写入字节码缓存文件的情况下。

• exception py_compile. PyCompileError

  • try编译文件时发生错误时引发异常。

• 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。这是作为警告，如果允许导入将字节编译的文件写入那些路径，则导入会将这些路径转换为常规文件。这是使用文件重命名将finally的字节编译文件放置到位以防止并发文件写入问题的导入的副作用。

• 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 *参数。

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

3.7 版中的新Function。

• 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，则在命令行上)，然后以常规方式缓存生成的字节码。此Function不会搜索目录结构来查找源文件；它仅编译显式命名的文件。如果'-'是 args 中的唯一参数，则文件列表取自标准 Importing。

在版本 3.2 中更改：添加了对'-'的支持。

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