Skip to content

Output

invoke_tasklib.output

Output helpers for user-facing progress messages.

invoke_tasklib.output.report_failure

report_failure(c: Context, title: str) -> Generator[None]

Report a failure of a block of a task.

If the block raises, the failure message (❌ Failed: <title without symbol and dots>) is written to the error stream and the exception is raised again. Only an Exception is reported: KeyboardInterrupt goes through. Nothing is written otherwise: use it in a task that writes its own progress messages with say; use step for a block with a start and a done message.

Parameters:

Name Type Description Default
c Context

The invoke context.

required
title str

What was being done, e.g. "📦 Installing project dependencies...".

required

Yields:

Type Description
Generator[None]

Nothing.

Example usage:

>>> from invoke.config import Config
>>> from invoke.context import Context
>>> from invoke_tasklib.output import report_failure
>>> c = Context(config=Config())
>>> with report_failure(c, "🎨 Checking..."):
...     pass
...

invoke_tasklib.output.say

say(c: Context, message: str, *, err: bool = False) -> None

Write a progress message followed by a newline.

The message goes to the output stream configured in the invoke context (run.out_stream), or to sys.stdout if none is configured. With err, it goes to run.err_stream or to sys.stderr instead, like the message of an Exit that invoke prints, so that a failure and its reason are on the same stream. Unlike logging, it needs no logging setup to be visible.

A message never fails a task: if the stream cannot encode a character (for example an emoji on an ASCII terminal), the status symbols are replaced by the tags [ok], [fail] and [skip], the other emojis are removed and any other character the stream cannot encode (an accented letter) becomes ?. Set the environment variable INVOKE_TASKLIB_ASCII to 1 to get this ASCII output on any stream.

Parameters:

Name Type Description Default
c Context

The invoke context.

required
message str

The message to write.

required
err bool

If True, write to the error stream instead of the output stream.

False

Example usage:

>>> from invoke.config import Config
>>> from invoke.context import Context
>>> from invoke_tasklib.output import say
>>> say(Context(config=Config()), "hello")
hello

invoke_tasklib.output.step

step(
    c: Context, start: str, done: str | None = None
) -> Generator[None]

Report the start and the end of a step of a task.

The start message is written when the block is entered and the done message (if there is one) when it exits normally. If the block raises, a failure message (❌ Failed: <start message without symbol and dots>) is written to the error stream instead and the exception is raised again, so that a failed step is visible and not only the output of the tool (see report_failure).

Parameters:

Name Type Description Default
c Context

The invoke context.

required
start str

The message written when the step starts.

required
done str | None

The message written when the step succeeds, or None for a step that has none (its work is the last thing the task says).

None

Yields:

Type Description
Generator[None]

Nothing.

Example usage:

>>> from invoke.config import Config
>>> from invoke.context import Context
>>> from invoke_tasklib.output import step
>>> c = Context(config=Config())
>>> with step(c, "🎨 Checking...", "✅ Done"):
...     pass
...
🎨 Checking...
✅ Done