Using pre-commit

Introduction

PlasmaPy uses pre-commit to automate code quality checks and perform auto-fixes.

Troubleshooting pre-commit failures

Tip

Many common pre-commit test failures related to formatting can be automatically fixed by adding a comment on a pull request that says:

pre-commit.ci autofix

This comment will produce a new commit to applies auto-fixes from pre-commit. For an example, see this comment.

After doing this, don’t forget to do a git pull in your clone of the repository to pull back the changes to your computer.

The following sections contain suggestions for how to fix pre-commit failures that were not corrected by commenting pre-commit.ci autofix on the issue.

ruff

PlasmaPy uses ruff as its primary linter and code quality tool. ruff can quickly find code quality issues and is able to do many code quality fixes.

Every issue detected by ruff corresponds to a specific lint rule. For example, lint rule F401 removes unused import statements. If you encounter a confusing ruff rule, search ruff’s documentation page on rules for the rule code and click on its name for more information.

Problems flagged by C901 occur when a function is too complex (i.e., when it contains heavily nested control flow), which makes code much more difficult to maintain.

Tip

Reduce complexity by breaking up complicated functions into short functions that do exactly one thing with no side effects.

Disabling a ruff rule

While ruff usually suggests improvements, there will occasionally be times where a departure from a ruff rule is (at least temporarily) justified. In these cases, we can append a # noqa <rule-codes> comment to the end of a line (where <rule-codes> is replaced with the corresponding ruff rule codes, and noqa stands for “no quality assurance”) to tell ruff to ignore that error on that line.

For example, we can tell ruff to ignore a function with excessive code complexity (C901), too many branches (PLR0912), and too many statements (PLR0915) by adding the following noqa comment:

def overly_complicated_function():  # noqa: C901, PLR0912, PLR0915
    """A function with 100+ lines of code and lots of if/else branches."""

Important

When writing new code, it is almost always better to refactor the code to remove the error rather than add a noqa comment. In the above example, it would be better to refactor an overly complicated function into multiple short functions that do exactly one thing with no side effects so that the code is easier to understand, modify, and maintain. We should only add noqa statements when we have a good reason to.

Spellchecks

PlasmaPy uses codespell and typos to spellcheck source code. While these tools generally work well, occasionally there will be false positives.

If you encounter a false positive with codespell, add it to ignore-words-list under [codespell] in pyproject.toml.
False positives from typos should be added to _typos.toml.

Using pre-commit locally

pre-commit checks are performed on GitHub for every pull request, but it is also possible to set up pre-commit locally.

Tip

We recommend enabling pre-commit for the clone of PlasmaPy’s GitHub repository only after you have become comfortable with the code contribution workflow.

Enabling pre-commit

To enable pre-commit on your computer:

Open a terminal.
If you use a Conda or virtual environment for developing PlasmaPy, activate it (i.e., with conda activate plasmapy-dev).

Make sure that pre-commit is installed to your Python environment by running:

py -m pip install pre-commit

python -m pip install pre-commit

python -m pip install pre-commit

Navigate to the PlasmaPy directory that contains your clone of PlasmaPy’s repository. For example, if you cloned PlasmaPy into the ~/repos directory, then run:
```
cd ~/repos/PlasmaPy
```
Enable pre-commit with:
```
pre-commit install
```

Changes to the workflow

Once pre-commit has been installed for a repository, pre-commit will run every time you try to commit a change.

If any pre-commit checks fail, or if pre-commit changes any files, it will be necessary to redo git add on the changed files and git commit once again.

Tip

To commit a change without running pre-commit, use the -n flag (short for --no-verify) with git.

Tip

To run pre-commit on all files, use

pre-commit run --all-files