Using pre-commit
Introduction
PlasmaPy uses pre-commit to autoformat code, automate code quality checks, and perform automated fixes if available. pre-commit checks are performed on GitHub for every pull request.
Important
Automatically fix most pre-commit failures on pull requests by commenting:
pre-commit.ci autofix
Adding this comment to the Conversation tab of a pull
request triggers a new commit that applies automatic fixes made by
PlasmaPy’s pre-commit hooks. Use git pull to bring changes on
GitHub back to your computer.
Running pre-commit locally
After installing pre-commit, pre-commit can be run locally for all files in your clone of the repository by running:
pre-commit run -a
The -a is short for --all-files.
Troubleshooting pre-commit failures
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 formatter. ruff quickly finds and often fixes many code quality issues.
Every issue detected by ruff corresponds to a specific linter rule. For
example, lint rule F401 removes unused import statements.
Tip
Find more information about issues flagged by ruff by searching ruff’s documentation page on rules for the rule code and clicking on its name.
Disabling a ruff rule
While ruff usually suggests improvements, there are occasionally times when a departure from a ruff rule is preferable.
To ignore a ruff rule on a specific line, append a comment of the form
# noqa <rule-codes>, where <rule-codes> is replaced by
the ruff rule code(s) to ignore.
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 a noqa comment like in the following
example:
def overly_complicated_function(): # noqa: C901, PLR0912, PLR0915
"""A function with 97 lines and multiple nested if/else blocks."""
When writing new code, it is almost always preferable to refactor the
code to remove the error than to add a # noqa comment to ignore the
rule. Complex functions flagged by C901 could be simplified by
extracting sections of code into separate functions that do exactly one
thing with no side effects.
Important
Use # noqa comments sparingly, and only when you have a strong
reason to do so.
Spellchecks
PlasmaPy uses codespell and typos to spellcheck source code. While these tools generally work well, occasionally there will be false positives.