Skip to content

Config

invoke_tasklib.config

Config resolution for invoke-tasklib tasks.

Consuming projects set project-specific values under a tasklib key in their invoke.yaml, e.g.::

tasklib:
  package:
    name: coola
  paths:
    docs_config: docs/mkdocs.yml

Only package.name (the distribution name) is required; everything else has a default derived from it. package.import_name defaults to the name with - replaced by _.

invoke_tasklib.config.SCHEMA module-attribute

SCHEMA: dict[str, dict[str, Option]] = {
    "package": {
        "name": Option(
            None,
            _validate_str,
            _STRING,
            "Distribution name, as on PyPI (required).",
        ),
        "import_name": Option(
            None,
            _validate_import_name,
            _STRING,
            "Name used to import the package (default: name with - replaced by _).",
        ),
        "python_version": Option(
            None,
            _validate_python_version,
            {
                "type": "string",
                "pattern": PYTHON_VERSION_PATTERN.pattern,
            },
            "Python version of the virtual environment (default: the one that uv chooses, see .python-version and requires-python).",
        ),
    },
    "paths": {
        "src": _path(
            None,
            "Source directory (default: src/<import_name>).",
        ),
        "tests": _path("tests", "Tests directory."),
        "unit_tests": _path(
            None, "Unit tests (default: <tests>/unit)."
        ),
        "integration_tests": _path(
            None,
            "Integration tests (default: <tests>/integration).",
        ),
        "functional_tests": _path(
            None,
            "Functional tests (default: <tests>/functional).",
        ),
        "benchmarks": _path(
            None,
            "Benchmarks (default: <tests>/benchmarks).",
        ),
        "docs_config": _path(
            "docs/mkdocs.yml", "MkDocs configuration file."
        ),
    },
    "groups": {
        "install": Option(
            ("dev",),
            _normalize_groups,
            _NAMES,
            "Dependency groups of env.install (comma-separated string or list).",
        ),
        "update": Option(
            ("dev", "docs"),
            _normalize_groups,
            _NAMES,
            "Dependency groups of env.update (comma-separated string or list).",
        ),
    },
    "test": {
        "unit_timeout": _timeout(
            10, "Timeout in seconds of each unit test."
        ),
        "integration_timeout": _timeout(
            60,
            "Timeout in seconds of each integration test.",
        ),
        "functional_timeout": _timeout(
            60,
            "Timeout in seconds of each functional test.",
        ),
        "xdoctest": Option(
            True,
            _validate_bool,
            {"type": "boolean"},
            "Run pytest with --xdoctest.",
        ),
        "timeout": Option(
            True,
            _validate_bool,
            {"type": "boolean"},
            "Run pytest with --timeout (it requires pytest-timeout).",
        ),
        "cov_fail_under": Option(
            None,
            _validate_cov_fail_under,
            {
                "type": ["integer", "null"],
                "minimum": 0,
                "maximum": 100,
            },
            "Coverage threshold passed to --cov-fail-under.",
        ),
        "cov_reports": Option(
            ("html", "xml", "term"),
            _validate_cov_reports,
            {
                "anyOf": [
                    {"type": "string"},
                    {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "pattern": _COV_REPORT_PATTERN,
                        },
                    },
                ]
            },
            "Coverage reports generated by --cov (formats, with an optional :argument).",
        ),
    },
    "types": {
        "checker": Option(
            "ty",
            _validate_checker,
            {"enum": list(TYPE_CHECKERS)},
            "Type checker of types.check and of the types step of check.all.",
        )
    },
    "check": {
        "tasks": Option(
            None,
            _validate_steps,
            _NAMES,
            "Steps of check.all (comma-separated string or list); null for the default steps.",
        ),
        "cov": Option(
            False,
            _validate_bool,
            {"type": "boolean"},
            "Run the unit step of check.all with --cov, so cov_fail_under is enforced.",
        ),
    },
    "fix": {
        "tasks": Option(
            None,
            _validate_steps,
            _NAMES,
            "Steps of fix.all (comma-separated string or list); null for the default steps.",
        )
    },
}

The declaration of every key of the tasklib config, by section.

It is the single source of the known keys, the defaults, the validation and the JSON schema.

invoke_tasklib.config.CheckConfig dataclass

Resolved check config section.

invoke_tasklib.config.FixConfig dataclass

Resolved fix config section.

invoke_tasklib.config.GroupsConfig dataclass

Resolved groups config section.

invoke_tasklib.config.Option dataclass

Declaration of one key of the tasklib config.

It is the single place that declares the key.

Attributes:

Name Type Description
default object

The default value. None means that the default is derived from other values (see get_config), that the key is required (package.name), that the key is not set (package.python_version, test.cov_fail_under), or that the composite task chooses the steps (check.tasks, fix.tasks). A default is a tuple for a list.

