Python Wheel¶

待完善

Wheel 选择使用版本的指南。
制定一项关于如何处理 wheel 冲突版本的政策。

Python wheel (*.whl) 是发布 Python 模块的标准方式。Blender 中支持它们，以便制作独立的 Python 扩展。

指南¶

按照惯例，文件应位于 ./wheels/ 下。

要求¶

必须从 Python 包索引直接打包未修改的 Wheels 文件。
Wheels 必须包含其依赖项。
Wheels 文件名必须符合 Python 二进制发行版规范：参见文档。从 Python 包索引下载的 Wheels 将遵循此约定。
在清单中列出这些项目时，请使用正斜杠作为路径分隔符。

如何捆绑 Wheel¶

可通过以下步骤捆绑 Python wheel (*.whl)。

下载 Wheel

将 wheel 下载到目录 ./wheels/．

对于与平台无关的 wheel，此示例会下载 jsmin：

pip wheel jsmin -w ./wheels

对于包含二进制编译文件的 wheel，应包含所有支持平台的 wheel：

此示例下载了 pillow - 一款广受欢迎的图像处理模块。

pip download pillow --dest ./wheels --only-binary=:all: --python-version=3.11 --platform=macosx_11_0_arm64
pip download pillow --dest ./wheels --only-binary=:all: --python-version=3.11 --platform=manylinux_2_28_x86_64
pip download pillow --dest ./wheels --only-binary=:all: --python-version=3.11 --platform=win_amd64

可用平台标识符列于 pillow 下载页面上。

更新清单

在 blender_manifest.toml 文件中将 wheel 作为路径列表包含其中，例如：

wheels = [
   "./wheels/pillow-10.3.0-cp311-cp311-macosx_11_0_arm64.whl",
   "./wheels/pillow-10.3.0-cp311-cp311-manylinux_2_28_x86_64.whl",
   "./wheels/pillow-10.3.0-cp311-cp311-win_amd64.whl",
]

当前安装程序将把该程序包解压至扩展自身的 site-packages 目录下。

运行

安装扩展后，您可以在 Python 控制台中导入该模块并打印其位置，以确认该模块是否已加载：

import PIL
print(PIL.__file__)

平台构建¶

Wheel 会对扩展的大小产生显著影响。为缓解这一问题，可针对每个特定需求平台构建不同的扩展 zip 文件。

为此，您需要使用 build 命令中的 --split-platforms 选项。

blender --command extension build --split-platforms

例子¶

清单文件节选：

id = "my_addon_with_wheels"
version = "1.0.0"

platforms = ["windows-x64", "macos-x64"]
wheels = [
   "./wheels/pillow-10.3.0-cp311-cp311-macosx_11_0_arm64.whl",
   "./wheels/pillow-10.3.0-cp311-cp311-manylinux_2_28_x86_64.whl",
   "./wheels/pillow-10.3.0-cp311-cp311-win_amd64.whl",
]

从 --split-platforms 生成的文件：

my_addon_with_wheels-1.0.0-windows_x64.zip
my_addon_with_wheels-1.0.0-macos_x64.zip

Note

尽管存在仅适用于 Linux 的 wheel，但系统并未生成 Linux 专用的 zip 文件。这是由于 platforms 字段仅包含 Mac 和 Windows 系统。