Jupyter Packaging

:warning: We recommend using Hatch Jupyter Builder instead of Jupyter Packaging for new and existing projects. See the blog post Packaging for Jupyter in 2022.

About

Tools to help build and install Jupyter Python packages that require a pre-build step that may include JavaScript build steps.

Install

pip install jupyter-packaging

Usage

There are three ways to use jupyter-packaging in another package. In general, you should not depend on jupyter_packaging as a runtime dependency, only as a build dependency.

As a Build Requirement

Use a pyproject.toml file as outlined in pep-518. An example:

[build-system]
requires = ["jupyter_packaging>=0.10,<2"]
build-backend = "setuptools.build_meta"

Below is an example setup.py using the above config. It assumes the rest of your metadata is in setup.cfg. We wrap the import in a try/catch to allow the file to be run without jupyter_packaging so that python setup.py can be run directly when not building.

from setuptools import setup
try:     from jupyterpackaging import wrapinstallers, npm_builder     builder = npm_builder()     cmdclass = wrapinstallers(predevelop=builder, pre_dist=builder) except ImportError:     cmdclass = {}
setup(cmdclass=cmdclass))

As a Build Backend

Use the jupyter_packaging build backend. The pre-build command is specified as metadata in pyproject.toml:

[build-system]
requires = ["jupyter_packaging>=0.10,<2"]
build-backend = "jupyterpackaging.buildapi"
[tool.jupyter-packaging.builder] factory = "jupyterpackaging.npmbuilder"
[tool.jupyter-packaging.build-args] build_cmd = "build:src"

The corresponding setup.py would be greatly simplified:

from setuptools import setup
setup()

The tool.jupyter-packaging.builder section expects a func value that points to an importable module and a function with dot separators. If not given, no pre-build function will run.

The optional tool.jupyter-packaging.build-args sections accepts a dict of keyword arguments to give to the pre-build command.

The build backend does not handle the develop command (pip install -e .). If desired, you can wrap just that command:

import setuptools
try:     from jupyterpackaging import wrapinstallers, npm_builder     builder = npmbuilder(buildcmd="build:dev")     cmdclass = wrapinstallers(predevelop=builder) except ImportError:     cmdclass = {}
setup(cmdclass=cmdclass))

The optional tool.jupyter-packaging.options section accepts the following options:

• skip-if-exists: A list of local files whose presence causes the prebuild to skip
• ensured-targets: A list of local file paths that should exist when the dist commands are run

As a Vendored File

Vendor setupbase.py locally alongside setup.py and import the module directly.

import setuptools
from setupbase import wrapinstallers, npmbuilder
func = npm_builder()
cmdclass = wrapinstallers(postdevelop=func, pre_dist=func)
setup(cmdclass=cmdclass)

Usage Notes

• This package does not work with the deprecated python setup.py bdistwheel or python setup.py sdist commands, PyPA recommends using the build package (pip install build && python -m build .).
• We recommend using includepackagedata=True and MANIFEST.in to control the assets included in the package.
• Tools like check-manifest or manifix can be used to ensure the desired assets are included.
• Simple uses of datafiles can be handled in setup.cfg or in setup.py. If recursive directories are needed use getdata_files() from this package.
• Unfortunately datafiles are not supported in develop mode (a limitation of setuptools). You can work around it by doing a full install (pip install .) before the develop install (pip install -e .), or by adding a script to push the data files to sys.baseprefix.

git clone https://github.com/jupyter/jupyter-packaging.git
cd jupyter-packaging
pip install -e .[test]
pre-commit install

[build-system]
requires = ["jupyter_packaging@file://<path-to-git-checkout>"]
build-backend = "setuptools.build_meta"