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 |