compileall — 字节编译 Python 库

源代码： Lib/compileall.py

此模块提供了一些实用函数来支持安装 Python 库。这些函数编译目录树中的 Python 源文件。此模块可用于在库安装时创建缓存的字节码文件，即使没有对库目录的写权限，也可以使用这些文件。

可用性：Emscripten 除外，WASI 除外。

此模块在 WebAssembly 平台 wasm32-emscripten 和 wasm32-wasi 上不起作用或不可用。有关更多信息，请参阅 WebAssembly 平台。

命令行使用

此模块可以用作脚本（使用 python -m compileall）来编译 Python 源代码。

directory ...
file ...

位置参数是要编译的文件或包含源文件（递归遍历）的目录。如果没有给出参数，则表现得好像命令行是 -l <directories from sys.path>。

-l

不要递归到子目录，仅编译直接包含在指定或隐含目录中的源代码文件。

-f

即使时间戳是最新的，也强制重新构建。

-q

不要打印已编译的文件列表。如果传递一次，仍会打印错误消息。如果传递两次（-qq），则所有输出都将被抑制。

-d destdir

预先添加到正在编译的每个文件的路径的目录。这将出现在编译时回溯中，并且还编译到字节码文件中，在字节码文件执行时源文件不存在的情况下，它将用于回溯和其他消息中。

-s strip_prefix
-p prepend_prefix

移除 (-s) 或追加 (-p) 在 .pyc 文件中记录的路径给定前缀。不能与 -d 结合使用。

-x regex

regex 用于搜索考虑进行编译的每个文件的完整路径，如果 regex 产生匹配，则跳过该文件。

-i list

读取文件 list 并将其中包含的每一行添加到要编译的文件和目录列表中。如果 list 是 -，则从 stdin 中读取行。

-b

将字节码文件写入其旧位置和名称，这可能会覆盖由其他版本的 Python 创建的字节码文件。默认情况下，将文件写入其 PEP 3147 位置和名称，这允许来自多个 Python 版本的字节码文件共存。

-r

控制子目录的最大递归级别。如果给定此项，则不会考虑 -l 选项。python -m compileall <directory> -r 0 等同于 python -m compileall <directory> -l。

-j N

使用 N 个工作进程来编译给定目录中的文件。如果使用 0，则将使用 os.cpu_count() 的结果。

--invalidation-mode [timestamp|checked-hash|unchecked-hash]

控制在运行时如何使生成的字节码文件失效。timestamp 值表示将生成嵌入源时间戳和大小的 .pyc 文件。checked-hash 和 unchecked-hash 值会导致生成基于哈希的 pyc。基于哈希的 pyc 嵌入源文件内容的哈希，而不是时间戳。有关 Python 如何在运行时验证字节码缓存文件，请参阅 缓存字节码失效 以了解更多信息。如果未设置 SOURCE_DATE_EPOCH 环境变量，则默认值为 timestamp；如果设置了 SOURCE_DATE_EPOCH 环境变量，则默认值为 checked-hash。

-o level

使用给定的优化级别进行编译。可以多次使用以一次编译多个级别（例如，compileall -o 1 -o 2）。

-e dir

忽略指向给定目录外部的符号链接。

如果两个具有不同优化级别的 .pyc 文件具有相同的内容，则使用硬链接来合并重复的文件。

在版本 3.2 中更改：添加了 -i、-b 和 -h 选项。

在版本 3.5 中更改：添加了 -j、-r 和 -qq 选项。-q 选项已更改为多级值。-b 将始终生成以 .pyc 结尾的字节码文件，而不是 .pyo。

在版本 3.7 中更改：添加了 --invalidation-mode 选项。

在版本 3.9 中更改：添加了 -s、-p、-e 和 --hardlink-dupes 选项。将默认递归限制从 10 提高到 sys.getrecursionlimit()。添加了指定 -o 选项多次的可能性。

没有命令行选项来控制 compile() 函数使用的优化级别，因为 Python 解释器本身已经提供了选项：python -O -m compileall。

同样，compile() 函数会尊重 sys.pycache_prefix 设置。生成的字节码缓存仅在使用与运行时将使用的相同 sys.pycache_prefix（如果有）运行 compile() 时才有用。

公共函数

compileall.compile_dir(dir, maxlevels=sys.getrecursionlimit(), ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)

递归遍历目录树，该树由 dir 命名，同时编译沿途的所有 .py 文件。如果所有文件编译成功，则返回真值，否则返回假值。

maxlevels 参数用于限制递归的深度；其默认为 sys.getrecursionlimit()。

如果给定了 ddir，则将其添加为要编译的每个文件的路径前缀，以用于编译时回溯，并且还将其编译到字节码文件中，在源文件在执行字节码文件时不存在的情况下，该文件将在回溯和其他消息中使用。

如果 force 为真，则即使时间戳是最新的，模块也会重新编译。

如果给定了 rx，则会对考虑用于编译的每个文件的完整路径调用其 search 方法，如果它返回真值，则跳过该文件。这可用于排除与正则表达式匹配的文件，该正则表达式以 re.Pattern 对象的形式给出。

如果 quiet 为 False 或 0（默认值），则文件名和其他信息将打印到标准输出。设置为 1，则仅打印错误。设置为 2，则禁止所有输出。

