Tugger `PythonWheelBuilder` 完全指南:用 Starlark 声明式构建 Python Wheel(.whl)

原创2026-10-09 13:32:381,872 阅读
文章标签:开发工具CLI

Tugger PythonWheelBuilder 完全指南:用 Starlark 声明式构建 Python Wheel(.whl)

PythonWheelBuilder 是 Tugger 的 Starlark 方言中用于创建 Python wheel(.whl)文件的专用类型,它允许开发者在配置文件里通过"设置参数 + 注册文件内容"的方式,纯声明式地组装出一个符合 PEP 427 规范的 wheel 归档。读完本文,你将掌握该类型的全部实例属性与方法的用法、wheel 内部 .dist-info 文件的自动推导规则、文件名生成机制,以及 PyOxidizer 仓库中用它打包自身二进制分发的真实案例。

背景:wheel 是什么,为什么需要一个构建器类型

Python wheel(.whl)本质上是一个带有一组约定文件的 zip 压缩包,这些文件用于描述 wheel 本身以及被打包的实体(Python 包)。其格式规范由 PEP 427 定义,兼容性标签(compatibility tag)的结构则由 PEP 425 定义。PythonWheelBuilder 就是 Tugger 面向这一格式提供的构建器:它把"往 zip 里塞文件"这一底层工作封装成三个语义清晰的方法(add_file / add_file_dist_info / add_file_data),并自动补齐 wheel 必需的元数据文件。

在 Tugger 的 Starlark 全局类型清单(tugger/docs/tugger_starlark_globals.rst)中,PythonWheelBuilder 与 FileContent、FileManifest、WiXMSIBuilder 等类型并列,是整个方言面向发行物构建能力的重要一环。从项目历史(pyoxidizer/docs/pyoxidizer_history.rst)可以看到,该类型最初定位就是"低层次、无太多集成,但足以从文件内容创建 wheel",PyOxidizer 自身正是用它取代 maturin 来构建自己的 PyPI 分发的。

构造与核心概念

__init__(distribution, version)

通过传入 distribution(即 Python 包的名称)和 version(该 distribution 的版本)构造一个实例:

wheel = PythonWheelBuilder("pyoxidizer", "0.24.0")

在底层,Starlark 层的 PythonWheelBuilderValue(tugger/src/starlark/python_wheel_builder.rs)持有 Arc<Mutex<WheelBuilder>> 对核心引擎的引用;真正干活的是 python-packaging crate 中的 WheelBuilder(python-packaging/src/wheel_builder.rs)。两个实例的 Starlark 值克隆后仍共享同一底层状态,保证并发读写一致。

新建实例时,核心引擎会套用一组默认值(源码 python-packaging/src/wheel_builder.rs 可确认):

配置项 默认值 说明
python_tag "py3" Python 标签
abi_tag "none" ABI 标签
platform_tag "any" 平台标签
generator "rust-python-packaging" 写入 WHEEL 文件的生成器名称
root_is_purelib false 归档解压目标(platlib)
modified_time 实例创建时刻的 UTC 时间 zip 内文件的修改时间戳

由此,默认的兼容性标签即 py3-none-any。这只适合"纯 Python 代码、无二进制文件"的 wheel;一旦 wheel 包含二进制内容或对 Python 版本有特定要求,就必须修改相关属性。

实例属性详解

以下属性均可读写(除 wheel_file_name 为只读),对应源码中的 get_attr / set_attr 实现(tugger/src/starlark/python_wheel_builder.rs)。

build_tag(Optional[str])

wheel 的构建标签,构成文件名与元数据中额外的组成部分。通常发布版不会设置 build tag,只有开发中或预发布版本才使用。

tag(str)

wheel 的兼容性标签,等价于 {python_tag}-{abi_tag}-{platform_tag}。也可以直接给 tag 整体赋值,底层会用 splitn(3, '-') 拆成三段后分别设置三个子标签;如果字符串格式不对(缺少 python-abi-platform 三段),会抛出 PYTHON_WHEEL_BUILDER 错误码的运行时异常。

python_tag(str)

兼容性标签的 Python 标签部分,例如 py3 或 py39。

abi_tag(str)

兼容性标签的 ABI 标签部分,例如 none、abi3 或 cp39。

platform_tag(str)

兼容性标签的平台标签部分,例如 any、linux_x86_64、manylinux2010_x86_64、macosx_10_9_x86_64 等。

generator(str)

描述"是谁构建了这个 wheel"。该值会被写入自动生成的 .dist-info/WHEEL 文件的 Generator: 字段。PyOxidizer 在自家配置里将其设为 "PyOxidizer (%s)" % PYOXIDIZER_VERSION(见 pyoxidizer.bzl)。

root_is_purelib(bool)

