Development

This page covers local development checks for contributors and release preparation.

Editable Install

Install Matheel in editable mode with the development tools:

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

Local Checks

Run the default offline-friendly test suite:

python -m pytest

Run the Ruff lint check:

python -m ruff check .

Real-model integration tests are opt-in because they may need optional backends, cached model weights, or network access:

python -m pytest -m integration

Install the full optional stack before running them locally:

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

The Real Model Integration Tests GitHub Actions workflow is manual-only. It installs matheel[all,dev], caches Hugging Face model files under ~/.cache/huggingface, and runs python -m pytest -m integration on the selected Python version. It is not part of default pull-request CI, so normal tests remain offline-friendly.

Package Checks

When preparing release or packaging changes, build the package and check the distribution metadata:

python -m build
python -m twine check dist/*

Cache Safety

Matheel uses module-level caches for Hugging Face model metadata, detected tokenizer limits, CodeBLEU keyword sets, tree-sitter parsers, and CodeBERTScore scorer objects.

Request-path cache writes are protected with locks so concurrent API or Gradio calls do not mutate the same cache at the same time. Keyword cache entries are stored as immutable values. Pair-level caches inside prepared run contexts are scoped to that run context and should not be reused across independent requests.