Using pre-commit

Introduction

PlasmaPy uses pre-commit to automate code quality checks and perform automated fixes. The configuration for pre-commit is in .pre-commit-config.yaml.

Troubleshooting pre-commit failures

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 (like in this comment). This comment will lead to a new commit to the pull request branch that applies the automatic fixes made by the different pre-commit hooks.

After doing this, please do a git pull in your clone of PlasmaPy’s repository to pull back the auto fixes 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.

Tip

Make sure all other tests are passing before manually fixing pre-commit test failures. Failures from pre-commit should generally be fixed after making sure all other tests are passing.

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.

codespell

PlasmaPy uses codespell to find typos in source code. Rather than checking if each word matches a dictionary entry, codespell tries to match words to a set of common misspellings. This approach greatly reduces the number of false positives, but will occasionally miss some uncommon misspellings.

If you encounter a false positive with codespell, add it to ignore-words-list under [codespell] in pyproject.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