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 版中更改: 添加了 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 之外的某个系统(如构建系统)保持最新时,此选项很有用。
命令行界面¶
此模块可以作为脚本调用,以编译多个源文件。filenames 中命名的文件将被编译,并且生成的字节码将以正常方式缓存。此程序不会搜索目录结构来查找源文件;它只编译显式命名的文件。如果无法编译其中一个文件,则退出状态为非零。
- -q, --quiet¶
禁止输出错误。
在版本 3.2 中更改:添加了对 -
的支持。
在版本 3.10 中更改:添加了对 -q
的支持。
另请参阅
- 模块
compileall
在目录树中编译所有 Python 源文件的实用程序。