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:
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