Rich Python

Rich Python

Design terminal output around a render target and data contract. Rich objects describe presentation; a Console decides capabilities, dimensions, stream, and rendering.

Boundary

Use this skill when a Python project already uses Rich or the user requests Rich terminal output. Do not introduce styling into stdout promised as JSON, CSV, a pipe protocol, or another machine-readable format. Do not use Rich to define command arguments (use the CLI framework), to replace structured logs, or to build a web interface.

Know the objects

Read the rendering model when output breaks under redirection, width changes, markup-like data, or tests.

Ordered workflow

1. Classify the channel: human stdout, diagnostics stderr, machine stdout, captured test output, file export, or interactive TTY.
2. Identify the semantic structure: prose, records, hierarchy, source, progress, or a changing dashboard. Choose one matching renderable.
3. Create or reuse a Console at the application boundary. Inject it into code that must be testable; do not scatter independently configured consoles.
4. Convert untrusted/dynamic strings to literal Text or escape markup. Never interpolate user text inside markup tags.
5. Define width, overflow, wrapping, and empty-state behavior. Tables need stable column meaning, not one visual column per arbitrary key.
6. Put transient output in a context manager so teardown occurs on errors.
7. Test at a fixed width with color disabled unless ANSI output itself is the contract. Test non-TTY behavior for progress/live code.

Intent to renderable

Canonical static output

from rich.console import Console
from rich.table import Table
from rich.text import Text


def render_jobs(console: Console, jobs: list[dict[str, object]]) -> None:
    table = Table("ID", "State", "Owner", show_header=True)
    for job in jobs:
        state = str(job["state"])
        state_text = Text(state, style="green" if state == "ready" else "yellow")
        table.add_row(str(job["id"]), state_text, Text(str(job["owner"])))
    console.print(table if jobs else Text("No jobs.", style="dim"))

Text(str(value)) keeps brackets and markup-like input literal. repr-style highlighting is not a stable serialization format.

Streams and terminal capability

• Reserve stdout for the documented primary result. Send diagnostics to a console configured with stderr=True.
• Let Rich auto-detect terminal capability for ordinary execution. Do not force color or interactive mode to make redirected output look like a TTY.
• Respect NO_COLOR, dumb terminals, narrow width, and noninteractive CI.
• Use force_terminal, force_interactive, or a fixed width only when the caller/test explicitly owns that rendering environment.
• If the command supports --json, bypass Rich on stdout entirely; Rich may still render errors to stderr.

Progress and live lifecycle

Choose Progress when task completion is the primary state. Choose Live when the whole view changes. Keep one active live display per console; print through its console so messages do not corrupt the frame. Update at meaningful work boundaries, not every byte or tight-loop iteration. Always use with so final refresh and cursor restoration occur after success or failure.

Read progress and live rules before combining tasks, nesting displays, redirecting output, or running in CI.

Deterministic verification

Inject Console(file=StringIO(), width=<fixed>, color_system=None, force_terminal=False) for semantic text tests. Use console.capture() for a small local capture. Assert content, row order, empty state, and absence of ANSI codes; avoid full snapshots unless exact layout is contractual. Read testing terminal output.

Inspect the installed version of Rich and its signatures when a constructor keyword, environment override, or live behavior may drift. The authoring anchors were executed on Rich 15.0.0; official rendered docs may show an earlier stable version. Completion requires correct stream separation, safe dynamic text, readable narrow/non-TTY output, managed live teardown, deterministic tests, and no Rich formatting in machine-readable output.

References

• Rendering model and markup safety
• Progress and Live lifecycle
• Testing terminal output