Jupyter Packaging Utilities

0.12.3 · active · verified Sun Apr 12

Jupyter Packaging provides utility functions and `setuptools` build command classes to simplify the packaging of Jupyter applications and extensions, particularly those with front-end (JavaScript/TypeScript) assets. It helps integrate pre-build steps into the Python packaging process. The current version is 0.12.3, and it typically sees releases for bug fixes, maintenance, and enhancements related to packaging standards and dependencies.

Warnings

breaking When upgrading `setuptools` to version 61.0.0 or higher, projects using `jupyter-packaging` versions prior to 0.12.0 may encounter `ImportError` due to a change in the internal import path for `bdist_wheel`.
Fix: Upgrade `jupyter-packaging` to version 0.12.0 or later. Ensure your `setup.py` or `pyproject.toml` specifies a compatible `jupyter-packaging` version.
deprecated Support for Python 3.6 was dropped with the release of `jupyter-packaging` 0.11.0.
Fix: Ensure your project targets Python 3.7 or newer. Upgrade your Python environment if necessary.
gotcha Building Jupyter extensions with front-end assets typically requires Node.js and a package manager (npm or yarn) to be installed and available in the system's PATH, as `jupyter-packaging` will execute these tools.
Fix: Install Node.js (which includes npm) and optionally yarn in your build environment. Verify their availability by running `node -v` and `npm -v` (or `yarn -v`).
gotcha `jupyter-packaging` is primarily intended as a *build-time* dependency, not a *runtime* dependency. It should be listed in `build-system.requires` in `pyproject.toml` rather than `install_requires` in `setup.py` or `dependencies` in `pyproject.toml` for most projects.
Fix: Configure `jupyter-packaging` as a build requirement in your `pyproject.toml` (e.g., `requires = ["jupyter_packaging>=0.10,<2"]`) or ensure it's only installed in build environments.
gotcha `jupyter-packaging` does not support the deprecated `python setup.py bdist_wheel` or `python setup.py sdist` commands directly. The recommended approach for building distributions is to use the `build` package.
Fix: Instead of `python setup.py sdist` or `python setup.py bdist_wheel`, use `pip install build` followed by `python -m build .`.
gotcha Setuptools' `data_files` (often used for Jupyter configuration files) are not fully supported in editable (`pip install -e .`) mode.
Fix: For development installations, you might need to perform a full install (`pip install .`) before an editable install (`pip install -e .`), or manually link/copy data files into the appropriate locations.

Install

pip install jupyter-packaging Install latest version

Imports

wrap_installers
```
from jupyter_packaging import wrap_installers
```
Used to wrap setuptools commands like 'install' or 'develop' with pre- and post-build steps.
npm_builder
```
from jupyter_packaging import npm_builder
```
A utility builder class for executing Node.js package manager commands (npm or yarn) as part of the build process.
bdist_wheel
```
from setuptools.command.bdist_wheel import bdist_wheel
```
As of `setuptools` v61.0.0, `bdist_wheel` moved from the `wheel` package into `setuptools` itself. `jupyter-packaging` v0.12.0 updated its internal import path to reflect this, but older versions of `jupyter-packaging` might break if used with newer `setuptools` versions.

Quickstart

This quickstart demonstrates how to integrate `jupyter-packaging` into a `setup.py` file to handle front-end build steps for a Jupyter extension. It uses `npm_builder` to define pre-build commands for both development (`develop`) and distribution (`dist`) modes, ensuring that JavaScript/TypeScript assets are compiled before the Python package is installed or built. The `try/except ImportError` block allows the `setup.py` to be run even if `jupyter-packaging` is not installed, which can be useful during initial `sdist` creation or local testing.

from setuptools import setup
try:
    from jupyter_packaging import wrap_installers, npm_builder
    
    # Define the builder for npm commands
    # Assumes a package.json in the root that defines 'build' and 'build:dev' scripts
    builder = npm_builder(build_cmd='build', develop_cmd='build:dev')
    
    # Wrap the 'install' and 'develop' commands with the npm builder
    cmdclass = wrap_installers(pre_develop=builder, pre_dist=builder)
except ImportError:
    # Fallback for when jupyter_packaging is not available (e.g., during sdist build)
    cmdclass = {}

setup(
    name='my_jupyter_extension',
    version='0.1.0',
    cmdclass=cmdclass,
    # Other setup arguments like packages, include_package_data, etc.
    packages=['my_jupyter_extension'],
    include_package_data=True,
    # Make sure to include MANIFEST.in for data files not in Python packages
    # (e.g., JS/CSS assets, Jupyter config files)
)

view raw JSON →