Python Wheel¶

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

指南¶

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

要求¶

Wheels must be bundled unmodified from Python's package index.
Wheels must include their dependencies.
Wheels filenames must match Python's binary distribution specification: see docs. Wheels downloaded from Python's package index will follow this convention.
Use forward slashes as path separators when listing them on the manifest.

如何捆绑 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.13 --platform=macosx_11_0_arm64
pip download pillow --dest ./wheels --only-binary=:all: --python-version=3.13 --platform=manylinux_2_28_x86_64
pip download pillow --dest ./wheels --only-binary=:all: --python-version=3.13 --platform=win_amd64

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

更新清单

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

wheels = [
   "./wheels/pillow-12.1.0-cp313-cp313-macosx_11_0_arm64.whl",
   "./wheels/pillow-12.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
   "./wheels/pillow-12.1.0-cp313-cp313-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-12.1.0-cp313-cp313-macosx_11_0_arm64.whl",
   "./wheels/pillow-12.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
   "./wheels/pillow-12.1.0-cp313-cp313-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 系统。