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

Install pixi, a faster package manager similar to conda, if you don’t already have it:

curl -fsSL https://pixi.sh/install.sh | sh

Then, open a new terminal or shell so pixi will be in your path.

Alternatively, you can install it into a conda environment via the pixi packge on conda-forge.

Note: pixi install creates the environment but does not automatically activate it in your current shell. To use tools from the environment (like python), either run commands with pixi run ... or start a subshell with pixi shell.

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

pixi install
pixi shell
python -m pip install --no-deps --no-build-isolation -e .

This creates a Pixi environment based on the root pixi.toml and then installs mache in editable mode.

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.