Python Wheel

待完善

  • Wheel 选择使用版本的指南。

  • Finalize a policy for how conflicting versions of a wheel are handled.

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/。

For wheels that are platform independent this example downloads jsmin:

pip wheel jsmin -w ./wheels

For wheels that contain binary compiled files, wheels for all supported platforms should be included:

This example downloads pillow - the popular image manipulation module.

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

The available platform identifiers are listed on pillow's download page.

更新清单

In blender_manifest.toml include the wheels as a list of paths, e.g.

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",
]

Now installing the package will extract the wheel into the extensions own site-packages directory.

运行

Once the extension has been installed you can check the module is being loaded by importing it in the Python console and printing it's location:

import PIL
print(PIL.__file__)

平台构建

Wheels can severely impact the size of an extension. To mitigate this, it is possible to build different extension zip files for each unique required platform.

For this you need to use the --split-platforms option from the build command.

blender --command extension build --split-platforms

例子

Manifest file excerpt:

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",
]

Generated files from --split-platforms:

  • my_addon_with_wheels-1.0.0-windows_x64.zip

  • my_addon_with_wheels-1.0.0-macos_x64.zip

Note

Even though there is a Linux-only wheel present, no Linux zip file is generated. This happens because the platforms field only has Mac and Windows.