Good coding practices#

Development Setup#

Installing for development#

For development, we recommend using uv, a fast Python package installer and resolver written in Rust. It provides significantly faster dependency resolution and installation compared to traditional tools.

Install uv#

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or with pip (If installing from PyPI, we recommend installing uv into an isolated environment)
pip install uv

Install puma in development mode#

git clone https://github.com/umami-hep/puma.git
cd puma
uv sync --extra dev

This installs puma in editable mode with all development dependencies including testing frameworks, linters, formatters, etc.

Alternative: Using pip#

If you prefer to use pip, you can still install with:

python -m pip install -e ".[dev]"

Test-Driven Development#

The puma framework uses unit tests to reduce the risk for bugs being undetected. If you contribute to puma, please make sure that you add unit tests for the new code.

Image-comparison tests and reference plots#

Many plotting tests render a figure and compare it pixel-wise (via matplotlib's compare_images) against a stored reference image under puma/tests/**/expected_plots/. When you intentionally change a plot's appearance, regenerate the affected reference images by passing the --update-reference-plots flag to pytest:

pytest --update-reference-plots puma/tests/

This overwrites the reference images with the freshly generated ones. Review the resulting git diff of the PNGs to confirm only the intended changes, then commit them. Without the flag, the tests only compare and never modify the references.

Code Style#

We are using the black python formatter, which also runs in the pipeline to check if your code is properly formatted. Most editors have a quite nice integration of black where you can e.g. set up automatic formatting when you save a file.

Linters#

In addition to the pure style-component of checking the code with black, we use ruff to check the code for bad coding practices and docstrings. Make sure to run ruff before you commit your code.

Pre-commit hook#

To check staged files for style conformity, you can use the pre-commit hook, which then won't allow you to commit your staged changes if ruff or `black fails. You can set it up by executing the following in the root of the repo:

pre-commit install