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. |
validate |
Callable[[str, object], object]
|
Check a raw value and return the resolved one. It
raises |
json_schema |
Mapping[str, object]
|
The JSON schema of the key, without |
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 |
dict[str, dict[str, object]]
|
|
dict[str, dict[str, object]]
|
|
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 |
TasklibConfig
|
|
TasklibConfig
|
sections, each a frozen dataclass too, e.g. |
TasklibConfig
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If the config is invalid: an unknown key, a missing
|
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 |
Raises:
| Type | Description |
|---|---|
Exit
|
If |
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'