Home¶
Overview¶
invoke-tasklib is a reusable library of Invoke tasks shared across
Python projects. Instead of copy-pasting the same tasks.py boilerplate (formatting, linting,
type-checking, testing, environment setup, releasing, and documentation) into every repository, a
project imports one namespace and gets a consistent set of invoke commands.
Quick Links:
Why invoke-tasklib?¶
Most Python projects end up with a tasks.py that wraps the same handful of tools: ruff,
ty, pytest, docformatter, uv, mike. Keeping those wrappers in sync across many
repositories is tedious, and small inconsistencies (a missing --xdoctest flag, a different
coverage flag) creep in over time.
invoke-tasklib centralizes these tasks in one importable package:
from invoke_tasklib import make_ns
ns = make_ns()
invoke --list
A single invoke.yaml at the project root configures the package name and, optionally, the paths
used by the tasks:
tasklib:
package:
name: my_package
See the user guide for the full config schema. Every key can also be set with
an INVOKE_TASKLIB_<SECTION>_<KEY> environment variable (for example INVOKE_TASKLIB_PATHS_SRC),
and an editor can check the file against the JSON schema.
A project that needs fewer tasks, or tasks of its own, builds the namespace with
make_ns(exclude=[...]) or make_ns(include=[...]), see
Writing a Custom Task.
Conventions of the Tasks¶
check_<target>never modifies a file andfix_<target>does.check.allruns the read-only checks of the project andfix.allthe fixers; the Check and Fix pages list their steps.- Every tool is looked up before it runs. A missing program or Python module is reported with
the command that installs it (exit code
127), and a composite task reports all the missing tools of its steps at once. - Exit codes:
0the task passed, or had nothing to do (aโญ๏ธline says why);1the checked thing failed;2invalid usage or config (the message names the key);127a tool is missing. - Extra arguments: the tasks that run a tool take
--argsand, for the tasks that work on files,--paths, see Passing Arguments to the Tools.
Features¶
invoke-tasklib provides a comprehensive set of tasks organized into namespaces:
๐จ Format and Lint¶
format.check-python/format.fix-python: check or format code with ruffformat.check-docstrings/format.fix-docstrings: check or format docstrings with docformatterformat.check-shell/format.check-shell-format/format.fix-shell: check shell scripts with shellcheck, check their format with shfmt, or format them with shfmtlint.check-python/lint.fix-python: check or fix linting with rufflint.check-spelling: check the spelling with codespelllint.pre-commit: run all the pre-commit hooks
๐ Cyclic Imports¶
imports.check-cycles: check for cyclic import dependencies (static import graph)imports.check-isolated: check that every module imports on its own
๐ฌ Type Checking¶
types.check: check type hints with ty (--completealso runs pyright)
๐งช Testing¶
test.doctest,test.doctest-src,test.doctest-markdown,test.unit,test.integration,test.functional,test.all,test.coverage-report,test.benchmark
๐ Environment Management¶
env.create-venv,env.install,env.update,env.check-tools,env.show-installed-packages,env.show-python-config
๐ฆ Release¶
release.build,release.publish
๐ Documentation¶
doc.build,doc.serve,doc.publish-dev,doc.publish-latest
๐ Security¶
security.audit: audit the dependencies for known vulnerabilities with pip-audit
โ Check¶
check.all(orcheck): run the main read-only checks
๐ง Fix¶
fix.all(orfix): fix the lint and format issues
๐งน Clean¶
clean.all(orclean): remove build artifacts and cachesclean.pycache: remove all__pycache__directories
โ๏ธ Config¶
config.show: show the resolved config and where each value comes from
Contributing¶
Contributions are welcome! Please open an issue first to discuss significant changes. See the developer guide for how to set up a development environment and the project's conventions.
API Stability¶
Important: As
invoke-tasklib is under active development, its API is not yet
stable and may change between releases. We recommend pinning a specific version in your project's
dependencies to ensure consistent behavior.
License¶
invoke-tasklib is licensed under the BSD 3-Clause "New" or "Revised" license available in
LICENSE.