User Guide¶
invoke-tasklib groups its tasks into namespaces, one per module. Each namespace maps to
one page in this guide.
All Tasks at a Glance¶
Each task either checks/reports (read-only, exits non-zero on violations) or mutates
(formats, builds, publishes) — the Mutates? column below flags which.
| Namespace | Task | Behavior | Mutates? |
|---|---|---|---|
| Format | format.check-python |
Check Python formatting with ruff | ❌ |
| Format | format.fix-python |
Format Python code with ruff | ✅ |
| Format | format.check-docstrings |
Check docstring formatting with docformatter | ❌ |
| Format | format.fix-docstrings |
Format docstrings with docformatter | ✅ |
| Format | format.check-shell |
Check shell scripts with shellcheck | ❌ |
| Format | format.check-shell-format |
Check the format of shell scripts with shfmt | ❌ |
| Format | format.fix-shell |
Format shell scripts with shfmt | ✅ |
| Lint | lint.check-python |
Check code linting with ruff | ❌ |
| Lint | lint.fix-python |
Fix auto-fixable linting issues with ruff | ✅ |
| Lint | lint.check-spelling |
Check the spelling with codespell | ❌ |
| Lint | lint.pre-commit |
Run all the pre-commit hooks | ✅ |
| Imports | imports.check-cycles |
Check for cyclic import dependencies | ❌ |
| Imports | imports.check-isolated |
Check that every module imports on its own | ❌ |
| Types | types.check |
Check type hints with ty (--complete: + pyright) |
❌ |
| Test | test.doctest |
Run doctests on source code and markdown files | ❌ |
| Test | test.doctest-src |
Run doctests on source code | ❌ |
| Test | test.doctest-markdown |
Run doctests on Python examples in markdown | ❌ |
| Test | test.unit |
Run unit tests | ❌ |
| Test | test.integration |
Run integration tests | ❌ |
| Test | test.functional |
Run functional tests | ❌ |
| Test | test.all |
Run unit, integration, and functional tests | ❌ |
| Test | test.coverage-report |
Generate an HTML/terminal report from coverage data | ❌ |
| Test | test.benchmark |
Run performance benchmarks | ❌ |
| Env | env.create-venv |
Create a virtual environment and install the project | ✅ |
| Env | env.install |
Install project dependencies and the package | ✅ |
| Env | env.check-tools |
Check which tools are available | ❌ |
| Env | env.update |
Update dependencies and pre-commit hooks | ✅ |
| Env | env.show-installed-packages |
Show installed packages | ❌ |
| Env | env.show-python-config |
Show the Python configuration | ❌ |
| Release | release.build |
Build the package and verify installation | ✅ |
| Release | release.publish |
Build and publish the package to PyPI | ✅ |
| Doc | doc.build |
Build the docs, failing on warnings | ❌ |
| Doc | doc.serve |
Serve the docs locally | ❌ |
| Doc | doc.publish-dev |
Publish development (unstable) docs | ✅ |
| Doc | doc.publish-latest |
Publish latest (stable) docs | ✅ |
| Security | security.audit |
Audit dependencies for known vulnerabilities | ❌ |
| Check | check.all (or check) |
Run the main read-only checks | ❌ |
| Fix | fix.all (or fix) |
Fix the lint and format issues | ✅ |
| Clean | clean.all (or clean) |
Remove build artifacts and caches | ✅ |
| Clean | clean.pycache |
Remove all __pycache__ directories |
✅ |
| Config | config.show |
Show the resolved config and its origins | ❌ |
| Config | (none — shared config) | Config resolution used by all tasks above | — |
Everyday Workflow¶
A typical local development loop looks like this:
invoke format.fix-python format.fix-docstrings # auto-fix formatting
invoke lint.check-python imports.check-cycles types.check # check quality
invoke test.unit --cov # run tests with coverage
To run the main read-only checks (format, lint, types, imports and the unit tests) in one command:
invoke check
See Check for the steps and the options.
And what CI typically runs (nothing should modify the working tree):
invoke format.check-python format.check-docstrings lint.check-python imports.check-cycles types.check
invoke test.all --cov
Since Invoke lets you chain multiple task names in one command, all of the above run as a single
invoke call each.
Passing Arguments to the Tools¶
Every task that runs an external tool takes --args, and the tasks that run on files also take
--paths:
--argsadds arguments to the command. The value is one string, split like a shell does.--pathsruns the tool on these files or directories instead of the default ones (the project forruff,paths.srcfordocformatterand the source doctests, the scope directory forpytest, every*.shfile forshellcheckandshfmt, every markdown file for the markdown doctests). The value is quoted, so a glob (src/*.py) or~reaches the tool as it is: only a tool that expands globs itself (likeruff) handles them.
| Tasks | --args goes to |
--paths |
|---|---|---|
test.all, test.unit, test.integration, test.functional, test.benchmark |
pytest |
✅ |
test.doctest-src |
pytest |
✅ |
test.doctest-markdown |
python -m doctest |
✅ |
test.coverage-report |
coverage report |
❌ |
format.*-python, lint.check-python, lint.fix-python |
ruff |
✅ |
format.*-docstrings |
docformatter |
✅ |
format.check-shell, format.check-shell-format, format.fix-shell |
shellcheck, shfmt |
✅ |
lint.check-spelling |
codespell |
✅ |
lint.pre-commit |
pre-commit |
❌ |
types.check |
ty (only) |
✅ |
security.audit |
pip-audit |
❌ |
doc.build, doc.serve |
mkdocs |
❌ |
release.build |
uv build |
❌ |
release.publish |
uv publish |
❌ |
The other tasks have no --args: the composite tasks (check.all and fix.all with
--only, --skip and --keep-going, test.doctest), the tasks that run no external tool
(clean.*, imports.*, config.show) and the tasks with their own options (env.*,
doc.publish-*).
invoke test.unit --args "-k foo -x" --paths tests/unit/test_foo.py
invoke lint.check-python --args "--select E" --paths "src/a.py src/b.py"
invoke format.check-python --paths src/a.py
invoke security.audit --args "--ignore-vuln PYSEC-2024-1"
invoke doc.serve --args "--dev-addr 127.0.0.1:8001"
invoke test.coverage-report --args "--fail-under=90"
For types.check, --args goes to ty only and --paths goes to ty and pyright. The
arguments and the paths are quoted, so they are never interpreted by the shell.
Missing Paths¶
One rule says what a task does when a path of the config does not exist:
| Kind of path | When it is missing | Examples |
|---|---|---|
| A directory the task may legitimately not have | ⏭️ message naming the directory, exit code 0 |
paths.unit_tests, paths.integration_tests, paths.functional_tests |
| A path the task is about | Exit code 2, the message names the key |
paths.src (test.doctest-src, format.*-docstrings), paths.docs_config |
| The only input of a task that produces a measurement | Exit code 1 |
paths.benchmarks (test.benchmark) |
A path given with --paths is never checked by the task: the tool reports it. In check.all a
skipped directory is a skipped step, not a failure.
External Tools¶
Tasks are thin wrappers around external command-line tools. Each is expected to be available on
PATH or next to the Python interpreter that runs invoke (or installed via env.install/env.create-venv):
| Tool | Used by |
|---|---|
ruff |
format.check-python, format.fix-python, lint.check-python |
docformatter |
format.check-docstrings, format.fix-docstrings |
shellcheck |
format.check-shell |
shfmt |
format.check-shell-format, format.fix-shell |
ty |
types.check |
pyright |
types.check --complete |
pytest |
test.* except test.doctest and test.doctest-markdown |
pytest-timeout |
test.unit, test.integration, test.functional, test.all |
pytest-cov |
the --cov option of the test.* tasks |
coverage |
test.coverage-report |
xdoctest |
test.* (unless tasklib.test.xdoctest is false), test.doctest-src |
pytest-benchmark |
test.benchmark |
uv |
env.* (except env.check-tools), release.*, security.audit |
twine (via uvx) |
release.build --check |
codespell |
lint.check-spelling |
pre-commit |
lint.pre-commit |
mkdocs |
doc.build, doc.serve |
mkdocs-material |
the theme of the docs built by doc.build, doc.serve |
mike |
doc.publish-dev, doc.publish-latest |
git |
doc.publish-latest, release.publish, and the file lookup of the shell and markdown tasks |
pip-audit (via uvx) |
security.audit |
Most of these come from your project's own dev/docs dependency groups; see
Env for how env.install wires them up, and the
Troubleshooting guide if a task fails with a "command not found" error.
See Also¶
- Get Started: installing
invoke-taskliband wiring up a new project. - Config: the shared configuration all tasks read from.
- Writing a Custom Task: the helpers to write a task like the shared ones.
- Troubleshooting: common errors and how to fix them.