Build ITK Module Python packages

ITK is organized into modules. Modules for ITK can be developed outside the ITK source tree as external modules. The external module can be made available in ITK’s CMake configuration by contributing it as a remote module. Python packages can also be generated for external modules and uploaded to the Python Package Index (PyPI)

This section describes how to create, build, and upload ITK external module Python packages to PyPI.

Prerequisites

Building wheels requires:

  • CMake
  • Git
  • C++ Compiler - Platform specific requirements are summarized in scikit-build documentation.
  • Python

Create the module

To create an ITK module with Python wrapping, first run cookiecutter:

python -m pip install cookiecutter
python -m cookiecutter gh:InsightSoftwareConsortium/ITKModuleTemplate
# Fill in the information requested at the prompts

Then, add your classes. Reference documentation on how to populate the module can be found in the ITK Software Guide.

GitHub automated CI package builds

Freely available continous integration (CI) testing services for open source repositories on GitHub can be used to generate Linux, macOS, and Windows Python packages for your module.

After enabling builds for the GitHub repository with a CircleCI, TravisCI, and AppVeyor account, Python wheel packages will be available with the continuous integration builds. These services use the configurations generated by the ITKModuleTemplate.

CircleCI Python wheels

Linux Python package wheel links can be found in the CircleCI Artifacts tab after expanding the available folders.

TravisCI Python wheels

macOS Python package wheels can be downloaded by visiting to the file.io link found in the build output. Note: this link may only be valid for the initial download.

AppVeyor Python wheels

Windows Python package wheel links can be found in the AppVeyor Artifacts tab.

Automated platform scripts

Automated scripts are available in this repository to build Python packages that are binary compatible with the Python distributions provided by Python.org, Anaconda, and package managers like apt or Homebrew. The following sections outline how to use the associated scripts for Linux, macOS, and Windows.

Once the builds are complete, Python packages will be available in the dist directory.

Linux

To build portable Python packages on Linux, first install Docker.

For the first local build, clone the ITKPythonPackage repository inside your and download the required ITK binary builds:

cd ~/ITKMyModule
git clone https://github.com/InsightSoftwareConsortium/ITKPythonPackage
./ITKPythonPackage/scripts/dockcross-manylinux-download-cache-and-build-module-wheels.sh

For subsequent builds, just call the build script:

./ITKPythonPackage/scripts/dockcross-manylinux-build-module-wheels.sh

macOS

First, install the Python.org macOS Python distributions. This step requires sudo:

cd ~/ITKMyModule
git clone https://github.com/InsightSoftwareConsortium/ITKPythonPackage
./ITKPythonPackage/scripts/macpython-install-python.sh

Then, build the wheels:

./ITKPythonPackage/scripts/macpython-build-wheels.sh

Windows

First, install Microsoft Visual Studio 2015, Git, and CMake, which should be added to the system PATH environmental variable.

Open a PowerShell terminal as Administrator, and install Python:

PS C:\> Set-ExecutionPolicy Unrestricted
PS C:\> $pythonArch = "64"
PS C:\> iex ((new-object net.webclient).DownloadString('https://raw.githubusercontent.com/scikit-build/scikit-ci-addons/master/windows/install-python.ps1'))

In a PowerShell prompt, run the windows-build-wheels.ps1 script:

PS C:\Windows> cd C:\ITKMyModule
PS C:\ITKMyModule> git clone https://github.com/InsightSoftwareConsortium/ITKPythonPackage.git IPP
PS C:\ITKMyModule> .\ITKPythonPackage\scripts\windows-download-cache-and-build-module-wheels.ps1

Upload the packages to PyPI

First, register for an account on PyPI.

Next, create a ~/.pypirc file with your login credentials:

[distutils]
index-servers =
  pypi
  pypitest

[pypi]
username=<your-username>
password=<your-password>

[pypitest]
repository=https://test.pypi.org/legacy/
username=<your-username>
password=<your-password>

where <your-username> and <your-password> correspond to your PyPI account.

Then, upload wheels to the testing server:

python -m pip install twine
python -m twine upload -r pypitest dist/*

Check out the packages on https://test.pypi.org/ the testing server.

Finally, upload the wheel packages to the production PyPI server:

python -m twine upload dist/*

Congratulations! Your packages can be installed with the commands:

python -m pip install --upgrade pip
python -m pip install itk-<yourmodulename>