compileall — 字节编译 Python 库

源代码: Lib/compileall.py

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

可用性: not WASI.

此模块在 WebAssembly 上不起作用或不可用。有关详细信息，请参阅 WebAssembly 平台。

命令行使用

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

directory ...
file ...

位置参数是要编译的文件或包含源代码文件的目录，递归遍历。如果没有给出参数，则行为如同命令行是 -l <来自 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.process_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 文件。如果所有文件都成功编译，则返回 True 值，否则返回 False 值。

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

如果给定 ddir，它会添加到正在编译的每个文件的路径前面，以便在编译时进行回溯，并且还会编译到字节码文件中，在字节码文件执行时，如果源文件不存在，它将在回溯和其他消息中使用。

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

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

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

如果 legacy 为 True，则字节码文件将写入其旧位置和名称，这可能会覆盖由另一个 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 版本中更改: 无论 optimize 的值如何，legacy 参数仅写入 .pyc 文件，而不是 .pyo 文件。

在 3.6 版本中更改: 接受 path-like object。

在 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 的文件。如果该文件成功编译，则返回 True 值，否则返回 False 值。

如果提供了 ddir，它会被添加到正在编译的文件路径的前面，用于编译时的回溯，并且也会被编译到字节码文件中。在字节码文件执行时，如果源文件不存在，它将用于回溯和其他消息中。

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

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

如果 legacy 为 true，字节码文件将被写入其旧的位置和名称，这可能会覆盖由其他 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 版本中更改: 无论 optimize 的值如何，legacy 参数仅写入 .pyc 文件，而不是 .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)

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

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

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

在 3.5 版本中更改: quiet 参数被更改为多级值。

在 3.5 版本中更改: 无论 optimize 的值如何，legacy 参数仅写入 .pyc 文件，而不是 .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

字节编译单个源文件。