Python Output Styler

Python Output Styling

Style all user-facing Python script output using the bundled style.py module.

Workflow

1. Read [references/style.py](references/style.py) to understand available functions
2. If style.py doesn't exist alongside the target script, copy from [references/style.py](references/style.py) into the same directory
3. Import functions in the target script: from style import header, success, error, info, section
4. Replace raw print() statements with styled output function calls
5. Replace input() prompts with styled_input, confirm, or choose as appropriate
6. Wrap long-running iterables with progress for animated feedback
7. Wrap long-running functions with spin for animated spinner feedback
8. Verify script still works when Rich is not installed (graceful degradation to plain print)

Dependency

Rich is the preferred rendering backend. Install via:

uv run --with rich script.py

When Rich is unavailable, all functions fall back to plain print() output automatically.

Color Palette

| Name | Hex | Rich Markup | Use | |---------|-----------|--------------------|------------------------------| | Brand | #AF87FF | [bold #AF87FF] | Headers, emphasis | | Success | #87D787 | [#87D787] | Checkmarks, completion | | Error | #FF5F5F | [#FF5F5F] | Errors, failures | | Warning | #FFD75F | [#FFD75F] | Warnings, caution | | Info | #87CEEB | [#87CEEB] | Info messages, tips | | Muted | #808080 | [#808080] | Paths, secondary text |

Output Functions

| Function | Symbol | Color | Purpose | |----------|--------|-------|---------| | header(title, subtitle="") | box | Brand | Bordered header panel | | section(text) | ━━ | Brand | Horizontal rule divider | | success(text) | ✓ | Success | Completed actions | | error(text) | ✗ | Error | Error messages | | warn(text) | ⚠ | Warning | Warnings | | info(text) | ● | Info | Informational | | step(text) | → | Muted | Action log (suppressed when quiet) | | note(text) | — | Muted | "Note:" prefixed | | banner(text) | box | Success | Completion banner | | error_block(*lines) | │ | Error | Multi-line error box | | list_item(label, value) | • | Brand+Muted | Key-value display | | dim(text) | — | Muted | De-emphasized text (suppressed when quiet) |

Utility Functions

| Function | Purpose | |----------|---------| | table(headers, *rows) | Formatted table with headers. headers is a list of strings, each row is a list of strings | | pretty(obj) | Rich inspect for any Python object (falls back to pprint) |

Progress Functions

| Function | Returns | Purpose | |----------|---------|---------| | progress(iterable, label="") | Wrapped iterable | Rich progress bar wrapping any iterable | | spin(title, func, *args, **kwargs) | Function result | Animated spinner wrapping a function call |

Interactive Functions

| Function | Returns | Purpose | |----------|---------|---------| | confirm(prompt, default=True) | bool | y/n prompt | | choose(header, *options) | str | Numbered selection menu | | styled_input(prompt, password=False) | str | Styled text input (avoids shadowing built-in input) |

Pattern Mapping

| Old Pattern | New Pattern | |-------------|-------------| | print("Title") + print("=====") | header("Title", "Subtitle") | | print("✓ done") | success("done") | | print("Error: ...") | error("...") | | print("Warning: ...") | warn("...") | | print(" - Label: value") | list_item("Label", "value") | | input("Continue? (y/n) ") | confirm("Continue?") | | print("Section...") between blocks | section("Section") | | print("Note: ...") | note("...") | | Multi-line error block | error_block("line1", "line2") | | Numbered menu with input() | choose("Pick one:", "A", "B", "C") | | input("Name: ") | styled_input("Name:") | | getpass.getpass("Password: ") | styled_input("Password:", password=True) | | for item in items: ... (slow) | for item in progress(items, "Processing"): ... | | Long function call with no feedback | result = spin("Installing...", install_pkg, "name") | | pprint(obj) | pretty(obj) |

Environment Variables

| Variable | Default | Effect | |----------|---------|--------| | NO_COLOR | unset | Disables all color output when set to any value | | STYLE_VERBOSE | 1 | 0=quiet (suppresses step/dim), 1=default, 2=verbose |

Rules

• ALWAYS import from style.py — never use Rich directly in scripts
• NEVER hard-code ANSI codes in scripts — use style.py functions exclusively
• Use styled_input instead of input for styled prompts to avoid shadowing the built-in
• confirm returns a bool — use directly in if confirm("Continue?"): ...
• spin returns the wrapped function's return value — use: result = spin("Building...", build_fn)
• choose returns the selected option string — use: choice = choose("Pick:", "A", "B")
• progress wraps an iterable — use: for item in progress(items, "Processing"): ...
• Do NOT wrap instant operations with spin — only use for functions that take noticeable time
• Preserve all existing logic — only change output formatting, never behavior
• Scripts must work identically when Rich is not installed (plain print fallback)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tsilva
• Source: tsilva/claudeskillz
• License: MIT

Install and usage instructions live in the source repository linked above.