Skip to content

Check

📖 This page describes the invoke_tasklib.check module.

Overview

Task Behavior
check.all Runs the main read-only checks of the project (default)

check.all is the default task of the check namespace, so invoke check runs it.

Usage

invoke check

Runs the steps of tasklib.check.tasks, in that order, and stops at the first failure. By default:

Step Task
format-python format.check-python
format-docstrings format.check-docstrings
lint lint.check-python
types types.check
imports imports.check-cycles
unit test.unit

Other steps can be added to the config (or run with --only): doctest (test.doctest), shell (format.check-shell and format.check-shell-format), spelling (lint.check-spelling), docs (doc.build) and audit (security.audit). They are not in the default set because they need more tools (shellcheck, shfmt, codespell, mkdocs) or the network.

tasklib:
  check:
    tasks: [format-python, lint, types, unit, doctest, docs]

None of them modifies a file. The exception is the unit step with tasklib.check.cov: true: it runs test.unit --cov, which generates the coverage reports and enforces tasklib.test.cov_fail_under (without it check never checks the threshold).

Option Effect
--keep-going Runs every step, prints the failed ones with the reason and exits with 1 if any failed
--only Comma-separated steps to run instead of tasklib.check.tasks
--skip Comma-separated steps to leave out
invoke check --keep-going
invoke check --only lint,types
invoke check --skip unit

Before running anything, the task looks up the tools that the selected steps need and reports all the missing ones at once (exit code 127), so a missing ty is not discovered after the formatting has run. With --keep-going, only the steps that miss a tool are not run: they are reported as failed, with the missing tool as the reason. Run env.check-tools to see every tool of the tasks.

By default the task stops at the first failure, as the CI jobs do; use --keep-going locally to learn about all the problems in one run. A step that fails with an error of the code or of the system (for example an OSError) is reported like any other failed step, with the type and the message of the error as the reason, and the other steps still run.

A step whose directory does not exist (for example the unit step of a project without tests/unit and tests) prints a ⏭️ line and counts as passed, see Missing Paths.

Use the tasks directly (with --args and --paths) to run only one of them, or lint.pre-commit to run the hooks of the project.

The steps come from tasklib.check.tasks; make_ns(exclude=...) does not remove them, so make_ns(exclude="lint") hides lint.* from inv --list but inv check --only lint still runs. To leave check out of a collection, use make_ns(exclude=["check"]).

Exit Codes

Code Meaning
0 Every selected step passed (or was skipped)
1 A step failed (with --keep-going, at the end; the failed steps are listed)
2 An unknown step in --only, --skip or tasklib.check.tasks, or a bad config
127 A tool of a selected step is missing, nothing was run

See Also