Skip to content

Config

📖 This page describes the invoke_tasklib.config module, which resolves the shared config that all invoke-tasklib tasks read from.

Prerequisites: You'll need to know a bit of Python and Invoke.

Overview

Every task in invoke-tasklib calls load_config(c) (get_config(c) with a clean exit on an invalid config, see below) to read project-specific values from an invoke.yaml at the root of the consuming project, under a tasklib key:

tasklib:
  package:
    name: my_package
    python_version: "3.14"
  paths:
    src: src/my_package
    tests: tests
    unit_tests: tests/unit
    integration_tests: tests/integration
    functional_tests: tests/functional
    benchmarks: tests/benchmarks
    docs_config: docs/mkdocs.yml
  groups:
    install: dev
    update: dev,docs
  test:
    unit_timeout: 10
    xdoctest: true
    timeout: true
    cov_fail_under: 90
    cov_reports: html,xml,term
  types:
    checker: ty
  check:
    tasks: format-python,format-docstrings,lint,types,imports,unit
    cov: false
  fix:
    tasks: lint,format-python,format-docstrings

Only tasklib.package.name (the distribution name, as on PyPI) is required. Everything else has a default, and most of the paths defaults are derived from package.name or from paths.tests.

Defaults

Key Default
package.name required
package.import_name <package.name> with - replaced by _
package.python_version not set: uv venv chooses the version
paths.src src/<package.import_name>, or <package.import_name> if only that directory exists
paths.tests tests
paths.unit_tests <paths.tests>/unit
paths.integration_tests <paths.tests>/integration
paths.functional_tests <paths.tests>/functional
paths.benchmarks <paths.tests>/benchmarks
paths.docs_config docs/mkdocs.yml
groups.install dev
groups.update dev,docs
test.unit_timeout 10
test.integration_timeout 60
test.functional_timeout 60
test.xdoctest true
test.timeout true
test.cov_fail_under not set
test.cov_reports html,xml,term
types.checker ty
check.tasks not set (format-python,format-docstrings,lint,types,imports,unit)
check.cov false
fix.tasks not set (lint,format-python,format-docstrings)

The test section sets the per-test timeout in seconds of each test scope, whether pytest runs with --xdoctest (it requires the xdoctest package, so set xdoctest: false if the project does not have it; test.doctest-src ignores it and always uses the plugin), whether it runs with --timeout (it requires the pytest-timeout package, so set timeout: false if the project does not have it; the unit_timeout, integration_timeout and functional_timeout values are then unused), and a coverage threshold: with --cov, cov_fail_under is forwarded as --cov-fail-under. Timeouts and cov_fail_under are integers, xdoctest and timeout are booleans. cov_reports is a comma-separated string or a list of the --cov-report values of pytest-cov (html, xml, json, lcov, annotate, term, term-missing) that --cov generates. A value can have the argument of pytest-cov after a colon, for example term-missing:skip-covered or html:cov_html (the directory or file of the report). The value is quoted in the command. An empty value passes no --cov-report, so pytest-cov uses its default.

types.checker is the type checker of types.check and of the types step of check.all: ty (default), pyright or mypy. With --complete, types.check also runs pyright after it (unless it is pyright). mypy is not installed by env.install: add it to the project dependencies.

check.cov is a boolean. If true, the unit step of check.all runs with --cov, so test.cov_fail_under is enforced there too (the coverage reports are generated).

check.tasks is a comma-separated string or a list of the steps of check.all, run in the order of the list below. It is not set by default (null in config.show), which means the first six steps below (format-python to unit). The names are checked by check.all, before any step runs (exit code 2). The steps are: format-python, format-docstrings, lint, types, imports, unit, doctest, shell, spelling, docs and audit. It must have at least one step and no unknown step.

fix.tasks is the same for the steps of fix.all (not set means lint, format-python and format-docstrings): lint, format-python, format-docstrings and shell, run in that order (the lint fixes first, so that the formatting has the last word on the layout).

package.import_name is the name used to import the package. It is used by imports.check-cycles, imports.check-isolated, release.build (the import check of the built artifacts) and the --cov option of the test tasks. Set it when it is not the distribution name with - replaced by _. It must be a Python module name, which may be dotted for a package of a namespace package (company.package): the tasks that read the source of the package (imports.check-cycles, imports.check-isolated) find it without importing company.

If tasklib.package.name is missing, get_config raises a ValueError; the tasks use load_config, which turns it into an invoke.exceptions.Exit with the same message and the exit code 2 (no traceback).

Unknown keys in tasklib itself (typically a typo of a section such as path) and in the package, paths, groups, test, types, check or fix sections (such as paths.unit_test) also raise a ValueError that lists the valid keys and suggests the closest one, instead of being silently ignored. Each section must be a mapping, package.name and every paths.* value must be a non-empty string, and test.cov_fail_under must be between 0 and 100. A null (~) is the same as not setting the key only for a key that has no default (test.cov_fail_under, package.python_version, check.tasks, fix.tasks); for a boolean or an integer (test.xdoctest, test.unit_timeout, check.cov, ...) it is an error, like any other invalid value, so write the value or remove the key.

package.python_version must be a quoted string such as "3.10" or "3.10.4". YAML reads an unquoted 3.10 as the number 3.1, so get_config raises a ValueError for any non-string or malformed value instead of silently creating a virtual environment with the wrong Python.

