Contributing

Development setup

This project uses uv for dependency management.

git clone https://github.com/dioscuri-tda/pyBallMapper.git
cd pyBallMapper
uv sync
uv run --group dev pre-commit install   # enable git hooks

Never use pip install for local development — always uv sync.

Pull requests

Open pull requests against the develop branch, not main. The main branch is reserved for releases.

CI pipeline

Every push and PR runs three stages in order. All must pass before merging.

Stage	Command	What it checks
Lint	`uv run pre-commit run --all-files`	Ruff lint + format
Typecheck	`uv run mypy pyballmapper/`	Static types (package only)
Test	`uv run pytest`	Unit tests

Running tests

uv run pytest                            # all tests
uv run pytest -x                         # stop on first failure
uv run pytest tests/test_ballmapper.py   # single file
uv run pytest -k "TestBallMapperConstruction"   # single test class

Fixtures live in tests/conftest.py and are shared across all test files.

Code quality

Ruff (lint + format)

Configured in pyproject.toml: line-length 88, target py313, rules E/F/W/I (ignores E203/E501/E731).

uv run pre-commit run --all-files   # run on entire tree

Pre-commit runs ruff (with --fix) and ruff-format automatically on every commit.

Mypy (type checking)

uv run mypy pyballmapper/

Only the package source is checked — tests and docs are excluded. ignore_missing_imports = true for untyped third-party libraries.

Pre-commit hooks

Hooks are defined in .pre-commit-config.yaml:

ruff — lint and auto-fix
ruff-format — format
mypy — typecheck on pyballmapper/ only

Run them on demand: uv run pre-commit run --all-files

Packaging

Built with setuptools. Version is read dynamically from pyballmapper/__init__.py.

uv build

Dependencies are declared in pyproject.toml under [project] dependencies. Dev-only deps (pre-commit, ruff, mypy, pytest) go under [dependency-groups] dev.