Code Quality

In an active development shell, the following make targets are available and act on all .py files under src/:

Command

Description

make format

Formats code and imports with ruff, docstrings with docformatter, and JSON documents with jq

make lint

Lints code with ruff

make typecheck

Typechecks code with mypy

make unittest

Runs unit tests and reports coverage with pytest and coverage

make test

Equivalent to make lint && make typecheck && make unittest, plus checks defined CLI scripts.

Configuration for these tools is provided by the file src/pyproject.toml.

The order of the targets above is intentional:

  • make format will complain about certain kinds of syntax errors that would cause all the remaining code-quality tools to fail (and that could change line numbers reported by other tools, if it ran after them).

  • make lint provides a good first check for obvious errors and anti-patterns in the code.

  • make typecheck offers a more nuanced look at interfaces between functions, methods, etc. and may spot issues missed by the linter.

  • make unittest provides higher-level semantic-correctness checks once code syntax and typing is deemed correct.

All the above tests are executed by the CI system when code is merged to specific git branches and when a conda package is built for release. To ensure that these processes succeed, be sure to run all the tests in a development shell before opening a pull request, and throughout the PR’s lifecycle as subsequent changes are made. CI will reject unformatted code, so also run make format and commit any changes it makes. A useful development idiom is to periodically run make format && make test to perform a full code-quality sweep through the code.

The uwtools repository has standardized 100% unit-test coverage, enforced by make unittest and its configuration in pyproject.toml. Please help maintain this high standard.