Quick Start for Developers

This guide is for contributors to mache. For general installation and usage, see the User’s Guide.

Setting up for Development

To work on mache, you should install the development version in an isolated environment:

conda config --add channels conda-forge
conda config --set channel_priority strict
conda create -y -n mache_dev --file spec-file.txt
conda activate mache_dev
python -m pip install --no-deps --no-build-isolation -e .

If you want to install into an existing environment:

conda install --file spec-file.txt
python -m pip install --no-deps --no-build-isolation -e .

Code Styling and Linting

mache uses pre-commit to enforce code style and quality. After setting up your environment, run:

pre-commit install

This only needs to be done once per environment. pre-commit will automatically check and format your code on each commit. If it makes changes, review and re-commit as needed. Some issues (like inconsistent variable types) may require manual fixes.

Internally, pre-commit uses:

  • ruff for PEP8 compliance and import formatting,

  • flynt to convert format strings to f-strings,

  • mypy for type checking.

Example error:

example.py:77:1: E302 expected 2 blank lines, found 1

In this case, add a blank line after line 77 and try again.

You may also use an IDE with a PEP8 style checker, such as PyCharm. See this tutorial for tips.

example.py:77:1: E302 expected 2 blank lines, found 1

For this example, we would just add an additional blank line after line 77 and try the commit again to make sure we’ve resolved the issue.

You may also find it useful to use an IDE with a PEP8 style checker built in, such as VS Code. See Formatting Python in VS Code for some tips on checking code style in VS Code.

Running Tests

To run the test suite:

pytest

Make sure all tests pass before submitting a pull request.

Contributing

  • Follow PEP8 and project code style.

  • Use descriptive commit messages.

  • Add or update tests for new features or bug fixes.

  • Document public functions and classes.

For more details, see the contributing guide.