Skip to content

Home

CI Nightly Package Tests Codecov Documentation (stable)
PyPI version Python BSD-3-Clause
Ruff Doc style: google OpenSSF Scorecard
Downloads Monthly downloads GitHub stars

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 and fix_<target> does. check.all runs the read-only checks of the project and fix.all the 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: 0 the task passed, or had nothing to do (a โญ๏ธ line says why); 1 the checked thing failed; 2 invalid usage or config (the message names the key); 127 a tool is missing.
  • Extra arguments: the tasks that run a tool take --args and, 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 ruff
  • format.check-docstrings / format.fix-docstrings: check or format docstrings with docformatter
  • format.check-shell / format.check-shell-format / format.fix-shell: check shell scripts with shellcheck, check their format with shfmt, or format them with shfmt
  • lint.check-python / lint.fix-python: check or fix linting with ruff
  • lint.check-spelling: check the spelling with codespell
  • lint.pre-commit: run all the pre-commit hooks

Learn more โ†’

๐Ÿ” Cyclic Imports

  • imports.check-cycles: check for cyclic import dependencies (static import graph)
  • imports.check-isolated: check that every module imports on its own

Learn more โ†’

๐Ÿ”ฌ Type Checking

  • types.check: check type hints with ty (--complete also runs pyright)

Learn more โ†’

๐Ÿงช Testing

  • test.doctest, test.doctest-src, test.doctest-markdown, test.unit, test.integration, test.functional, test.all, test.coverage-report, test.benchmark

Learn more โ†’

๐Ÿ Environment Management

  • env.create-venv, env.install, env.update, env.check-tools, env.show-installed-packages, env.show-python-config

Learn more โ†’

๐Ÿ“ฆ Release

  • release.build, release.publish

Learn more โ†’

๐Ÿ“š Documentation

  • doc.build, doc.serve, doc.publish-dev, doc.publish-latest

Learn more โ†’

๐Ÿ”’ Security

  • security.audit: audit the dependencies for known vulnerabilities with pip-audit

Learn more โ†’

โœ… Check

  • check.all (or check): run the main read-only checks

Learn more โ†’

๐Ÿ”ง Fix

  • fix.all (or fix): fix the lint and format issues

Learn more โ†’

๐Ÿงน Clean

  • clean.all (or clean): remove build artifacts and caches
  • clean.pycache: remove all __pycache__ directories

Learn more โ†’

โš™๏ธ Config

  • config.show: show the resolved config and where each value comes from

Learn more โ†’

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.