See the Scikit-HEP Developer introduction for a detailed description of best practices for developing Scikit-HEP packages.

Contributing#

Setting up a development environment#

Nox#

The fastest way to start with development is to use nox. If you don’t have nox, you can use uvx nox to run it without installing, or uv tool install nox. If you don’t have uv (or pipx, which is similar), then you can install with with pip install uv (the only case were installing an application with regular pip is reasonable). If you use macOS, then uv, prek, and nox are both in brew, use brew install uv prek nox.

To use, run nox. This will lint and test using every installed version of Python on your system, skipping ones that are not installed. You can also run specific jobs:

$ nox -l # List all the defined sessions
$ nox -s lint  # Lint only
$ nox -s tests-3.14  # Python 3.14 tests only
$ nox -s docs -- serve  # Build and serve the docs
$ nox -s build  # Make an SDist and wheel

Nox handles everything for you, including setting up an temporary virtual environment for each run. On Linux, it will run the --mpl tests. You can run the linux tests from anywhere with Docker:

docker run --rm -v $PWD:/nox -w /nox -t quay.io/pypa/manylinux_2_28_x86_64:latest pipx run nox -s tests-3.10
# Regenerate the MPL comparison images:
docker run --rm -v $PWD:/nox -w /nox -t quay.io/pypa/manylinux_2_28_x86_64:latest pipx run nox -s regenerate

Documentation#

The generation of documentation requires pandoc and dot (a Graphviz application) in addition.

For example, on Debian/ubuntu:

$ sudo apt install pandoc graphviz
$ nox -s docs
$ xdg-open _build/html/index.html

PyPI#

For extended development, you can set up a development environment using PyPI.

$ python3 -m venv .venv
$ source .venv/bin/activate
(venv)$ pip install -e . --group dev
(venv)$ python -m ipykernel install --user --name hist

You should have pip 10 or later.

Post setup#

You should prepare prek, which will help you by checking that commits pass required checks:

uv tool install prek # or brew install prek on macOS
prek install # Will install a pre-commit hook into the git repo

You can also/alternatively run prek (changes only) or prek -a to check even without installing the hook.

Testing#

Use PyTest to run the unit checks:

uv run pytest

Contributing

Contents