This release is a pre-release and may not be stable for production use.
invoke-tasklib
Reusable Invoke tasks shared across Python
projects: formatting, linting, type-checking, testing, environment setup,
security auditing, releasing, documentation, and cleanup — all as a single
importable package instead of a tasks.py you copy-paste and let drift
between repositories.
📖 Full documentation: https://durandtibo.github.io/invoke-tasklib/
Install
uv add --dev invoke-tasklib
or with pip:
pip install invoke-tasklib
Prerequisite: most tasks (env.*, release.*, security.audit) run
uv, so install
it even if you install invoke-tasklib with pip.
Platforms: Linux and macOS. Windows is not supported: the tasks rely on
a POSIX shell (for the quoting of the commands), and make_ns emits a
RuntimeWarning on Windows.
Quickstart
1. Add a tasks.py at the root of your project:
# tasks.py
from invoke_tasklib import make_ns
ns = make_ns()
2. Add an invoke.yaml with, at minimum, your package name:
tasklib:
package:
name: my_package
3. List and run the tasks:
invoke --list
invoke format.check-python lint.check-python
invoke test.unit
If a task fails because a tool like ruff or pytest isn't installed yet,
run invoke env.install first.
See the Get Started guide for a full walkthrough.
Tasks
Tasks are grouped into namespaces, one per module. Each task either checks/reports (read-only, exits non-zero on violations) or mutates (formats, builds, publishes) — the table 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 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 also runs 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 files | ❌ |
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 existing 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 (editable) | ✅ |
env |
env.check-tools |
Check which tools (ruff, pyright, ...) are available | ❌ |
env |
env.update |
Update dependencies and pre-commit hooks | ✅ |
env |
env.show-installed-packages |
Show the installed packages | ❌ |
env |
env.show-python-config |
Show the Python configuration | ❌ |
release |
release.build |
Build the package and verify installation (--check also validates metadata with twine) |
✅ |
release |
release.publish |
Build and publish the package to PyPI | ✅ |
doc |
doc.publish-dev |
Publish development (unstable) docs | ✅ |
doc |
doc.publish-latest |
Publish latest (stable) docs | ✅ |
doc |
doc.build |
Build the docs, failing on warnings (mkdocs build --strict) |
❌ |
doc |
doc.serve |
Serve the docs locally | ❌ |
security |
security.audit |
Audit the locked dependencies for known vulnerabilities with pip-audit | ❌ |
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 where each value comes from | ❌ |
format.* and lint.* follow a naming convention: read-only checks are
named check_<target>, and the matching in-place fixer is named
fix_<target> (e.g. check_python/fix_python), so the counterpart of a
task is always easy to find. Follow this convention when adding new tasks
to these namespaces.
For task-by-task details, options (like --cov on test.* tasks), and the
tools each one wraps, see the
User Guide.
Configuration
Only tasklib.package.name is required — everything else has a sensible
default derived from it:
tasklib:
package:
name: my_package # required
import_name: my_package # default: <package.name> with - replaced by _
python_version: "3.14" # used by env.create-venv (default: the version that uv chooses)
paths:
src: src/my_package # default: src/<package.import_name>
tests: tests
unit_tests: tests/unit # default: <tests>/unit
integration_tests: tests/integration # default: <tests>/integration
functional_tests: tests/functional # default: <tests>/functional
benchmarks: tests/benchmarks # default: <tests>/benchmarks
docs_config: docs/mkdocs.yml
groups:
install: dev # dependency groups of env.install
update: dev,docs # dependency groups of env.update
test:
unit_timeout: 10 # seconds, also integration_timeout and functional_timeout
xdoctest: true # pytest --xdoctest (needs xdoctest)
timeout: true # pytest --timeout (needs pytest-timeout)
cov_fail_under: 90 # threshold of --cov (default: not set)
cov_reports: html,xml,term
types:
checker: ty # type checker of types.check: ty, pyright or mypy
check:
tasks: format-python,format-docstrings,lint,types,imports,unit # steps of check.all
cov: false # run the unit step of check.all with --cov
fix:
tasks: lint,format-python,format-docstrings # steps of fix.all
check.tasks also accepts doctest, shell, spelling, docs and audit; fix.tasks also
accepts shell. invoke config.show prints the resolved values and where each one comes from.
See the Config reference for how each path default is derived.
Every key can also be set with an INVOKE_TASKLIB_<SECTION>_<KEY> environment variable, for example
INVOKE_TASKLIB_PATHS_SRC=lib or INVOKE_TASKLIB_TEST_UNIT_TIMEOUT=30, which wins over
invoke.yaml. An invalid value, an unknown key (with the closest valid key suggested) or a wrong
working directory exits with the code 2 before any command runs. For editor completion, the JSON
schema of the tasklib section is published at
https://durandtibo.github.io/invoke-tasklib/schema.json (python -m invoke_tasklib.config prints
it).
Conventions
- Arguments: the tasks that run a tool take
--args(extra arguments for the tool, as one string, e.g.--args "-k foo -x") and, for the tasks that work on files,--paths(files or directories instead of the default ones). Both are quoted, so a glob or~reaches the tool as it is. - Exit codes:
0the task passed, or had nothing to do (a⏭️line says why);1the checked thing failed;2invalid usage or config;127a tool is missing. A missing program or Python module is reported with the command that installs it. - Composite tasks:
invoke checkruns the main read-only checks andinvoke fixthe fixers;--only,--skipand--keep-goingselect the steps and report all the failures at the end. - Dangerous tasks ask first:
env.create-venvasks before it clears.venvandrelease.publishchecks the git state and asks before it uploads (--yesskips the question,--dry-runpublishes nothing).cleanstays inside the project and keeps what git tracks. - ASCII output: set
INVOKE_TASKLIB_ASCII=1to replace the emojis of the messages with[ok],[fail]and[skip].
Composing a custom subset of tasks
Need a different set of tasks, or a one-off task alongside the shared ones?
Use make_ns, which returns a new collection each time, so adding or removing tasks never affects
other importers. Leave out the tasks you do not use (for example the ones that publish):
# tasks.py
from invoke import task
from invoke_tasklib import make_ns
@task
def my_custom_task(c):
r"""Run a one-off command."""
c.run("echo hello")
ns = make_ns(exclude=["release.publish", "doc"])
ns.add_task(my_custom_task)
tasks.py is imported by Invoke as a top-level module, so a task defined in another file of the
project is imported with an absolute import (from my_tasks import my_custom_task), not a
relative one (from . import my_custom_task), which fails with an ImportError.
or keep only some of them with include, e.g. make_ns(include=["lint", "test.unit"]). The names
are namespaces ("doc") or tasks ("release.publish"); an unknown name raises a ValueError. The
make_ns() with no argument has all the tasks (the former pre-built invoke_tasklib.ns, one
collection shared by every importer, was removed). Individual task modules can also be composed by
hand:
# tasks.py
from invoke import Collection, task
from invoke_tasklib import lint, testing
@task
def my_custom_task(c):
r"""Run a one-off command."""
c.run("echo hello")
ns = Collection(lint, Collection.from_module(testing, name=testing.NAMESPACE), my_custom_task)
The modules of the format, types and test namespaces are named formatting, typecheck
and testing so that they do not shadow the standard library (types, test) or a builtin
(format); pass name=module.NAMESPACE (every task module has the name of its namespace in NAMESPACE)
to Collection.from_module to keep the task names.
Prefer adding a config knob to a shared task over forking it; reserve custom composition for things that are genuinely one-off to a single project.
API Stability
⚠️ invoke-tasklib is under active development and its API is not
yet stable — pin a specific version in your project's dependencies for
consistent behavior across releases.
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.
License
invoke-tasklib is licensed under the BSD 3-Clause "New" or "Revised"
license available in
LICENSE.
Metadata
Release files for invoke-tasklib 0.1.0a0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| invoke_tasklib-0.1.0a0.tar.gz | 158.8 kB | Without provenance | Details for invoke_tasklib-0.1.0a0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| invoke_tasklib-0.1.0a0-py3-none-any.whl | Python 3 | none | any | Details for invoke_tasklib-0.1.0a0-py3-none-any.whl |
Total release size: 247.8 kB
Release files / invoke_tasklib-0.1.0a0.tar.gz
| Download URL | invoke_tasklib-0.1.0a0.tar.gz |
|---|---|
| Size | 158.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
695a29198732bb0ad323410285fcfbe1a1fd8e640e5ad538221c0c135fb95056
|
|
BLAKE2b-256 checksum How to use checksums |
3ea73abb54b668f3bc03fc53943d3acb88413845ecf824547efd9bc8dd34bfab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / invoke_tasklib-0.1.0a0-py3-none-any.whl
| Download URL | invoke_tasklib-0.1.0a0-py3-none-any.whl |
|---|---|
| Size | 89.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9741d211fd11d5b4e5c49f7365ad3d5073ce0d99b1a4dfd961134c1342069164
|
|
BLAKE2b-256 checksum How to use checksums |
071a033a988682e140c98ba01b6a069b0414d8ae623df3b243c17799a93afb9c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for invoke-tasklib 0.1.0a0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.