如果 legacy 为真，则字节码文件将写入其旧位置和名称，这可能会覆盖由其他版本的 Python 创建的字节码文件。默认情况下，文件将写入其 PEP 3147 位置和名称，这允许来自多个 Python 版本的字节码文件共存。

optimize 指定编译器的优化级别。它被传递给内置 compile() 函数。还接受优化级别的序列，这些序列导致一次调用中对一个 .py 文件进行多次编译。

参数 workers 指定用于并行编译文件的 worker 数量。默认情况下不使用多个 worker。如果平台无法使用多个 worker 且给定了 workers 参数，则将使用顺序编译作为后备。如果 workers 为 0，则使用系统中的内核数。如果 workers 低于 0，则会引发 ValueError。

invalidation_mode 应为 py_compile.PycInvalidationMode 枚举的成员，并控制在运行时如何使生成的 pyc 失效。

stripdir、prependdir 和 limit_sl_dest 参数对应于上面描述的 -s、-p 和 -e 选项。它们可以指定为 str 或 os.PathLike。

如果 hardlink_dupes 为 true，并且两个具有不同优化级别的 .pyc 文件具有相同的内容，则使用硬链接合并重复文件。

在版本 3.2 中更改： 添加了 legacy 和 optimize 参数。

在版本 3.5 中更改： 添加了 workers 参数。

在版本 3.5 中更改： quiet 参数已更改为多级值。

在版本 3.5 中更改： legacy 参数仅写出 .pyc 文件，无论 optimize 的值是什么，都不会写出 .pyo 文件。

在版本 3.6 中更改： 接受 类路径对象。

在版本 3.7 中更改： 添加了 invalidation_mode 参数。

在版本 3.7.2 中更改： invalidation_mode 参数的默认值更新为 None。

在版本 3.8 中更改： 将 workers 设置为 0 现在会选择最佳内核数。

在版本 3.9 中更改： 添加了 stripdir、prependdir、limit_sl_dest 和 hardlink_dupes 参数。maxlevels 的默认值已从 10 更改为 sys.getrecursionlimit()

compileall.compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)

使用路径 fullname 编译文件。如果文件编译成功，则返回一个真值；否则，返回一个假值。

如果给定了 ddir，则将其添加为前缀到要编译的文件的路径中，以用于编译时回溯，并且还编译到字节码文件中，在字节码文件执行时源文件不存在的情况下，它将用于回溯和其他消息中。

如果给定了 rx，则其 search 方法将传递给正在编译的文件的完整路径名，如果它返回真值，则不会编译该文件，并且返回 True。这可用于排除与正则表达式匹配的文件，该正则表达式以 re.Pattern 对象的形式给出。

如果 quiet 为 False 或 0（默认值），则文件名和其他信息将打印到标准输出。设置为 1，则仅打印错误。设置为 2，则禁止所有输出。

如果 legacy 为真，则字节码文件将写入其旧位置和名称，这可能会覆盖由其他版本的 Python 创建的字节码文件。默认情况下，将文件写入其 PEP 3147 位置和名称，这允许来自多个 Python 版本的字节码文件共存。

optimize 指定编译器的优化级别。它被传递给内置 compile() 函数。还接受优化级别的序列，这些序列导致一次调用中对一个 .py 文件进行多次编译。

invalidation_mode 应为 py_compile.PycInvalidationMode 枚举的成员，并控制在运行时如何使生成的 pyc 失效。

stripdir、prependdir 和 limit_sl_dest 参数对应于上面描述的 -s、-p 和 -e 选项。它们可以指定为 str 或 os.PathLike。

如果 hardlink_dupes 为 true，并且两个具有不同优化级别的 .pyc 文件具有相同的内容，则使用硬链接合并重复文件。

在 3.2 版中添加。

在版本 3.5 中更改： quiet 参数已更改为多级值。

在版本 3.5 中更改： legacy 参数仅写出 .pyc 文件，无论 optimize 的值是什么，都不会写出 .pyo 文件。

在版本 3.7 中更改： 添加了 invalidation_mode 参数。

在版本 3.7.2 中更改： invalidation_mode 参数的默认值更新为 None。

在 3.9 版中更改： 添加了 stripdir、prependdir、limit_sl_dest 和 hardlink_dupes 参数。

compileall.compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)

字节编译在 .py 文件中找到的所有 sys.path。如果所有文件都编译成功，则返回真值；否则，返回假值。

如果 skip_curdir 为真（默认值），则当前目录不会包含在搜索中。所有其他参数都传递给 compile_dir() 函数。请注意，与其他编译函数不同，maxlevels 的默认值为 0。

在版本 3.2 中更改： 添加了 legacy 和 optimize 参数。

在版本 3.5 中更改： quiet 参数已更改为多级值。

在版本 3.5 中更改： legacy 参数仅写出 .pyc 文件，无论 optimize 的值是什么，都不会写出 .pyo 文件。

在版本 3.7 中更改： 添加了 invalidation_mode 参数。

在版本 3.7.2 中更改： invalidation_mode 参数的默认值更新为 None。

要强制重新编译 Lib/ 子目录及其所有子目录中的所有 .py 文件

import compileall

compileall.compile_dir('Lib/', force=True)

# Perform same compilation, excluding files in .svn directories.
import re
compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True)

# pathlib.Path objects can also be used.
import pathlib
compileall.compile_dir(pathlib.Path('Lib/'), force=True)

另请参阅

模块 py_compile

字节编译单个源文件。