对应 wheel 的 Root-Is-Purelib 设置。为 True 时,归档内普通位置的文件在安装时被解压到 Python 的 purelib 目录;为 False 时解压到 platlib。若 wheel 只含纯 Python 文件(无二进制),应设为 True。

modified_time(int)

zip 归档中所有文件的修改时间,单位是 UNIX epoch 秒。默认值为实例创建时刻。该属性对构建可复现性至关重要:同一 builder 实例生成的 zip 内容是确定性的;不同实例之间只要设置相同的 modified_time 并使用相同的输入设置与文件,产物也能完全一致。

wheel_file_name(只读 str)

按当前设置计算出的 wheel 文件名。它由 distribution、version、build tag 与兼容性标签推导而来。例如默认配置下构造 PythonWheelBuilder("package", "0.1"),该属性为 package-0.1-py3-none-any.whl(有测试用例佐证,见 tugger/src/starlark/python_wheel_builder.rs)。

向 wheel 中添加文件

wheel 内部的文件分三种去向,对应三个方法。三者共享同一套 path / directory 参数语义:都不传时,文件以 FileContent.filename 为名落到默认位置;传 path 时,它定义精确的归档内路径;传 directory 时,实际路径等价于 os.path.join(directory, file.filename)。path 与 directory 不能同时指定,否则报错(三个方法在 tugger/src/starlark/python_wheel_builder.rs 中均有此校验)。

add_file_dist_info(file, path=None, directory=None)

把 FileContent 放入所打包 distribution 的 .dist-info/ 目录。这个目录描述 wheel 自身与被打包实体。在核心引擎中,目录名实际是 {normalized_distribution}-{version}.dist-info(python-packaging/src/wheel_builder.rs),其中 distribution 会被小写化、- 替换为 _。

add_file_data(destination, file, path=None, directory=None)

把 FileContent 放入 .data/<destination>/ 目录。destination 是 Python 安装中众所周知的目录名,取值包括:

  • purelib:纯 Python 模块与字节码
  • platlib:平台相关的二进制扩展模块与其他二进制
  • headers:头文件
  • scripts:可执行脚本
  • data:其他数据

安装 wheel 时,.data/<destination>/ 下的文件会被移动到目标环境的对应路径。

add_file(file, path=None, directory=None)

把 FileContent 放到归档的其他任意位置。这类文件在安装时不作特殊处理,根据 Root-Is-Purelib 的值直接解压到 purelib 或 platlib。

三个方法接受的都是 FileContent 类型实例。该类型通过 path(引用现有文件系统路径)或 content + filename(内存中的字符串内容)构造,并可通过 executable 标记可执行权限,详见 tugger/docs/tugger_starlark_type_file_content.rst。

输出构建结果

to_file_content() -> FileContent

返回一个代表已构建 wheel 的 FileContent。返回实例的 filename 会被设置为符合当前设置的 wheel 文件名(如 package-0.1-py3-none-any.whl),其数据是一个包含规范 wheel 的 zip 归档。在 Starlark 测试中,该方法的返回值类型被断言为 FileContent(tugger/src/starlark/python_wheel_builder.rs)。

write_to_directory(path) -> str

把 .whl 文件写入 path 指定的目录并返回写入文件的路径。底层实现会先 create_dir_all 确保目录存在,再调用 write_wheel_into_directory(tugger/src/starlark/python_wheel_builder.rs)。需要注意:相对路径是相对于当前配置的构建目录(build path)解释的,而非进程的工作目录(这一行为在 pyoxidizer/docs/pyoxidizer_history.rst 的历史记录中有明确说明)。

build(target) -> ResolvedTarget

构建实例。等价于 write_to_directory(),区别是输出目录取名为 target 指定的目标的构建目录。返回值是 ResolvedTarget(run_mode 为 RunMode::None),表示"产物已就绪"。

.dist-info 元数据文件的自动推导

PythonWheelBuilder 在 wheel 创建时会根据当前设置自动推导生成三个 .dist-info/ 文件(逻辑见 python-packaging/src/wheel_builder.rs):

  • .dist-info/WHEEL:默认内容为 Wheel-Version: 1.0、Generator: <generator>、Root-Is-Purelib: <root_is_purelib>、Tag: <tag> 四行字段。若通过 add_file_dist_info 提供了自定义 WHEEL,则使用自定义内容。
  • .dist-info/METADATA:默认内容为 Metadata-Version: 2.1、Name: <distribution>、Version: <version>。同样可被自定义 METADATA 覆盖。
  • .dist-info/RECORD:始终由构建器自动生成,即使你手动提供了自定义 RECORD 文件也会被忽略并重新生成。生成逻辑对归档中每个文件计算 SHA-256 摘要(URL-safe、无填充的 base64 编码),按 路径,sha256=<digest>,<字节数> 格式逐行列出,最后追加一行 {dist_info}/RECORD,,。

