sp-repo-review 2023.12.21

sp-repo-review provides checks based on the Scientific-Python Development Guide at scientific-python/cookie for repo-review.

This tool can check the style of a repository. Use like this:

pipx run 'sp-repo-review[cli]' <path to repository>

This will produce a list of results - green checkmarks mean this rule is followed, red x’s mean the rule is not. A yellow warning sign means that the check was skipped because a previous required check failed. Some checks will fail, that’s okay - the goal is bring all possible issues to your attention, not to force compliance with arbitrary checks. Eventually there might be a way to mark checks as ignored.

For example, GH101 expects all your action files to have a nice name: field. If you are happy with the file-based names you see in CI, you should feel free to simply ignore this check (just visually ignore it for the moment, a way to specify ignored checks will likely be added eventually).

All checks are mentioned at least in some way in the Scientific-Python Development Guide. You should read that first - if you are not attempting to follow them, some of the checks might not work. For example, the guidelines specify pytest configuration be placed in pyproject.toml. If you place it somewhere else, then all the pytest checks will be skipped.

This was originally developed for Scikit-HEP before moving to Scientific Python.

Other ways to use

You can also use GitHub Actions:

- uses: scientific-python/cookie@<version>

Or pre-commit:

- repo: https://github.com/scientific-python/cookie
  rev: <version>
  hooks:
    - id: sp-repo-review

If you use additional_dependencies to add more plugins, like validate-pyproject, you should also include "repo-review[cli]" to ensure the CLI requirements are included.

List of checks

General

• PY001: Has a pyproject.toml
• PY002: Has a README.(md|rst) file
• PY003: Has a LICENSE* file
• PY004: Has docs folder
• PY005: Has tests folder
• PY006: Has pre-commit config
• PY007: Supports an easy task runner (nox or tox)

PyProject

• PP002: Has a proper build-system table
• PP003: Does not list wheel as a build-dep
• PP301: Has pytest in pyproject
• PP302: Sets a minimum pytest to at least 6
• PP303: Sets the test paths
• PP304: Sets the log level in pytest
• PP305: Specifies xfail_strict
• PP306: Specifies strict config
• PP307: Specifies strict markers
• PP308: Specifies useful pytest summary
• PP309: Filter warnings specified

Documentation

• RTD100: Uses ReadTheDocs (pyproject config)
• RTD101: You have to set the RTD version number to 2
• RTD102: You have to set the RTD build image
• RTD103: You have to set the RTD python version

GitHub Actions

• GH100: Has GitHub Actions config
• GH101: Has nice names
• GH102: Auto-cancel on repeated PRs
• GH103: At least one workflow with manual dispatch trigger
• GH104: Use unique names for upload-artifact
• GH200: Maintained by Dependabot
• GH210: Maintains the GitHub action versions with Dependabot
• GH211: Do not pin core actions as major versions
• GH212: Require GHA update grouping

MyPy

• MY100: Uses MyPy (pyproject config)
• MY101: MyPy strict mode
• MY102: MyPy show_error_codes deprecated
• MY103: MyPy warn unreachable
• MY104: MyPy enables ignore-without-code
• MY105: MyPy enables redundant-expr
• MY106: MyPy enables truthy-bool

Pre-commit

• PC100: Has pre-commit-hooks
• PC110: Uses black or ruff-format
• PC111: Uses blacken-docs
• PC140: Uses mypy
• PC160: Uses codespell
• PC170: Uses PyGrep hooks (only needed if RST present)
• PC180: Uses prettier
• PC190: Uses Ruff
• PC191: Ruff show fixes if fixes enabled
• PC901: Custom pre-commit CI message

Ruff

• RF001: Has Ruff config
• RF002: Target version must be set
• RF003: src directory specified if used
• RF101: Bugbear must be selected
• RF102: isort must be selected
• RF103: pyupgrade must be selected
• RF201: Avoid using deprecated config settings
• RF202: Use (new) lint config section