Wheels de Python

Las Wheels de Python (*.whl) son la forma estándar de distribuir módulos de Python. Se encuentran soportadas en Blender para crear Extensiones de Python autocontenidas.

Pautas

  • By convention, always locate the files under ./wheels/.

Requisitos

  • Las Wheels deberán ser empacadas de forma intacta, con respecto al Índice de paquetes de Python.

  • Wheels must include their dependencies.

  • Los nombres de archivo de Wheels deberán coincidir con la especificación para distribución binaria de Python: ver la documentación. Las Wheels descargadas desde el *Índice de paquetes de Python respetarán esta convención.*

  • Use forward slashes as path separators when listing them on the manifest.

Cómo incorporar Wheels

Las Wheels de Python (*.whl) podrán ser empacadas usando los siguientes pasos.

Descarga de Wheels

Download the wheel to the directory ./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.

Update the Manifest

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.

Ejecución

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__)

Platform Builds

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

Ejemplo

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

Nota

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.