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

Quickstart

1. Add a tasks.py at the root of your project:

# tasks.py
from invoke_tasklib import 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-lint
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.

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
    python_version: "3.14" # used by env.create-venv
  paths:
    src: src/my_package # default: src/<package.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

See the Config reference for how each path default is derived.

Composing a custom subset of tasks

Need a different set of tasks, or a one-off task alongside the shared ones? Import individual task modules instead of the pre-built ns:

from invoke import Collection
from invoke_tasklib import lint, test

from . import my_custom_task

ns = Collection(lint, test, my_custom_task)

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.