Skip to content

Writing a Custom Task

📖 This page shows how to write a task of your own that behaves like the tasks of invoke-tasklib. The helpers below are the supported public API for that: they are the names in the __all__ of runner, tools, output and config (a test compares this page with them), and their signatures are documented in the reference pages (runner, tools, output and config). Anything else in these modules starts with an underscore and can change without notice.

Overview

Helper Use it to
invoke_tasklib.config.load_config Read the resolved config; an invalid one exits cleanly
invoke_tasklib.runner.build_command Build a command (a list of words) with the args and paths
invoke_tasklib.runner.run Run a command (a list of words): echo, pty, program check
invoke_tasklib.runner.in_ci Tell whether CI is on (CI=false and CI=0 are off)
invoke_tasklib.runner.in_github_actions Tell whether GITHUB_ACTIONS is true
invoke_tasklib.runner.capture Run a command and read its output: hidden, not echoed, no pty
invoke_tasklib.tools.check_program Check that the program of a command is installed
invoke_tasklib.tools.find_tool Find a program on the PATH, or a Python module of the interpreter
invoke_tasklib.runner.split_args Split the value of an option like a shell does
invoke_tasklib.output.say Print a progress message
invoke_tasklib.output.step Print the start and the end of a step, and ❌ Failed: ... on error
invoke_tasklib.output.report_failure Print ❌ Failed: ... if a block raises, for a task that uses say

More helpers, for a task that needs less common things:

Helper Use it to
invoke_tasklib.runner.python_executable Get the interpreter that runs Invoke, as a word of a command
invoke_tasklib.runner.ARGS_HELP, PATHS_HELP, TOOL_HELP Reuse the help text of the args and paths options
invoke_tasklib.tools.hint, not_found_message, tool_path Say how to install a tool, or find the PATH of the tools
invoke_tasklib.tools.Tool, TOOLS Read the table of the programs and modules that the tasks run
invoke_tasklib.config.get_config Resolve the config and raise ValueError (load_config exits)
invoke_tasklib.config.TasklibConfig, PackageConfig, PathsConfig Type the resolved config and its sections
invoke_tasklib.config.GroupsConfig, TestConfig, TypesConfig (the other sections)
invoke_tasklib.config.CheckConfig, FixConfig (the other sections)
invoke_tasklib.config.SCHEMA, Option, default_config, json_schema Read the declaration of the keys, their defaults and the JSON schema

Example

# tasks.py
from invoke.tasks import task

from invoke_tasklib import make_ns
from invoke_tasklib.config import load_config
from invoke_tasklib.output import step
from invoke_tasklib.runner import TOOL_HELP, build_command, run


@task(help=TOOL_HELP)
def check_complexity(c, *, args=None, paths=None):
    r"""Check the complexity of the code with radon."""
    cfg = load_config(c)
    with step(c, "🔍 Checking the complexity...", "✅ Complexity check passed"):
        command = build_command(
            ["radon", "cc"], args=args, paths=paths, default_paths=[cfg.paths.src]
        )
        run(c, command)


ns = make_ns()
ns.add_task(check_complexity)
  • Read the config with load_config(c), not from c.config: it merges the defaults, validates the values and exits with a one-line message on an invalid config. The tasklib section is available as cfg.package, cfg.paths, cfg.groups, cfg.test, cfg.types, cfg.check and cfg.fix.
  • A command is a list of words, never a string: ["radon", "cc", "src"]. Do not quote anything and do not split a string yourself. build_command(words, args=, paths=, default_paths=) adds the user's args and paths (and the default paths) to the words; the two options are split like a shell does, each word stays one word.
  • Run it with run: run quotes each word (shlex.join) in the only place that builds the shell line, so a space or a ; never splits or injects a command. For the same reason a glob (*.py), ~ or $HOME reaches the tool as it is: the shell does not expand it. A string raises a TypeError.
  • run also echoes the command, uses a pty only on a terminal, and first checks that the program is on the PATH (with an installation hint if it is not). Only the first word of the command is checked. A command whose program is a shell function or an alias, which is not on the PATH, needs run(c, command, check=False); a shell operator (|, &&, >) cannot be used, because each word is quoted: run the two commands one after the other. Do not call c.run directly. For python -m <module>, the module is checked only when the command uses the running interpreter (python_executable(), the one that runs invoke): for another interpreter or a python found on the PATH, a missing module is reported by Python itself (No module named ...), without a hint. Use python_executable() in your commands, as the first word of a list: run(c, [python_executable(), "-m", "pytest"]) (run quotes each word of a list).
  • Read the output with capture when the code needs it: it is run with the output hidden, the command not echoed and no pty, so a warning on stderr is never read as data.
  • Report the step with step: it prints the start message, then the done message, or ❌ Failed: <what was being done> on the error stream (stderr, like the message of an Exit) if the block raises (the exception is raised again, so the exit code is unchanged). Use say for any other message (say(c, msg, err=True) writes to stderr); neither fails on a terminal that cannot encode an emoji: ✅, ❌ and ⏭️ become [ok], [fail] and [skip], the other emojis are removed and any other character the stream cannot encode (an accent) becomes ?. Set INVOKE_TASKLIB_ASCII=1 to get this output on any terminal.

Follow the naming convention of the shared tasks: check_<target> never modifies a file and fix_<target> does. Add the task to a make_ns() result, as above, so it does not leak into other importers.

>>> from invoke_tasklib.runner import build_command
>>> build_command(["radon", "cc"], args="-s", paths="a.py 'my dir'", default_paths=["src"])
['radon', 'cc', '-s', 'a.py', 'my dir']

Adding a Shortcut for an Existing Task

add_task with a name registers a task of the library under one more name, at the top level of the collection. The task keeps its own name in its namespace:

>>> from invoke_tasklib import make_ns
>>> from invoke_tasklib.release import build
>>> ns = make_ns()
>>> ns.add_task(build, name="build-package")
>>> "build-package" in ns.task_names
True
>>> "release.build" in ns.task_names
True

The tasks.py of this repository does it for release.build: inv build-package is the command that the composite action durandtibo/build-pypi-package-action runs, as the release workflow shows. Such a shortcut shows up in invoke --list of the project, so add one only for a name that something else (a CI action, a script) depends on.

Testing a Custom Task

invoke.context.MockContext records the commands without running them:

>>> from invoke.config import Config
>>> from invoke.context import MockContext
>>> from invoke_tasklib.runner import run
>>> c = MockContext(config=Config(), run=True)
>>> _ = run(c, ["ls", "my dir"])
>>> c.run.call_args.args[0]
"ls 'my dir'"

See Also