Skip to content

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 hint.

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 name up as a Python module of the running interpreter instead of as a program. A program is looked up in tool_path().

False

Returns:

Type Description
str | None

The path of the program or of the module, or None if it is

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 hint of the tool in TOOLS; else the command that

str

installs its dependency group; else _DEFAULT_HINT (the tool

str

is not in TOOLS).

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, name is a Python module.

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 hint.

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 PATH of the process with the directory of

str

sys.executable added to the front.

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