Getting Started for Developers

We strongly recommend using the Miniforge3 conda distribution that ships the package installer mamba, a C++ reimplementation of conda.

Warning

The following guide is used only if you want to develop the pyvisgrid package, if you just want to write code that uses it as a dependency, you can install pyvisgrid through one of the installation methods in Getting Started for Users

Setting Up the Development Environment

We provide a mamba/conda environment with all packages needed for development of pyvisgrid that can be installed via:

$ mamba env create --file=environment-dev.yml

Next, activate this new virtual environment:

$ mamba activate pyvisgrid

You will need to run that last command any time you open a new terminal session to activate the mamba/conda environment.

Installing pyvisgrid in Development Mode

Note

We recommend using the uv package manager to install pyvisgrid and its dependencies. Never heard of uv? See the documentation for more.

To install pyvisgrid in your virtual environment, just run

$ uv pip install --group dev -e .

in the root of the directory (the directory that contains the pyproject.toml file). This installs the package in editable mode, meaning that you won’t have to rerun the installation for code changes to take effect. For greater changes such as adding new entry points, the command may have to be run again.

Attention

Make sure you include the --group flag to install the dev dependency group, which provides all the necessary dependencies for development on pyvisgrid.

Further Setup

We are using pre-commit with Ruff as linter and formatter for automatic code adherence to the Coding Style Guide. Install the pre-commit hooks:

$ pre-commit install

The pre-commit hooks will then run every time you commit something. If any of the tools reports a problem, the commit will be aborted and you will have to fix the issues first. Usually, a failing pre-commit hook indicates code not complying with the style guide. Once all problems are fixed, you can try committing again, and the changes will be accepted.

To run pre-commit manually, call:

$ pre-commit run

Or, to run it on all files:

$ pre-commit run --all-files

The Ruff hook uses the configuration in pyproject.toml for linting and formatting.

Next Steps

Check out Contribution Guide and Coding Style Guide to learn how to contribute to pyvisgrid as a developer.