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 fromc.config: it merges the defaults, validates the values and exits with a one-line message on an invalid config. Thetasklibsection is available ascfg.package,cfg.paths,cfg.groups,cfg.test,cfg.types,cfg.checkandcfg.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'sargsandpaths(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:runquotes 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$HOMEreaches the tool as it is: the shell does not expand it. A string raises aTypeError. runalso echoes the command, uses a pty only on a terminal, and first checks that the program is on thePATH(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 thePATH, needsrun(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 callc.rundirectly. Forpython -m <module>, the module is checked only when the command uses the running interpreter (python_executable(), the one that runsinvoke): for another interpreter or apythonfound on thePATH, a missing module is reported by Python itself (No module named ...), without a hint. Usepython_executable()in your commands, as the first word of a list:run(c, [python_executable(), "-m", "pytest"])(runquotes each word of a list).- Read the output with
capturewhen the code needs it: it isrunwith 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 anExit) if the block raises (the exception is raised again, so the exit code is unchanged). Usesayfor 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?. SetINVOKE_TASKLIB_ASCII=1to 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¶
- Config: the
tasklibsection thatload_configresolves. invoke_tasklib.runnerreferenceinvoke_tasklib.toolsreferenceinvoke_tasklib.outputreference