Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

invoke-tasklib

CI Nightly Package Tests Codecov
Documentation Documentation
Doc style: google Ruff try/except style: tryceratops
PYPI version Python BSD-3-Clause
Downloads Monthly downloads GitHub stars
OpenSSF Scorecard

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: 0 the task passed, or had nothing to do (a ⏭️ line says why); 1 the checked thing failed; 2 invalid usage or config; 127 a tool is missing. A missing program or Python module is reported with the command that installs it.
  • Composite tasks: invoke check runs the main read-only checks and invoke fix the fixers; --only, --skip and --keep-going select the steps and report all the failures at the end.
  • Dangerous tasks ask first: env.create-venv asks before it clears .venv and release.publish checks the git state and asks before it uploads (--yes skips the question, --dry-run publishes nothing). clean stays inside the project and keeps what git tracks.
  • ASCII output: set INVOKE_TASKLIB_ASCII=1 to 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)

Source distribution for invoke-tasklib 0.1.0a0
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)

Table of built distributions (wheels) for invoke-tasklib 0.1.0a0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page