Tools
invoke_tasklib.tools ¶
Find the tools that the tasks run and say how to install them.
invoke_tasklib.tools.TOOLS
module-attribute
¶
TOOLS: dict[str, Tool] = {
tool.name: tool
for tool in (
Tool("uv", hint=f"Install uv, see {_UV_URL}."),
Tool(
"uvx",
hint=f"Install uv, which provides uvx, see {_UV_URL}.",
),
Tool(
"git",
hint=_system_hint(
"git",
extra=", or on macOS `xcode-select --install`",
),
),
Tool("ruff", group="dev"),
Tool("ty", group="dev"),
Tool("pyright", group="dev"),
Tool(
"mypy",
hint="Add mypy to the dependencies of the project, e.g. `uv add --dev mypy`.",
),
Tool("docformatter", group="dev"),
Tool(
"codespell",
hint="Add codespell to the dependencies of the project, e.g. `uv add --dev codespell`.",
),
Tool("pre-commit", group="dev"),
Tool("shellcheck", hint=_system_hint("shellcheck")),
Tool("shfmt", hint=_system_hint("shfmt")),
Tool("mkdocs", group="docs"),
Tool("mike", group="docs"),
Tool("pytest", "module", group="dev"),
Tool("coverage", "module", group="dev"),
Tool(
"xdoctest",
"module",
group="dev",
plugin_options=("--xdoctest",),
),
Tool(
"pytest_timeout",
"module",
group="dev",
plugin_options=("--timeout",),
),
Tool(
"pytest_cov",
"module",
group="dev",
plugin_options=(
"--cov",
"--cov-report",
"--cov-append",
"--cov-fail-under",
"--cov-branch",
"--cov-config",
"--no-cov",
),
),
Tool(
"pytest_benchmark",
"module",
group="dev",
plugin_options=(
"--benchmark-only",
"--benchmark-compare",
"--benchmark-disable",
),
),
)
}
Every program and module that the tasks run, by name.
It is the one place to edit to add a tool: hint,
not_found_message, env.check-tools and the check of the pytest
plugins read it. Names are unique across the programs and the modules.
invoke_tasklib.tools.Tool ¶
Bases: NamedTuple
A program or a Python module that the tasks run.
Example usage:
>>> from invoke_tasklib.tools import Tool
>>> Tool("ruff", group="dev").kind
'program'
invoke_tasklib.tools.Tool.group
class-attribute
instance-attribute
¶
group: str | None = None
The dependency group that provides the tool, if uv sync
--group <group> installs it.
invoke_tasklib.tools.Tool.hint
class-attribute
instance-attribute
¶
hint: str | None = None
How to install a tool that no group provides.
It replaces the hint built from group.
invoke_tasklib.tools.Tool.kind
class-attribute
instance-attribute
¶
kind: Literal['program', 'module'] = 'program'
Whether the tool is looked up on the PATH or as a module.
invoke_tasklib.tools.Tool.name
instance-attribute
¶
name: str
The name of the program, or of the module (pytest_cov).
invoke_tasklib.tools.check_program ¶
check_program(command: Sequence[str]) -> None
Check that the program of a command is available.
The command is a program and its arguments, as a list of words: only
the first word is looked up. It is not checked when it is a path
(for example the running interpreter, see python_executable, or
~/bin/tool). For python -m <module> with the running
interpreter, the module is checked, and so are the plugins of the
pytest options (see _PLUGIN_OPTIONS).
The words are never given to a shell parser, so a program that is a
shell builtin or a shell function or alias is not found: pass
check=False to run to run it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
command
|
Sequence[str]
|
The words of the command. |
required |
Raises:
| Type | Description |
|---|---|
Exit
|
If the program (or the module) is not found. The message
says how to install it, see |
Example usage:
>>> from invoke_tasklib.tools import check_program
>>> check_program(["/bin/sh", "-c", "true"])
>>> check_program(["no-such-program", "--version"])
Traceback (most recent call last):
...
invoke.exceptions.Exit: ...
invoke_tasklib.tools.find_tool ¶
find_tool(name: str, *, module: bool = False) -> str | None
Find a program on the tool path or a module of the interpreter.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The name of the program, or of the module. |
required |
module
|
bool
|
If True, look |
False
|
Returns:
| Type | Description |
|---|---|
str | None
|
The path of the program or of the module, or |
str | None
|
not available. |
Example usage:
>>> from invoke_tasklib.tools import find_tool
>>> find_tool("no-such-program") is None
True
>>> find_tool("no_such_module", module=True) is None
True
invoke_tasklib.tools.hint ¶
hint(name: str) -> str
Return how to install a program or a Python module.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The name of the program, or of the Python module. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The |
str
|
installs its dependency group; else |
str
|
is not in |
Example usage:
>>> from invoke_tasklib.tools import hint
>>> hint("uv")
'Install uv, see https://docs.astral.sh/uv/getting-started/installation/.'
>>> hint("mike")
"Install it with the 'docs' group: `uv sync --group docs`."
>>> hint("pytest")
"Install it with the 'dev' group: `uv sync --group dev`."
invoke_tasklib.tools.not_found_message ¶
not_found_message(
name: str,
*,
module: bool = False,
interpreter: str | None = None,
) -> str
Build the message for a program or a module that is missing.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The name of the program, or of the Python module. |
required |
module
|
bool
|
If True, |
False
|
interpreter
|
str | None
|
The interpreter the module is looked up for. Default is the running one. |
None
|
Returns:
| Type | Description |
|---|---|
str
|
The message, with how to install the tool, see |
Example usage:
>>> from invoke_tasklib.tools import not_found_message
>>> not_found_message("uv")[:36]
"'uv' was not found on the PATH or ne"
invoke_tasklib.tools.tool_path ¶
tool_path() -> str
Return the PATH that the tasks use to find the programs.
The directory of the running interpreter comes first: it is where
uv sync installs the programs (ruff, ty, mkdocs,
...) of the virtual environment. Python modules are found with the
running interpreter, so the programs of the same environment are
found the same way, with no need to activate it. It also makes the
task run the program of the environment, not another one that is
earlier on the PATH.
Returns:
| Type | Description |
|---|---|
str
|
The |
str
|
|
Example usage:
>>> import os
>>> from pathlib import Path
>>> import sys
>>> from invoke_tasklib.tools import tool_path
>>> first = tool_path().split(os.pathsep)[0]
>>> first == str(Path(sys.executable).parent)
True