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