Skip to content

Formatted messages

Summary

Use the message helpers to present clear output in a Typer CLI, from plain text to a framed panel or operation status.

Overview

typerdrive provides three helpers for output messages:

  • terminal_message displays content in a Rich panel with an optional subject and footer.
  • simple_message prints undecorated text, with optional Markdown rendering and indentation.
  • status_message brackets an operation with starting, completion, and failure lines.

All three functions are available from the typerdrive package and are documented in the API reference.

Usage

This runnable example defines one command for each message helper:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
import typer
from typerdrive import simple_message, status_message, terminal_message

cli = typer.Typer()


@cli.command()
def terminal():
    terminal_message(
        "Your session is ready.",
        subject="Connected",
        footer="Press Ctrl+C to quit",
    )


@cli.command()
def simple():
    simple_message(
        """
        **Sync complete**

        Three files were updated.
        """,
        markdown=True,
        indent=True,
    )


@cli.command()
def status():
    with status_message("search index refresh"):
        print("Indexed 3 documents")

    try:
        with status_message("cache refresh"):
            raise RuntimeError("Cache backend unavailable")
    except RuntimeError:
        pass


if __name__ == "__main__":
    cli()

Run each command from the repository root:

python examples/format/messages.py terminal
python examples/format/messages.py simple
python examples/format/messages.py status

terminal displays a panel titled Connected, with a footer. simple renders a bold Markdown heading and an indented message without a panel. status shows a completed operation followed by a failed operation; it catches the operation's exception after the failure status is printed.

Install the demo extra, then run the interactive message demos:

typerdrive-demo --feature format

See the demo guide for installation and interactive controls.

Details

terminal_message accepts a string or any Rich renderable. String messages are dedented and indented by default; set markdown=True to render them as Markdown. Its optional subject, subject_color, subject_align, footer, and footer_align arguments customize the panel. Set error=True to write to stderr or to_clipboard=True to attempt to copy the message without the panel decoration.

simple_message accepts a string and supports the same Markdown, indentation, stderr, and clipboard options. Its padding option controls whether blank lines surround the output.

status_message is a context manager. It prints a starting line, then reports completion or failure. Exceptions are re-raised after the failure status is printed.