validate Callable[[str, object], object]

Check a raw value and return the resolved one. It raises ValueError with a message that names the key.

json_schema Mapping[str, object]

The JSON schema of the key, without default.

doc str

One-line description, used by the JSON schema.

invoke_tasklib.config.PackageConfig dataclass

Resolved package config section.

invoke_tasklib.config.PathsConfig dataclass

Resolved paths config section.

invoke_tasklib.config.TasklibConfig dataclass

Resolved tasklib config.

invoke_tasklib.config.TestConfig dataclass

Resolved test config section.

invoke_tasklib.config.TypesConfig dataclass

Resolved types config section.

invoke_tasklib.config.default_config

default_config() -> dict[str, dict[str, object]]

Return the defaults of the tasklib config section.

The defaults are registered with Invoke (see make_ns) so that the keys can also be set with the INVOKE_TASKLIB_<SECTION>_<KEY> environment variables, for example INVOKE_TASKLIB_PATHS_SRC. Invoke only reads an environment variable for a key that exists in the defaults. Invoke casts the variable to the type of the default, and it reads any text but 0 as true for a boolean, so every key is registered with an Unset, which is a string: the text is kept and parsed by the validation. The real defaults stay in SCHEMA, where get_config and the JSON schema read them. Read the config with load_config, not from c.config: it holds an Unset for a key that no source sets.

Returns:

Type Description
dict[str, dict[str, object]]

A new dict with the package, paths, groups,

dict[str, dict[str, object]]

test, types, check and fix sections, with an

dict[str, dict[str, object]]

Unset for every key of SCHEMA.

Example usage:

>>> from invoke_tasklib.config import default_config
>>> sorted(default_config())
['check', 'fix', 'groups', 'package', 'paths', 'test', 'types']
>>> default_config()["groups"]
{'install': '', 'update': ''}

invoke_tasklib.config.get_config

get_config(c: Context) -> TasklibConfig

Return the effective tasklib config, merging user overrides from invoke.yaml (under the tasklib key) on top of the defaults.

Parameters:

Name Type Description Default
c Context

The invoke context.

required

Returns:

Type Description
TasklibConfig

A frozen dataclass with the resolved package, paths,

TasklibConfig

groups, test, types, check and fix

TasklibConfig

sections, each a frozen dataclass too, e.g.

TasklibConfig

cfg.paths.src.

Raises:

Type Description
ValueError

If the config is invalid: an unknown key, a missing tasklib.package.name or a value that is not valid. The message names the key. The rules of every key are listed in the user guide, see uguide/config.md.

Example usage:

>>> from invoke.config import Config
>>> from invoke.context import Context
>>> from invoke_tasklib.config import get_config
>>> overrides = {"tasklib": {"package": {"name": "mypkg"}}}
>>> c = Context(config=Config(overrides=overrides))
>>> cfg = get_config(c)
>>> cfg.package.import_name
'mypkg'
>>> cfg.paths.src
'src/mypkg'
>>> cfg.groups
GroupsConfig(install=('dev',), update=('dev', 'docs'))
>>> cfg.test.unit_timeout
10
>>> cfg.check.tasks is None
True

invoke_tasklib.config.json_schema

json_schema() -> dict[str, Any]

Return the JSON schema of the tasklib config.

The schema is generated from SCHEMA, so it cannot drift from the keys and the defaults. It lets an editor complete and check the invoke.yaml file. Other top-level keys (the config of Invoke itself) are allowed.

Returns:

Type Description
dict[str, Any]

The schema, as a dict that can be dumped as JSON.

Example usage:

>>> from invoke_tasklib.config import json_schema
>>> schema = json_schema()
>>> sorted(schema["properties"]["tasklib"]["properties"])
['check', 'fix', 'groups', 'package', 'paths', 'test', 'types']

invoke_tasklib.config.load_config

load_config(c: Context) -> TasklibConfig

Return the effective tasklib config, exiting cleanly on an invalid config.

The tasks use this function instead of get_config so that an invalid config is reported as a one-line message and the exit code 2 rather than as a Python traceback. get_config is the function to use programmatically, because it raises a ValueError.

Parameters:

Name Type Description Default
c Context

The invoke context.

required

Returns:

Type Description
TasklibConfig

The resolved config, see get_config.

Raises:

Type Description
Exit

If get_config raises a ValueError, or if Invoke runs from another directory than the one of tasks.py. The message is the one of the ValueError.

Example usage:

>>> from invoke.config import Config
>>> from invoke.context import Context
>>> from invoke_tasklib.config import load_config
>>> overrides = {"tasklib": {"package": {"name": "mypkg"}}}
>>> c = Context(config=Config(overrides=overrides))
>>> load_config(c).package.name
'mypkg'