Contributing

Issues and pull requests are welcome at github.com/vanvonzhang/pyFracAggregate. This page covers the local setup and the checks a change is expected to pass.

Development setup

Development needs Python ≥ 3.13 (see the installation guide for why the floor exists and how to satisfy the mathutils dependency on your platform). Clone the repository and install in editable mode with all development extras:

pip install -e ".[dev,plot]"     # pytest, ruff, mypy + matplotlib

Running the tests

pytest                                      # Run all tests
pytest tests/test_core/test_aggregate.py    # Run a single test file
pytest -k "test_pca"                        # Run tests matching a name pattern

The suite mirrors the source layout (tests/test_core/, test_generators/, test_analysis/, test_io/), so new modules should get a matching test file. Slow performance tests are marked benchmark; deselect them with:

pytest -m "not benchmark"

and run the benchmark set alone with pytest -m benchmark.

Lint and type checks

ruff check src/     # Lint source code
mypy src/           # Static type checking

The codebase is typed throughout; type hints on public functions are part of the API.

Building the documentation

The docs are Sphinx + MyST Markdown living in docs/ (see Architecture for the site layout):

pip install -e ".[docs]"                         # Sphinx, MyST, RTD theme, ...
sphinx-build -W -b html docs docs/_build/html    # Strict build

The zero-warning gate is mandatory for docs changes: sphinx-build -W turns any warning (broken cross-reference, missing anchor, autodoc error) into a build failure, and a PR that touches docs/ must build clean. The first build fetches intersphinx inventories (Python, NumPy, scipy, pyvista) over the network; subsequent builds use the cached environment.

Preview the result by opening docs/_build/html/index.html in a browser.

Pull request expectations

Before you open a PR:

  • pytest passes (or -m "not benchmark" if you are deliberately skipping the slow set — say so in the PR).

  • ruff check src/ and mypy src/ are clean on the files you touched.

  • If you touched anything under docs/ (including docstrings that feed the API reference), sphinx-build -W -b html docs docs/_build/html exits 0 with zero warnings.

  • New public API gets a docstring (Google style) and a matching entry in the API reference when it belongs in __all__.