Skip to main content

Blender distutils addon

Project description

This Python module adds a new command to distutils to build Blender addons: bdist_blender_addon. It also provides a simple mechanism to package extra modules not included with Blender’s Python distribution within the addon.

Example

See the info_example_distutils addon to see how this distutils module is used.

Installation

Installing the blender.distutils module

The module is available on PiPy and installable with pip.

$ pip install blender.distutils

It is suggested to add a requirements.txt file to the Blender addon plugin that lists the module dependencies.

# This is requirements.txt

# This module adds the setup.py bdist_blender_addon command

blender.distutils

# This module is required by the addon, but not distributed with blender
# bdist_blender_addon will ship it if with the addon
# Dependencies to be included are listed in setup.cfg

dateutils

Add a simple setup.py to the blender addon

The bdist_blender_addon is a distutils command. As such, a setup.py file is required. Addon name and version are defined by this file. I suggest using bumpversion to keep setup.py, bl_info and your git tags in sync.

The setup.py for a blender addon is actually quite straightforward. The install_requires argument should only list the first-level dependencies needed by the addon: those may require their own dependencies. The actual modules to be shipped with the addon are cherry picked in setup.cfg.

from setuptools import setup, find_packages

setup(
    name='info_example_distutils',
    version='1.0.0',
    description='Blender example distutils',
    long_description=open('README.md').read(),
    url='https://github.com/charlesfleche/blender.distutils/io_example_distutils',
    author='Charles Flèche',
    author_email='charles.fleche@free.fr',
    license='MIT',
    classifiers=[
        'Development Status :: 5 - Production/Stable',
        'Intended Audience :: End Users/Desktop',
        'Topic :: Multimedia :: Graphics :: 3D Modeling',
        'Topic :: Multimedia :: Graphics :: 3D Rendering',
        'License :: OSI Approved :: MIT License',
        'Programming Language :: Python :: 3 :: Only'
    ],
    packages=find_packages(),
    keywords='blender',

    # Here are listed first level dependencies needed by the module. Themselves
    # may require dependencies. The actual modules to be shipped with the addon
    # are cherry picked in setup.cfg
    install_requires=['dateutils']
)

Including third-party modules not shipped with blender

The bdist_blender_addon command allows to include additional python modules that are not shipped with Blender. These modules will be included in the root folder of the addon. Currently an explicit list of modules, including their dependencies, needs to be configured.

Cherry pick the modules to be shipped with the blender addon

The modules to be included to the blender addon are listed as an option of the [bdist_blender_addon] section in setup.cfg. This list includes all the modules and their dependencies.

# This is in setup.cfg

[bdist_blender_addon]

# Here are listed the modules (and their dependencies) to be shipped
# with the blender module. In this example the addon requires `dateutils`,
# which in turns requires `dateutil`, `pytz` and `six`.
addon_require = dateutil,dateutils,pytz,six

Include the additional modules folder in the addon code

The addon needs to explicitly register the path to third party modules. During development, those modules will be in a virtual environment. When the addon is installed in production, those modules will be at the root of the addon folder.

import pathlib
import os
import site
import sys


def third_party_modules_sitedir():
    # If we are in a VIRTUAL_ENV, while developing for example, we want the
    # addon to hit the modules installed in the virtual environment
    if 'VIRTUAL_ENV' in os.environ:
        env = pathlib.Path(os.environ['VIRTUAL_ENV'])
        v = sys.version_info
        path = env / 'lib/python{}.{}/site-packages'.format(v.major, v.minor)

    # However outside of a virtual environment, the additionnal modules not
    # shipped with Blender are expected to be found in the root folder of
    # the addon
    else:
        path = pathlib.Path(__file__).parent

    return str(path.resolve())

# The additionnal modules location (virtual env or addon folder) is
# appended here
site.addsitedir(third_party_modules_sitedir())

# This module is not part of the standard blender distribution
# It is shipped alongside the plugin when `python setup.py bdist_blender_addon`
import dateutils

Build the module

The bdist_blender_addon command will copy the addon code, copy the additional modules over, clean unneeded files (like the *.pyc bytecode files) and package them all in a versioned zip archive under the dist folder.

$ python setup.py bdist_blender_addon
running bdist_blender_addon
running build
running build_py
creating build/lib/info_example_distutils
copying info_example_distutils/__init__.py -> build/lib/info_example_distutils
creating build/lib/info_example_distutils/dateutil
[long list of files being copied or added to the addon zip archive]

$ ls dist/
info_example_distutils-v1.0.0.zip

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

blender.distutils-1.0.5.tar.gz (4.2 kB view details)

Uploaded Source

Built Distribution

blender.distutils-1.0.5-py3-none-any.whl (4.7 kB view details)

Uploaded Python 3

File details

Details for the file blender.distutils-1.0.5.tar.gz.

File metadata

File hashes

Hashes for blender.distutils-1.0.5.tar.gz
Algorithm Hash digest
SHA256 1b4b46449b1703ab4c69b003c11507735d66dfc2dcf4afbb6eee4a8ff869f7e5
MD5 803227dd4bf432ba6ed5d75c68fd779f
BLAKE2b-256 9fb05c4b5d41d45e80afd3a978fc9faed2c8f2264cdaf85bdc1345b8ef438ce3

See more details on using hashes here.

File details

Details for the file blender.distutils-1.0.5-py3-none-any.whl.

File metadata

File hashes

Hashes for blender.distutils-1.0.5-py3-none-any.whl
Algorithm Hash digest
SHA256 b69e03763271f000bd006d7ab007df2dc924558a46b30a96cfdf7e5659a9de3e
MD5 4a50ad491fd212f026904452fc5963d8
BLAKE2b-256 e2c158f2d79e4ff21d35f430d8edf18f99112d81c8bbfa3bb89c18720e33cd6a

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page