CPython compileall 模块完全指南批量字节码编译、.pyc 缓存管理与目录树编译实操【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpythoncompileall是 CPython 标准库中面向库安装场景的批处理编译工具它沿目录树递归收集.py源文件并逐个编译为字节码缓存.pyc使没有库目录写权限的用户也能直接受益于预编译缓存。阅读本篇后你将完整掌握python -m compileall的全部命令行选项含-d/-s/-p路径重写、-j并行、--invalidation-mode与--hardlink-dupes等能熟练调用 compile_dir / compile_file / compile_path 三大公开函数并理解SOURCE_DATE_EPOCH、PEP 3147 布局与运行时.pyc校验等底层机制。compileall 在 CPython 中的作用compileall的核心价值在 Python 官方文档与源码模块 docstring 中表述得非常一致Byte-compile Python libraries字节码编译 Python 库。当一个 Python 安装目录被多个用户共享时普通用户可能没有源码目录的写权限也就无法在 import 时由解释器自动落盘.pyc——每次启动都得现场编译程序启动会明显变慢。解决方案正是在库安装阶段打包与安装脚本运行期提前把所有.py编译成缓存字节码。这也是模块 docstring 中明确给出的场景说明见 Lib/compileall.py。从功能职责上看compileall是目录树级别的调度器而真正的单文件字节码生成由 py_compile 模块Lib/py_compile.py完成。本文关联文档在末尾 See Also 一节明确指向py_compile指出其职责是 Byte-compile a single source file。二者构成批量遍历 单文件编译的分层关系。平台可用性compileall 模块不可在 WebAssembly 平台上使用含 WASI、Emscripten这是由官方文档 include 的 wasm-notavail 说明 声明的This module does not work or is not available on WebAssembly。对应的测试类EncodingTest也以skipIf(support.is_wasi, ...)方式跳过 WASI见 test_compileall.py。命令行使用python -m compileall模块可以脚本方式运行即python -m compileall。入口实现在main()Lib/compileall.py__main__会根据main()的返回值sys.exit编译全部成功返回 0否则返回 1。位置参数与默认行为python -m compileall [选项] directory ... file ...位置参数为要编译的文件或目录目录会被递归遍历其内所有源码文件。不传任何参数时等价于-l不递归作用于sys.path中的各个目录。实现上main()在compile_dests为空时调用compile_path(...)Lib/compileall.py后者遍历sys.path逐项调用compile_dir。选项含义-l不递归子目录只编译指定/隐含目录下的直接源码文件。实现上等价于maxlevels0store_const写入destmaxlevels见 Lib/compileall.py-f强制重建即使时间戳显示已是最新-q不打印已编译文件列表传一次-q仍打印错误信息传两次-qq连错误输出也完全抑制。argparse 中用actioncount实现多级 quietLib/compileall.py-d destdir在每个被编译文件的路径前拼接destdir。该路径用于编译期 traceback并会编入字节码文件当运行期源文件已不存在时traceback 与报错消息使用该记录路径-s strip_prefix从.pyc内记录路径中移除给定前缀使路径相对化典型用于剥离构建根目录可与-p连用不可与-d连用-p prepend_prefix在.pyc记录路径前追加前缀-p /用于把剥离后路径恢复为绝对路径可与-s连用不可与-d连用-x regex用正则搜索每个待编译文件的完整路径命中则跳过该文件-i list读取文件list把其中每一行追加为待编译的文件/目录list为-时从stdin逐行读取-b写入旧版legacy位置与命名的字节码文件可能覆盖其他 Python 版本产物默认写入 PEP 3147 布局允许多版本共存-r限定子目录最大递归层级指定后-l将被忽略python -m compileall dir -r 0等价于... -l。源码中-r优先级高于-l见 Lib/compileall.py-j N使用 N 个 worker 并行编译-j 0时使用os.process_cpu_count()得到的核心数--invalidation-mode [timestamp\|checked-hash\|unchecked-hash]控制生成的.pyc在运行期失效判定方式详见下文专节-o level以指定优化级别编译可多次指定如compileall -o 1 -o 2一次生成多份优化字节码。默认-1即沿用解释器自身的优化级别见 Lib/compileall.py-e dir忽略指向给定目录之外的符号链接--hardlink-dupes当不同优化级别的两个.pyc内容相同时用硬链接合并重复文件选项之间的约束与互斥源码中main()与核心函数对这些约束做了严格校验命令行的非法组合会直接报错退出-d不能与-s/-p同时使用。compile_dir/compile_file入口会抛出ValueError(Destination dir (ddir) cannot be used in combination with stripdir or prependdir)Lib/compileall.py命令行层面parser.error提前拦截Lib/compileall.py。--hardlink-dupes只有在指定多于一个优化级别时才有意义单级别使用会报错parser.errorLib/compileall.py对应的 API 入口则抛ValueErrorLib/compileall.py。-j的 worker 数小于 0 时compile_dir抛ValueError(workers must be greater or equal to 0)Lib/compileall.py。与解释器优化选项的配合官方文档特别指出命令行没有用于控制compile函数优化级别的独立选项因为解释器已提供该机制——直接使用python -O -m compileall即可让被编译代码带上-O级别去掉 assert、debug分支等。同时compile函数会尊重运行期sys.pycache_prefix设置。也就是说预编译生成的字节码缓存只有在编译时使用的sys.pycache_prefix如有与运行期一致的前提下才有意义否则运行期仍会在新前缀下重新寻找/生成缓存。.pyc 失效机制与 --invalidation-mode这是 compileall 最值得深入理解的参数。Python 加载.pyc前必须先确认缓存与.py源文件同步官方文档 Cached bytecode invalidation 一节阐述了完整规则timestamp默认写缓存时记录源文件的最后修改时间与大小运行期把缓存内嵌的元数据与源文件元数据比对来判定失效。hash-based缓存嵌入的是源文件内容的哈希而非时间戳包含两种变体checked-hash运行期重新哈希源文件并与缓存哈希比对发现失效会重新生成并覆写缓存。unchecked-hash只要缓存存在就假定其有效。hash-based 缓存的运行期校验行为可被解释器启动参数--check-hash-based-pycs覆盖见 import.rst。在 compileall 语境中--invalidation-mode的默认值并非写死环境变量SOURCE_DATE_EPOCH未设置→ 默认timestampSOURCE_DATE_EPOCH已设置→ 默认checked-hash。这一默认值逻辑直接映射到py_compile的_get_default_invalidation_mode()Lib/py_compile.py用于保证可复现构建设置了SOURCE_DATE_EPOCH的构建中时间戳不再可靠因此回退到内容哈希模式。对应参数内部实现于 Lib/py_compile.pytimestamp模式调用_code_to_timestamp_pyc写入源文件 mtime 与 sizehash 模式则用importlib.util.source_hash(source_bytes)计算哈希后调用_code_to_hash_pyc其中布尔参数区分 checked/unchecked 变体。模式枚举定义于 PycInvalidationModeTIMESTAMP1、CHECKED_HASH2、UNCHECKED_HASH3命令行以--invalidation-mode [timestamp|checked-hash|unchecked-hash]三段取值经字符串规范化后映射回枚举Lib/compileall.py。版本演进速览版本变化3.2新增-i、-b、-h选项引入compile_filecompile_dir/compile_path新增legacy、optimize参数3.5新增-j、-r、-qq-q变为多级取值-b只产出.pyc不再产出.pyo新增workers参数3.7新增--invalidation-modehash-based.pyc首次出现见 import.rst3.8workers0改为自动选择最优核心数3.9新增-s、-p、-e、--hardlink-dupes默认递归深度由 10 提升为sys.getrecursionlimit()-o支持多次指定输出位置与命名PEP 3147 vs legacycompileall 默认将字节码写入PEP 3147位置与命名——即__pycache__/目录下形如module.cpython-313.pyc的文件使不同 CPython 版本的字节码可以共存。-blegacy 模式则退回到与源文件同目录的module.pyc旧布局可能覆盖其他 Python 版本生成的同名文件。在实现层目标路径由importlib.util.cache_from_source(fullname, optimizationopt)计算其中优化级别 0 映射为空串、1级别映射为对应优化标记字符串落在非 legacy 布局下Lib/compileall.py。此外还有一个值得注意的边界若sys.implementation.cache_tag不存在无缓存标签的自定义实现非 legacy 模式无法推导.pyc路径compile_file会打印提示并返回失败而不抛异常Lib/compileall.py。增量跳过的判断逻辑不指定-f时compileall 会尝试跳过已是最新的文件。compile_file内实现为读取源文件 mtime构造 12 字节期望头struct.pack(4sLL, importlib.util.MAGIC_NUMBER, 0, mtime 0xFFFF_FFFF)与各目标.pyc文件头逐一比对只有全部一致才返回成功并跳过Lib/compileall.py。这正是timestamp 校验在编译侧的镜像头部不匹配魔术字、mtime 任一不同即判定需要重编译。递归、并行与目录遍历实现compile_dir的目录遍历由生成器_walk_dir完成Lib/compileall.py要点包括目录条目按名称排序保证输出与编译顺序确定自动跳过__pycache__目录仅在maxlevels 0时对非符号链接目录递归递归深度每层递减maxlevels为None时取sys.getrecursionlimit()Lib/compileall.py符号链接文件会被yield作为文件处理但符号链接目录不会被递归深入not os.path.islink(fullname)条件。并行方面workers ! 1时先通过_check_system_limits()探测平台是否支持进程池不支持则回退为单线程顺序编译支持时若当前启动方式为fork则改用forkserver上下文随后用ProcessPoolExecutor以chunksize4分发compile_fileLib/compileall.py。workers0时把None交给池执行器自动按 CPU 数决定。整个目录的成败由min(results)聚合——任一文件失败即整体为假。公开函数 APIcompile_dir / compile_file / compile_path命令行是这些函数的薄封装模块的__all__导出三者Lib/compileall.py。全部函数在成功编译所有文件时返回真值任一失败返回假值。compile_dir(dir, ...)compile_dir(dir, maxlevelsNone, ddirNone, forceFalse, rxNone, quiet0, legacyFalse, optimize-1, workers1, invalidation_modeNone, *, stripdirNone, prependdirNone, limit_sl_destNone, hardlink_dupesFalse)递归下降编译dir目录树中所有.py。参数语义maxlevels递归深度上限默认sys.getrecursionlimit()ddir拼接到每个文件编译路径前用于编译期 traceback并编入字节码供源文件缺失时的运行期 traceback 使用force为真时即使时间戳最新也强制重编译rx接收一个re.Pattern对象其search方法作用于每个待编译文件的完整路径返回真值则跳过quietFalse/0默认打印文件名等信息到标准输出1只打印错误2完全静默legacy为真写入旧版位置/命名可能覆盖他版本字节码默认为 PEP 3147 布局optimize传给内置compile的优化级别也接受优化级别序列一次调用产出该文件的多份不同优化字节码workers并行编译使用的进程数默认不并行平台不支持且传入了该参数时回退串行0表示使用系统核心数小于 0 抛ValueErrorinvalidation_modepy_compile.PycInvalidationMode枚举成员控制.pyc运行期失效方式stripdir/prependdir/limit_sl_dest对应命令行-s/-p/-e可用str或os.PathLikehardlink_dupes为真时不同优化级别内容相同的.pyc以硬链接合并。路径参数兼容os.PathLike即可以直接传入pathlib.Path对象。compile_file(fullname, ...)compile_file(fullname, ddirNone, forceFalse, rxNone, quiet0, legacyFalse, optimize-1, invalidation_modeNone, *, stripdirNone, prependdirNone, limit_sl_destNone, hardlink_dupesFalse)编译单个路径为fullname的文件参数含义与compile_dir相同。与目录版本的区别在于rx命中时该文件不编译且直接返回True视为跳过成功。compile_path(skip_curdirTrue, ...)compile_path(skip_curdirTrue, maxlevels0, forceFalse, quiet0, legacyFalse, optimize-1, invalidation_modeNone)沿sys.path编译其中找到的所有.py。要点skip_curdir为真默认时跳过当前目录参数透传给compile_dir但与其他函数不同其maxlevels默认值为0不递归。官方文档标准示例官方文档给出了一个可直接运行的完整示例重编译Lib/整棵子树含排除.svn目录与Path对象用法import compileall compileall.compile_dir(Lib/, forceTrue) # 执行同样的编译但排除 .svn 目录中的文件 import re compileall.compile_dir(Lib/, rxre.compile(r[/\\][.]svn), forceTrue) # pathlib.Path 对象同样可用 import pathlib compileall.compile_dir(pathlib.Path(Lib/), forceTrue)实战场景与进阶技巧1. 读取待编译清单-i-i允许把文件/目录清单以每行一条的方式写入文件再传给 compileall清单为-时从 stdin 读取。实现于main()Lib/compileall.py按utf-8读取每行strip()后追加进编译目标列表读取失败时打印Error reading file list ...并返回失败。典型流水线用法find src -name *.py files.txt python -m compileall -i files.txt -q2. 路径重写-s / -p / -d 的打包语义跨机器打包如构建产物拷贝到部署机时源码绝对路径不应被编入.pyc。-s剥离构建根-p追加目标前缀二者可组合-d则直接指定一个展示用目录。注意三者的共同限制-d与-s/-p互斥。实现上stripdir按路径段前缀匹配并左剥不匹配时打印提示并忽略prependdir随后前插Lib/compileall.py。标准库测试覆盖了strip_only、prepend_only、strip_and_prepend、strip_prepend_and_ddir错误组合等分支见 test_compileall.py。3. 一次编译多个优化级别-opython -m compileall -o 0 -o 1 -o 2 mypkg/optimize序列经sorted(set(...))去重排序后逐级产出module.cpython-313.opt-1.pyc等文件Lib/compileall.py。-o不指定时默认[-1]即沿用解释器优化级别。若配合--hardlink-dupes只有至少两个优化级别时才可能产生内容相同未使用 assert/__debug__时各优化级字节码可能完全一致的.pyc去重场景——此时 compileall 会os.unlink重复文件并用os.link建立到前一版本的硬链接Lib/compileall.py。4. 符号链接与目录遍历安全-e-e dir用于忽略指向目录外部的符号链接防止编译过程逃逸出预期目录。判断逻辑是当目标是符号链接且Path(limit_sl_dest).resolve()不在Path(fullname).resolve().parents中时跳过Lib/compileall.py。测试 test_ignore_symlink_destination 验证了目录内链接被编译、指向目录外的链接被跳过的行为。5. 排除文件-x与强制重编译-f# 跳过路径中匹配 /test/ 的文件 python -m compileall -x /test/ src/ # 忽略时间戳全部强制重编 python -m compileall -f -q Lib/-x的正则经re.compile编译后其search作用于完整路径命中即跳过Lib/compileall.py-f会绕过12 字节头比对的最新性检查。注意若同时用-o指定多个级别-f会重写全部级别的缓存。6. 只编译单层-l / -r 0python -m compileall -l Lib/ # 只编 Lib/ 直接子文件 python -m compileall -r 0 Lib/ # 等价写法-r 优先于 -l python -m compileall -r 2 Lib/ # 限定最多下钻 2 层从源码看整体调用链一次python -m compileall src/ -j 0 -o 1 -o 2的完整调用链可概括为main()解析 argparse 参数做互斥与取值范围校验对每个目录目标调用compile_dir对每个文件目标调用compile_filecompile_dir用_walk_dir递归枚举.py跳过__pycache__与符号链接目录按workers决定走ProcessPoolExecutor并行分支还是串行循环每个文件进入compile_file依次处理 cache_tag 检查、stripdir/prependdir 路径重写、优化级别集合、rx排除、limit_sl_dest符号链接边界、12 字节头最新性判定真正编译动作委托py_compile.compile(fullname, cfile, dfile, True, ...)doraiseTrue——若缓存已过期则调用内置compile并序列化为.pyc随后以原子写方式落盘py_compile.compile依invalidation_mode决定写入 timestamp 头还是 source_hash 头checked/unchecked任一层失败都会向上聚合最终sys.exit(非 0)。测试覆盖与质量保障仓库中与本文档对应的完整测试套件位于 Lib/test/test_compileall.py主要测试类含多组场景可按需对照基础行为test_compile_files、test_mtime、test_magic_number、test_compile_path、test_no_pycache_in_non_packageCLI 语义test_no_args_compiles_path、test_legacy_paths、test_force、test_recursion_control、test_recursion_limit、test_quiet/test_silent、test_regexp、test_multiple_dirs文件清单test_include_bad_file、test_include_file_with_arg、test_include_on_stdin多优化级别与硬链接test_multiple_optimization_levels、test_hardlink_bad_args、test_hardlink、test_duplicated_levels、test_recompilation并行test_workers、test_workers_available_cores、test_compile_workers_non_positive路径重写与符号链接test_strip_only/test_prepend_only/test_strip_and_prepend、test_ignore_symlink_destination环境敏感性套件通过元类同时以SOURCE_DATE_EPOCH设置与否两种形态运行CompileallTestsWithSourceEpoch/CompileallTestsWithoutSourceEpoch见 test_compileall.py确保失效模式默认值切换被完整验证。小结compileall是 CPython 打包与安装链路上连接源码分发与字节码缓存的关键工具命令行形态适合安装脚本与 CI函数形态适合嵌入你自己的构建代码。理解其默认值背后的规则PEP 3147 布局、timestamp/hash 失效、SOURCE_DATE_EPOCH联动、sys.pycache_prefix一致性有助于在多用户共享安装、可复现构建、交叉打包等场景中正确使用它。若需单文件级编译或更细的缓存写入控制可进一步研究其底层模块 py_compile 的compile()、PycInvalidationMode与PyCompileError。【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpython创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
CPython compileall 模块完全指南批量字节码编译、.pyc 缓存管理与目录树编译实操【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpythoncompileall是 CPython 标准库中面向库安装场景的批处理编译工具它沿目录树递归收集.py源文件并逐个编译为字节码缓存.pyc使没有库目录写权限的用户也能直接受益于预编译缓存。阅读本篇后你将完整掌握python -m compileall的全部命令行选项含-d/-s/-p路径重写、-j并行、--invalidation-mode与--hardlink-dupes等能熟练调用 compile_dir / compile_file / compile_path 三大公开函数并理解SOURCE_DATE_EPOCH、PEP 3147 布局与运行时.pyc校验等底层机制。compileall 在 CPython 中的作用compileall的核心价值在 Python 官方文档与源码模块 docstring 中表述得非常一致Byte-compile Python libraries字节码编译 Python 库。当一个 Python 安装目录被多个用户共享时普通用户可能没有源码目录的写权限也就无法在 import 时由解释器自动落盘.pyc——每次启动都得现场编译程序启动会明显变慢。解决方案正是在库安装阶段打包与安装脚本运行期提前把所有.py编译成缓存字节码。这也是模块 docstring 中明确给出的场景说明见 Lib/compileall.py。从功能职责上看compileall是目录树级别的调度器而真正的单文件字节码生成由 py_compile 模块Lib/py_compile.py完成。本文关联文档在末尾 See Also 一节明确指向py_compile指出其职责是 Byte-compile a single source file。二者构成批量遍历 单文件编译的分层关系。平台可用性compileall 模块不可在 WebAssembly 平台上使用含 WASI、Emscripten这是由官方文档 include 的 wasm-notavail 说明 声明的This module does not work or is not available on WebAssembly。对应的测试类EncodingTest也以skipIf(support.is_wasi, ...)方式跳过 WASI见 test_compileall.py。命令行使用python -m compileall模块可以脚本方式运行即python -m compileall。入口实现在main()Lib/compileall.py__main__会根据main()的返回值sys.exit编译全部成功返回 0否则返回 1。位置参数与默认行为python -m compileall [选项] directory ... file ...位置参数为要编译的文件或目录目录会被递归遍历其内所有源码文件。不传任何参数时等价于-l不递归作用于sys.path中的各个目录。实现上main()在compile_dests为空时调用compile_path(...)Lib/compileall.py后者遍历sys.path逐项调用compile_dir。选项含义-l不递归子目录只编译指定/隐含目录下的直接源码文件。实现上等价于maxlevels0store_const写入destmaxlevels见 Lib/compileall.py-f强制重建即使时间戳显示已是最新-q不打印已编译文件列表传一次-q仍打印错误信息传两次-qq连错误输出也完全抑制。argparse 中用actioncount实现多级 quietLib/compileall.py-d destdir在每个被编译文件的路径前拼接destdir。该路径用于编译期 traceback并会编入字节码文件当运行期源文件已不存在时traceback 与报错消息使用该记录路径-s strip_prefix从.pyc内记录路径中移除给定前缀使路径相对化典型用于剥离构建根目录可与-p连用不可与-d连用-p prepend_prefix在.pyc记录路径前追加前缀-p /用于把剥离后路径恢复为绝对路径可与-s连用不可与-d连用-x regex用正则搜索每个待编译文件的完整路径命中则跳过该文件-i list读取文件list把其中每一行追加为待编译的文件/目录list为-时从stdin逐行读取-b写入旧版legacy位置与命名的字节码文件可能覆盖其他 Python 版本产物默认写入 PEP 3147 布局允许多版本共存-r限定子目录最大递归层级指定后-l将被忽略python -m compileall dir -r 0等价于... -l。源码中-r优先级高于-l见 Lib/compileall.py-j N使用 N 个 worker 并行编译-j 0时使用os.process_cpu_count()得到的核心数--invalidation-mode [timestamp\|checked-hash\|unchecked-hash]控制生成的.pyc在运行期失效判定方式详见下文专节-o level以指定优化级别编译可多次指定如compileall -o 1 -o 2一次生成多份优化字节码。默认-1即沿用解释器自身的优化级别见 Lib/compileall.py-e dir忽略指向给定目录之外的符号链接--hardlink-dupes当不同优化级别的两个.pyc内容相同时用硬链接合并重复文件选项之间的约束与互斥源码中main()与核心函数对这些约束做了严格校验命令行的非法组合会直接报错退出-d不能与-s/-p同时使用。compile_dir/compile_file入口会抛出ValueError(Destination dir (ddir) cannot be used in combination with stripdir or prependdir)Lib/compileall.py命令行层面parser.error提前拦截Lib/compileall.py。--hardlink-dupes只有在指定多于一个优化级别时才有意义单级别使用会报错parser.errorLib/compileall.py对应的 API 入口则抛ValueErrorLib/compileall.py。-j的 worker 数小于 0 时compile_dir抛ValueError(workers must be greater or equal to 0)Lib/compileall.py。与解释器优化选项的配合官方文档特别指出命令行没有用于控制compile函数优化级别的独立选项因为解释器已提供该机制——直接使用python -O -m compileall即可让被编译代码带上-O级别去掉 assert、debug分支等。同时compile函数会尊重运行期sys.pycache_prefix设置。也就是说预编译生成的字节码缓存只有在编译时使用的sys.pycache_prefix如有与运行期一致的前提下才有意义否则运行期仍会在新前缀下重新寻找/生成缓存。.pyc 失效机制与 --invalidation-mode这是 compileall 最值得深入理解的参数。Python 加载.pyc前必须先确认缓存与.py源文件同步官方文档 Cached bytecode invalidation 一节阐述了完整规则timestamp默认写缓存时记录源文件的最后修改时间与大小运行期把缓存内嵌的元数据与源文件元数据比对来判定失效。hash-based缓存嵌入的是源文件内容的哈希而非时间戳包含两种变体checked-hash运行期重新哈希源文件并与缓存哈希比对发现失效会重新生成并覆写缓存。unchecked-hash只要缓存存在就假定其有效。hash-based 缓存的运行期校验行为可被解释器启动参数--check-hash-based-pycs覆盖见 import.rst。在 compileall 语境中--invalidation-mode的默认值并非写死环境变量SOURCE_DATE_EPOCH未设置→ 默认timestampSOURCE_DATE_EPOCH已设置→ 默认checked-hash。这一默认值逻辑直接映射到py_compile的_get_default_invalidation_mode()Lib/py_compile.py用于保证可复现构建设置了SOURCE_DATE_EPOCH的构建中时间戳不再可靠因此回退到内容哈希模式。对应参数内部实现于 Lib/py_compile.pytimestamp模式调用_code_to_timestamp_pyc写入源文件 mtime 与 sizehash 模式则用importlib.util.source_hash(source_bytes)计算哈希后调用_code_to_hash_pyc其中布尔参数区分 checked/unchecked 变体。模式枚举定义于 PycInvalidationModeTIMESTAMP1、CHECKED_HASH2、UNCHECKED_HASH3命令行以--invalidation-mode [timestamp|checked-hash|unchecked-hash]三段取值经字符串规范化后映射回枚举Lib/compileall.py。版本演进速览版本变化3.2新增-i、-b、-h选项引入compile_filecompile_dir/compile_path新增legacy、optimize参数3.5新增-j、-r、-qq-q变为多级取值-b只产出.pyc不再产出.pyo新增workers参数3.7新增--invalidation-modehash-based.pyc首次出现见 import.rst3.8workers0改为自动选择最优核心数3.9新增-s、-p、-e、--hardlink-dupes默认递归深度由 10 提升为sys.getrecursionlimit()-o支持多次指定输出位置与命名PEP 3147 vs legacycompileall 默认将字节码写入PEP 3147位置与命名——即__pycache__/目录下形如module.cpython-313.pyc的文件使不同 CPython 版本的字节码可以共存。-blegacy 模式则退回到与源文件同目录的module.pyc旧布局可能覆盖其他 Python 版本生成的同名文件。在实现层目标路径由importlib.util.cache_from_source(fullname, optimizationopt)计算其中优化级别 0 映射为空串、1级别映射为对应优化标记字符串落在非 legacy 布局下Lib/compileall.py。此外还有一个值得注意的边界若sys.implementation.cache_tag不存在无缓存标签的自定义实现非 legacy 模式无法推导.pyc路径compile_file会打印提示并返回失败而不抛异常Lib/compileall.py。增量跳过的判断逻辑不指定-f时compileall 会尝试跳过已是最新的文件。compile_file内实现为读取源文件 mtime构造 12 字节期望头struct.pack(4sLL, importlib.util.MAGIC_NUMBER, 0, mtime 0xFFFF_FFFF)与各目标.pyc文件头逐一比对只有全部一致才返回成功并跳过Lib/compileall.py。这正是timestamp 校验在编译侧的镜像头部不匹配魔术字、mtime 任一不同即判定需要重编译。递归、并行与目录遍历实现compile_dir的目录遍历由生成器_walk_dir完成Lib/compileall.py要点包括目录条目按名称排序保证输出与编译顺序确定自动跳过__pycache__目录仅在maxlevels 0时对非符号链接目录递归递归深度每层递减maxlevels为None时取sys.getrecursionlimit()Lib/compileall.py符号链接文件会被yield作为文件处理但符号链接目录不会被递归深入not os.path.islink(fullname)条件。并行方面workers ! 1时先通过_check_system_limits()探测平台是否支持进程池不支持则回退为单线程顺序编译支持时若当前启动方式为fork则改用forkserver上下文随后用ProcessPoolExecutor以chunksize4分发compile_fileLib/compileall.py。workers0时把None交给池执行器自动按 CPU 数决定。整个目录的成败由min(results)聚合——任一文件失败即整体为假。公开函数 APIcompile_dir / compile_file / compile_path命令行是这些函数的薄封装模块的__all__导出三者Lib/compileall.py。全部函数在成功编译所有文件时返回真值任一失败返回假值。compile_dir(dir, ...)compile_dir(dir, maxlevelsNone, ddirNone, forceFalse, rxNone, quiet0, legacyFalse, optimize-1, workers1, invalidation_modeNone, *, stripdirNone, prependdirNone, limit_sl_destNone, hardlink_dupesFalse)递归下降编译dir目录树中所有.py。参数语义maxlevels递归深度上限默认sys.getrecursionlimit()ddir拼接到每个文件编译路径前用于编译期 traceback并编入字节码供源文件缺失时的运行期 traceback 使用force为真时即使时间戳最新也强制重编译rx接收一个re.Pattern对象其search方法作用于每个待编译文件的完整路径返回真值则跳过quietFalse/0默认打印文件名等信息到标准输出1只打印错误2完全静默legacy为真写入旧版位置/命名可能覆盖他版本字节码默认为 PEP 3147 布局optimize传给内置compile的优化级别也接受优化级别序列一次调用产出该文件的多份不同优化字节码workers并行编译使用的进程数默认不并行平台不支持且传入了该参数时回退串行0表示使用系统核心数小于 0 抛ValueErrorinvalidation_modepy_compile.PycInvalidationMode枚举成员控制.pyc运行期失效方式stripdir/prependdir/limit_sl_dest对应命令行-s/-p/-e可用str或os.PathLikehardlink_dupes为真时不同优化级别内容相同的.pyc以硬链接合并。路径参数兼容os.PathLike即可以直接传入pathlib.Path对象。compile_file(fullname, ...)compile_file(fullname, ddirNone, forceFalse, rxNone, quiet0, legacyFalse, optimize-1, invalidation_modeNone, *, stripdirNone, prependdirNone, limit_sl_destNone, hardlink_dupesFalse)编译单个路径为fullname的文件参数含义与compile_dir相同。与目录版本的区别在于rx命中时该文件不编译且直接返回True视为跳过成功。compile_path(skip_curdirTrue, ...)compile_path(skip_curdirTrue, maxlevels0, forceFalse, quiet0, legacyFalse, optimize-1, invalidation_modeNone)沿sys.path编译其中找到的所有.py。要点skip_curdir为真默认时跳过当前目录参数透传给compile_dir但与其他函数不同其maxlevels默认值为0不递归。官方文档标准示例官方文档给出了一个可直接运行的完整示例重编译Lib/整棵子树含排除.svn目录与Path对象用法import compileall compileall.compile_dir(Lib/, forceTrue) # 执行同样的编译但排除 .svn 目录中的文件 import re compileall.compile_dir(Lib/, rxre.compile(r[/\\][.]svn), forceTrue) # pathlib.Path 对象同样可用 import pathlib compileall.compile_dir(pathlib.Path(Lib/), forceTrue)实战场景与进阶技巧1. 读取待编译清单-i-i允许把文件/目录清单以每行一条的方式写入文件再传给 compileall清单为-时从 stdin 读取。实现于main()Lib/compileall.py按utf-8读取每行strip()后追加进编译目标列表读取失败时打印Error reading file list ...并返回失败。典型流水线用法find src -name *.py files.txt python -m compileall -i files.txt -q2. 路径重写-s / -p / -d 的打包语义跨机器打包如构建产物拷贝到部署机时源码绝对路径不应被编入.pyc。-s剥离构建根-p追加目标前缀二者可组合-d则直接指定一个展示用目录。注意三者的共同限制-d与-s/-p互斥。实现上stripdir按路径段前缀匹配并左剥不匹配时打印提示并忽略prependdir随后前插Lib/compileall.py。标准库测试覆盖了strip_only、prepend_only、strip_and_prepend、strip_prepend_and_ddir错误组合等分支见 test_compileall.py。3. 一次编译多个优化级别-opython -m compileall -o 0 -o 1 -o 2 mypkg/optimize序列经sorted(set(...))去重排序后逐级产出module.cpython-313.opt-1.pyc等文件Lib/compileall.py。-o不指定时默认[-1]即沿用解释器优化级别。若配合--hardlink-dupes只有至少两个优化级别时才可能产生内容相同未使用 assert/__debug__时各优化级字节码可能完全一致的.pyc去重场景——此时 compileall 会os.unlink重复文件并用os.link建立到前一版本的硬链接Lib/compileall.py。4. 符号链接与目录遍历安全-e-e dir用于忽略指向目录外部的符号链接防止编译过程逃逸出预期目录。判断逻辑是当目标是符号链接且Path(limit_sl_dest).resolve()不在Path(fullname).resolve().parents中时跳过Lib/compileall.py。测试 test_ignore_symlink_destination 验证了目录内链接被编译、指向目录外的链接被跳过的行为。5. 排除文件-x与强制重编译-f# 跳过路径中匹配 /test/ 的文件 python -m compileall -x /test/ src/ # 忽略时间戳全部强制重编 python -m compileall -f -q Lib/-x的正则经re.compile编译后其search作用于完整路径命中即跳过Lib/compileall.py-f会绕过12 字节头比对的最新性检查。注意若同时用-o指定多个级别-f会重写全部级别的缓存。6. 只编译单层-l / -r 0python -m compileall -l Lib/ # 只编 Lib/ 直接子文件 python -m compileall -r 0 Lib/ # 等价写法-r 优先于 -l python -m compileall -r 2 Lib/ # 限定最多下钻 2 层从源码看整体调用链一次python -m compileall src/ -j 0 -o 1 -o 2的完整调用链可概括为main()解析 argparse 参数做互斥与取值范围校验对每个目录目标调用compile_dir对每个文件目标调用compile_filecompile_dir用_walk_dir递归枚举.py跳过__pycache__与符号链接目录按workers决定走ProcessPoolExecutor并行分支还是串行循环每个文件进入compile_file依次处理 cache_tag 检查、stripdir/prependdir 路径重写、优化级别集合、rx排除、limit_sl_dest符号链接边界、12 字节头最新性判定真正编译动作委托py_compile.compile(fullname, cfile, dfile, True, ...)doraiseTrue——若缓存已过期则调用内置compile并序列化为.pyc随后以原子写方式落盘py_compile.compile依invalidation_mode决定写入 timestamp 头还是 source_hash 头checked/unchecked任一层失败都会向上聚合最终sys.exit(非 0)。测试覆盖与质量保障仓库中与本文档对应的完整测试套件位于 Lib/test/test_compileall.py主要测试类含多组场景可按需对照基础行为test_compile_files、test_mtime、test_magic_number、test_compile_path、test_no_pycache_in_non_packageCLI 语义test_no_args_compiles_path、test_legacy_paths、test_force、test_recursion_control、test_recursion_limit、test_quiet/test_silent、test_regexp、test_multiple_dirs文件清单test_include_bad_file、test_include_file_with_arg、test_include_on_stdin多优化级别与硬链接test_multiple_optimization_levels、test_hardlink_bad_args、test_hardlink、test_duplicated_levels、test_recompilation并行test_workers、test_workers_available_cores、test_compile_workers_non_positive路径重写与符号链接test_strip_only/test_prepend_only/test_strip_and_prepend、test_ignore_symlink_destination环境敏感性套件通过元类同时以SOURCE_DATE_EPOCH设置与否两种形态运行CompileallTestsWithSourceEpoch/CompileallTestsWithoutSourceEpoch见 test_compileall.py确保失效模式默认值切换被完整验证。小结compileall是 CPython 打包与安装链路上连接源码分发与字节码缓存的关键工具命令行形态适合安装脚本与 CI函数形态适合嵌入你自己的构建代码。理解其默认值背后的规则PEP 3147 布局、timestamp/hash 失效、SOURCE_DATE_EPOCH联动、sys.pycache_prefix一致性有助于在多用户共享安装、可复现构建、交叉打包等场景中正确使用它。若需单文件级编译或更细的缓存写入控制可进一步研究其底层模块 py_compile 的compile()、PycInvalidationMode与PyCompileError。【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpython创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
