compileall —字节编译 Python 库

源代码： Lib/compileall.py

---

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

Command-line use

这个模块可以作为脚本(使用 python -m compileall )来编译 Python 源代码。

• directory ...

• file ...

  • 位置参数是要编译的文件或包含源文件的目录，这些文件是递归遍历的。如果未提供任何参数，则其行为就像命令行是-l <directories from sys.path>。

• -l ``

  • 不要递归到子目录，而只能编译直接包含在命名或隐含目录中的源代码文件。

• -f ``

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

• -q ``

  • 不要打印已编译文件的列表。如果pass一次，错误消息仍将被打印。如果pass两次(-qq)，将禁止所有输出。

• -d destdir

  • 目录位于要编译的每个文件的路径之前。这将出现在编译时回溯中，并且也将编译到字节码文件中，在执行字节码文件时源文件不存在的情况下，它将在回溯和其他消息中使用。

• -x regex

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

• -i list

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

• -b ``

  • 将字节代码文件写入其原有位置和名称，这可能会覆盖由另一个版本的 Python 创建的字节代码文件。默认设置是将文件写入其 PEP 3147的位置和名称，这允许来自多个 Python 版本的字节码文件共存。

• -r ``

  • 控制子目录的最大递归级别。如果提供此选项，则将不考虑-l选项。 python -m compileall -r 0 等效于 python -m compileall -l 。

• -j N

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

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

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

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

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

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

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

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

Public functions

• compileall. compile_dir(* dir ， maxlevels = 10 ， ddir = None ， force = False ， rx = None ， quiet = 0 ， legacy = False ， optimize = -1 *， * workers = 1 ， invalidation_mode = None *)
  • 递归地以* dir *命名的目录树，编译整个.py文件。如果所有文件编译成功，则返回 true，否则返回 false。

• maxlevels *参数用于限制递归的深度；默认为10。

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

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

如果给定了* rx *，则在要考虑编译的每个文件的完整路径上调用其搜索方法，如果返回的是 true 值，则跳过该文件。

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

如果* legacy *为 true，则将字节代码文件写入其旧位置和名称，这可能会覆盖由另一个版本的 Python 创建的字节代码文件。默认设置是将文件写入其 PEP 3147的位置和名称，这允许来自多个 Python 版本的字节码文件共存。

• optimize *指定编译器的优化级别。它被传递给内置的compile()函数。

参数* workers 指定使用多少个 worker 并行编译文件。默认为不使用多个工作程序。如果平台不能使用多个 worker 并且给出了 workers 参数，那么 Sequences 编译将用作后备。如果 workers 为 0，则使用系统中的内核数。如果 workers *低于0，则将引发ValueError。

• invalidation_mode *应该是py_compile.PycInvalidationMode枚举的成员，并控制如何在运行时使生成的 pycs 无效。

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

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

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

在版本 3.5 中更改：* legacy 参数仅写出.pyc个文件，而不写.pyo个文件，无论 optimize *的值是多少。

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

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

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

在 3.8 版中进行了更改：现在将* workers *设置为 0 可以选择最佳的内核数量。

• compileall. compile_file(* fullname ， ddir = None ， force = False ， rx = None ， quiet = 0 ， legacy = False ， optimize = -1 ， invalidation_mode = None *)
  • 使用路径* fullname *编译文件。如果文件编译成功，则返回 true 值，否则返回 false 值。

如果给定了* ddir *，它会被放在要编译的文件的路径中，以供在编译时回溯中使用，并且还会被编译为字节码文件，在以下情况下，它将在回溯和其他消息中使用：执行字节码文件时源文件不存在。

如果给定了* rx *，则其搜索方法会将完整路径名传递给正在编译的文件，如果返回的是 true 值，则不编译该文件并返回True。

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

如果* legacy *为 true，则将字节代码文件写入其旧位置和名称，这可能会覆盖由另一个版本的 Python 创建的字节代码文件。默认设置是将文件写入其 PEP 3147的位置和名称，这允许来自多个 Python 版本的字节码文件共存。

• optimize *指定编译器的优化级别。它被传递给内置的compile()函数。

• invalidation_mode *应该是py_compile.PycInvalidationMode枚举的成员，并控制如何在运行时使生成的 pycs 无效。

3.2 版中的新Function。

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

在版本 3.5 中更改：* legacy 参数仅写出.pyc个文件，而不写.pyo个文件，无论 optimize *的值是多少。

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

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

• compileall. compile_path(* skip_curdir = True ， maxlevels = 0 ， force = False ， quiet = 0 ， legacy = False ， optimize = -1 ， invalidation_mode = None *)
  • 字节编译sys.path中找到的所有.py文件。如果所有文件编译成功，则返回 true，否则返回 false。

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

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

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

在版本 3.5 中更改：* legacy 参数仅写出.pyc个文件，而不写.pyo个文件，无论 optimize *的值是多少。

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