这正是 tugger/docs/tugger_starlark_type_python_wheel_builder.rst 所述"默认自动推导、可自定义 WHEEL 与 METADATA、自定义 RECORD 无效"的底层实现依据。

文件名生成与归档细节

wheel 文件名遵循 PEP 427 的 {distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl 结构(python-packaging/src/wheel_builder.rs)。其中:

  • distribution 会被规范化(小写、- 转 _);
  • 每个组成部分会通过正则 [^\w\d.]+ 把非法字符替换为 _;
  • 只有设置了 build_tag 时才插入该段。

引擎的单元测试完整覆盖了各标签组合下的文件名变化,例如设置 python_tag="py39"、abi_tag="abi"、platform_tag="platform" 后文件名为 my_package-0.1-py39-abi-platform.whl,再设置 build_tag="build" 则变为 my_package-0.1-build-py3-none-any.whl(python-packaging/src/wheel_builder.rs)。

写出 zip 时还有两个值得注意的细节:

  1. 排序:.dist-info/ 下的文件被刻意排到最后,符合 PEP 427 的建议;
  2. 权限与时间戳:可执行文件在 zip 中标记为 Unix 权限 0o0755,普通文件为 0o0644;所有文件使用 modified_time 作为 zip 时间戳(python-packaging/src/wheel_builder.rs)。

此外,该引擎"几乎不做输入校验",构成一个格式良好的 wheel 是调用方的责任,可借助 auditwheel 等外部工具校验产物内容。

实战案例:PyOxidizer 用它发布自己的二进制 wheel

PyOxidizer 仓库根目录的 pyoxidizer.bzl 展示了该类型的完整用法——PyOxidizer 自己发布到 PyPI 的 wheel 正是用它构建的:

def make_wheel(platform_tag, target_triple):
    # PyOxidizer's wheel is simply the executable binary as a "script" file.
    wheel = PythonWheelBuilder("pyoxidizer", PYOXIDIZER_VERSION)
    wheel.generator = "PyOxidizer (%s)" % PYOXIDIZER_VERSION
    wheel.tag = "py3-none-%s" % platform_tag

    wheel.add_file_dist_info(FileContent(filename="METADATA", content=WHEEL_METADATA))

    path = "target/%s/release/pyoxidizer" % target_triple

    if "-windows-" in target_triple:
        path = "%s.exe" % path

    wheel.add_file_data("scripts", FileContent(path=path, executable=True))

    return wheel

(完整函数见 pyoxidizer.bzl。)随后通过 make_wheel_linux_x86_64、make_wheel_macos_aarch64 等辅助函数传入不同的 platform_tag 与 target triple,分别产出 manylinux2010_x86_64、manylinux2014_aarch64、macosx_10_9_x86_64、macosx_11_0_arm64、win32、win_amd64 等平台标签的二进制 wheel(pyoxidizer.bzl)。

这个案例展示了两个核心手法:

  1. tag = "py3-none-<platform>":因为 wheel 里放的是编译好的原生可执行文件,不再是纯 Python,所以把默认的 any 平台标签改成具体平台,同时保留 py3-none 的 Python/ABI 兼容性;
  2. 可执行脚本打包:把目标平台的 pyoxidizer(Windows 下为 .exe)可执行文件作为 FileContent(executable=True)通过 add_file_data("scripts", ...) 放入 .data/scripts/,安装后即被安置到环境的 scripts 目录。

自定义 METADATA 也在此例中体现:WHEEL_METADATA 字符串(pyoxidizer.bzl)提供了完整的 Metadata-Version: 2.1 头字段、作者、许可证、描述内容类型等信息,通过 add_file_dist_info 注入,覆盖默认的极简 METADATA。

使用建议与注意事项

  • 纯 Python 包直接用默认值:不修改任何标签即可产出 py3-none-any 的 wheel;一旦引入二进制内容,务必同步调整 python_tag / abi_tag / platform_tag(或直接设 tag)与 root_is_purelib。
  • 追求可复现构建:显式设置 modified_time 为一个固定值,配合一致的输入文件,即可让不同实例产出的 zip 字节完全一致。
  • 路径参数二选一:path 与 directory 不可同时传入;directory 本质是"目录前缀 + 文件名"的拼接。
  • 相对路径语义:write_to_directory 与 build 中的相对路径以当前构建目录为基准;FileContent(path=...) 的相对路径则以全局 CWD 变量为基准,二者基准不同,混用时需留意。
  • 低层次定位:该类型只负责产出 wheel 文件本身,不与其他 Starlark Python 类型联动,也不做格式校验,复杂包的元数据建议像 PyOxidizer 那样显式提供自定义 METADATA。

延伸阅读

登录后查看全文
PyOxidizer