compileall — 字节编译 Python 库 — Python 文档

compileall — 字节编译 Python 库

源代码： :source:`Lib/compileall.py`

---

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

命令行使用

该模块可以作为脚本（使用 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 编译所有 -r 0 相当于 python -m 编译所有 -l .

-j N

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

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

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

-o level

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

-e dir

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

--hardlink-dupes

如果两个优化级别不同的.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 设置。 生成的字节码缓存仅在 compile() 使用将在运行时使用的相同 sys.pycache_prefix（如果有）运行时才有用。

公共职能

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 并且给出了 workers 参数，那么顺序编译将用作后备。 如果 workers 为 0，则使用系统中的核心数。 如果 workers 低于 0，则会引发 ValueError。

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

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

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

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

3.5 版变更： 增加了 workers 参数。

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

3.5 版本更改： legacy 参数只写出.pyc 文件，而不是.pyo 文件，无论优化[ X156X] 是。

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

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

3.7.2 版更改： invalidation_mode 参数的默认值更新为无。

在 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)

使用路径 全名 编译文件。 如果文件编译成功，则返回真值，否则返回假值。

如果给出了 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、bytes 或 os.PathLike。

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

3.2 版中的新功能。

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

3.5 版本更改： legacy 参数只写出.pyc 文件，而不是.pyo 文件，无论优化[ X156X] 是。

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

3.7.2 版更改： invalidation_mode 参数的默认值更新为无。

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 版本更改： legacy 参数只写出.pyc 文件，而不是.pyo 文件，无论优化[ X156X] 是。

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

3.7.2 版更改： invalidation_mode 参数的默认值更新为无。

强制重新编译 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

字节编译单个源文件。