Jupyter Packaging

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 jupyter_packaging import wrap_installers, npm_builder
    builder = npm_builder()
    cmdclass = wrap_installers(pre_develop=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 = "jupyter_packaging.build_api"

[tool.jupyter-packaging.builder]
factory = "jupyter_packaging.npm_builder"

[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 jupyter_packaging import wrap_installers, npm_builder
    builder = npm_builder(build_cmd="build:dev")
    cmdclass = wrap_installers(pre_develop=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 wrap_installers, npm_builder
func = npm_builder()
cmdclass = wrap_installers(post_develop=func, pre_dist=func)
setup(cmdclass=cmdclass)

Usage Notes

This package does not work with the deprecated python setup.py bdist_wheel or python setup.py sdist commands, PyPA recommends using the build package (pip install build && python -m build .).
We recommend using include_package_data=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 data_files can be handled in setup.cfg or in setup.py. If recursive directories are needed use get_data_files() from this package.
Unfortunately data_files 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.base_prefix.

Development Install

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

You can test changes locally by creating a pyproject.toml with the following, replacing the local path to the git checkout:

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

Note: you need to run pip cache remove jupyter_packaging any time changes are made to prevent pip from using a cached version of the source.

Release files for jupyter-packaging 0.12.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jupyter-packaging 0.12.3
File	Size	Uploaded
jupyter_packaging-0.12.3.tar.gz	25.4 kB	Aug 25, 2022	Details

Built distribution (wheel)

Table of built distributions (wheels) for jupyter-packaging 0.12.3
File	Interpreter	ABI	Platform	Reset
jupyter_packaging-0.12.3-py3-none-any.whl 15.7 kB Aug 25, 2022	Python 3	none	any	Details

Total release size: 41.0 kB

Release files / jupyter_packaging-0.12.3.tar.gz

Download URL	jupyter_packaging-0.12.3.tar.gz
Size	25.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`9d9b2b63b97ffd67a8bc5391c32a421bc415b264a32c99e4d8d8dd31daae9cf4`
BLAKE2b-256 checksum How to use checksums	`25c5b0e154e6403c6790bb1e66acddf9787296a8196f5b14f4bb9e4c92b6734e`
Upload date	Aug 25, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.10.6`

Release files / jupyter_packaging-0.12.3-py3-none-any.whl

Download URL	jupyter_packaging-0.12.3-py3-none-any.whl
Size	15.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c1a376b23bcaced6dfc9ab0e924b015ce11552a1a5bccf783c6476957c538348`
BLAKE2b-256 checksum How to use checksums	`ddcb6c4c3e2219c2fe6fff6f9d4bda48da21951c3bd8f39b443a586f13173ea0`
Upload date	Aug 25, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.10.6`