When the key is not set (null in config.show), env.create-venv does not pass --python and uv venv chooses the version: the one of the .python-version file if there is one, else the newest interpreter that satisfies project.requires-python of pyproject.toml, else the newest one that is available. Set the key to pin the version of the virtual environment.

Showing the Resolved Config

invoke config.show

Prints the tasklib section as the tasks see it, with every key and a comment with its origin. It answers "which value is used, and why" without reading the code:

tasklib:
  package:
    name: demo # project file
    import_name: demo # derived
  paths:
    src: lib # project file
    tests: zz # environment variable INVOKE_TASKLIB_PATHS_TESTS
    unit_tests: zz/unit # derived
    docs_config: docs/mkdocs.yml # default

The origin is the source with the highest priority that sets the key: default (the default of the library, or no value for an optional key), project file (invoke.yaml), environment variable INVOKE_TASKLIB_..., system config file, user config file, runtime config file or override (set from the command line or by code). derived is a value that no source sets, computed from other values or from the project (import_name, src and the test paths). The origins come from private attributes of Invoke (there is no public API for them): if a release of Invoke renames one, the task writes a warning on the error stream that names it, and the check that inv runs from the project root (also based on one of them) writes a RuntimeWarning, instead of going on silently. The config is validated first, so an invalid one stops the task with the usual one-line message. The task reads nothing but the config and the project directories of paths, and changes nothing.

Editor Completion (JSON Schema)

The keys, the defaults and the descriptions are declared once, in invoke_tasklib.config.SCHEMA (one Option per key: default, validation and JSON schema). The defaults, the key checks, the error messages and the JSON schema are all generated from it, so they cannot drift. Print the schema of the tasklib section of invoke.yaml with:

python -m invoke_tasklib.config > invoke-tasklib.schema.json

The same file is published with the documentation. Point your editor to it with a comment at the top of invoke.yaml to get completion and validation of the keys:

# yaml-language-server: $schema=https://durandtibo.github.io/invoke-tasklib/schema.json
tasklib:
  package:
    name: my_package

A test checks that the published docs/docs/schema.json equals the schema printed by the command (regenerate it with python -m invoke_tasklib.config > docs/docs/schema.json).

Working Directory

Run inv from the directory of tasks.py (the project root). Invoke finds tasks.py and invoke.yaml in the parents of the current directory, but the tasks use paths relative to the current directory, so any task that reads the config exits with code 2 and a message when the current directory is another one (see Troubleshooting).

Environment Variables

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. This is handy in CI. It works because make_ns registers the defaults of the tasklib section with Invoke, which only reads the environment variables of the keys that it knows. The usual Invoke order applies: the environment variables win over invoke.yaml.

Invoke reads an environment variable as a string, and tasklib parses it:

  • a boolean (INVOKE_TASKLIB_TEST_XDOCTEST, ..._TEST_TIMEOUT, ..._CHECK_COV) is one of true, false, 1, 0, yes, no, on and off, in any case. Any other text is an error;
  • an integer (the timeouts, test.cov_fail_under) is a string of digits. Any other text is an error.

An invalid value exits with code 2 and a one-line message, like an invalid invoke.yaml. The same spellings work for a string value in invoke.yaml. A collection built by hand (Collection(lint, ...)) has no defaults, so it does not read the environment variables unless you call ns.configure({"tasklib": invoke_tasklib.config.default_config()}). default_config() holds an empty placeholder for every key, not its default: read the config with load_config (or see it with inv config.show), not from c.config.tasklib.

Minimal Config

The smallest valid invoke.yaml only sets the package name:

tasklib:
  package:
    name: my_package

With this, paths.src resolves to src/my_package, paths.unit_tests resolves to tests/unit, and so on.

Overriding Paths

Override any individual path without affecting the others' defaults, for example when tests live outside tests/:

tasklib:
  package:
    name: my_package
  paths:
    tests: test
    benchmarks: test/perf

Here paths.unit_tests still resolves to <paths.tests>/unit, i.e. test/unit, since it is derived from the overridden paths.tests.

Overriding Dependency Groups

env.install and env.update install uv dependency groups by name. Projects that define more groups than dev/docs (e.g. test, lint) can change the defaults those tasks use, instead of passing --groups on every invocation:

tasklib:
  package:
    name: my_package
  groups:
    install: dev,test
    update: dev,test,docs

Each value can also be written as a YAML list, which is joined with commas:

tasklib:
  groups:
    install: [dev, test]
    update: [dev, test, docs]

The --groups flag of the tasks stays a comma-separated string (--groups dev,docs).

Using get_config in a Custom Task

get_config returns frozen dataclasses (cfg.package, cfg.paths, cfg.groups, cfg.test, cfg.types, cfg.check and cfg.fix), so the values are read as attributes and cannot be modified. It raises a ValueError on an invalid config. A task uses load_config, which exits with a one-line message instead (and also checks that inv runs from the project root), like every built-in task, so a project-specific task reads the same config:

from invoke.tasks import task
from invoke_tasklib.config import load_config
from invoke_tasklib.output import say


@task
def my_task(c):
    cfg = load_config(c)
    say(c, f"{cfg.package.name} {cfg.paths.src}")

Use get_config outside a task, where a ValueError is the right error.

See Also