Tryboy869 rich Best Practices
rich transforms plain terminal output into engaging, readable interfaces. These rules ensure your rich applications are performant, testable, and follow modern Python best practices.
1. Code Organization: Centralize Console Management
Instantiate Console once per application run. Avoid creating new Console objects in every function or module, as this leads to inconsistent styling, performance overhead, and potential issues with interactive elements. Pass the Console instance explicitly or use a global singleton pattern for CLI applications.
❌ BAD: Repeated Console instantiation
# module_a.py
from rich.console import Console
def do_something():
console = Console() # New console every time
console.print("Doing something...")
# module_b.py
from rich.console import Console
def do_another_thing():
console = Console() # Another new console
console.print("Doing another thing...")
✅ GOOD: Single Console instance
# main.py
from rich.console import Console
from .module_a import do_something
from .module_b import do_another_thing
console = Console() # Instantiate once at the top-level
def main():
console.print("[bold green]Starting application...[/bold green]")
do_something(console)
do_another_thing(console)
console.print("[bold green]Application finished.[/bold green]")
if __name__ == "__main__":
main()
# module_a.py
from rich.console import Console
def do_something(console: Console): # Pass console explicitly
console.print("Doing something...")
# module_b.py
from rich.console import Console
def do_another_thing(console: Console): # Pass console explicitly
console.print("Doing another thing...")
2. Output: Always Use console.print()
For any output intended to be styled or managed by rich, use console.print(). Mixing print() with console.print() can lead to unpredictable output order and styling issues, especially with interactive elements like progress bars or live displays.
❌ BAD: Mixing print() and console.print()
from rich.console import Console
console = Console()
print("This line might appear out of order or unstyled.")
console.print("[red]This is styled.[/red]")
✅ GOOD: Consistent console.print() usage
from rich.console import Console
console = Console()
console.print("This line is managed by rich.")
console.print("[red]This is styled.[/red]")
3. Interactive Elements: Use with Statements
For rich.progress.Progress and rich.live.Live, always use a with statement. This ensures proper resource management, graceful shutdown, and correct rendering behavior, even if errors occur. Failing to use with can leave artifacts in the terminal or prevent proper cleanup.
❌ BAD: Manual start/stop (prone to errors)
from rich.progress import Progress
progress = Progress()
progress.start()
# ... do work ...
progress.stop() # Easy to forget or miss on error
✅ GOOD: with statement for automatic management
from rich.progress import Progress
from rich.console import Console
import time
console = Console()
with Progress(console=console) as progress:
task = progress.add_task("[green]Processing...", total=100)
for _ in range(100):
time.sleep(0.01)
progress.update(task, advance=1)
4. Logging: Integrate RichHandler
Leverage rich.logging.RichHandler for beautiful, readable, and structured logs directly in your terminal. Configure it once at application startup to enhance all standard Python logging output.
import logging
from rich.console import Console
from rich.logging import RichHandler
console = Console()
logging.basicConfig(
level="INFO",
format="%(message)s",
datefmt="[%X]",
handlers=[RichHandler(console=console, show_time=True, show_level=True, show_path=False)]
)
log = logging.getLogger("rich")
def process_data():
log.info("Starting data processing...")
# ... some work ...
log.warning("Potential issue detected during processing.")
# ... more work ...
log.error("Failed to save results!")
if __name__ == "__main__":
process_data()
5. Type Hints: Embrace rich Types
rich provides excellent type annotations. Use them in your function signatures and variable declarations to improve code readability, enable static analysis with Mypy, and catch type-related errors early.
❌ BAD: Untyped rich usage
def display_table(data):
from rich.table import Table
table = Table("Name", "Value")
for row in data:
table.add_row(row[0], str(row[1]))
# ...
✅ GOOD: Type-hinted rich usage
from typing import List, Tuple, Any
from rich.console import Console
from rich.table import Table
def display_table(console: Console, data: List[Tuple[str, Any]]):
table = Table("Name", "Value")
for row_name, row_value in data:
table.add_row(row_name, str(row_value))
console.print(table)
if __name__ == "__main__":
console = Console()
sample_data = [("Item A", 100), ("Item B", "Hello")]
display_table(console, sample_data)
6. Testing: Capture rich Output
When testing rich applications with pytest, capture stdout to assert the content and styling. For more granular control, direct Console output to a StringIO object, allowing you to inspect the raw rich markup.
# my_cli_app.py
from rich.console import Console
def greet(console: Console, name: str):
console.print(f"Hello, [bold blue]{name}[/bold blue]!")
# test_my_cli_app.py
from io import StringIO
from rich.console import Console
from my_cli_app import greet
def test_greet_output_stringio():
# Direct console output to a StringIO object for precise capture
output_buffer = StringIO()
console = Console(file=output_buffer, force_terminal=True) # force_terminal for consistent output
greet(console, "World")
captured = output_buffer.getvalue()
assert "Hello, World!" in captured
assert "[bold blue]World[/bold blue]" in captured # Assert rich markup
def test_greet_output_capsys(capsys): # pytest fixture to capture stdout/stderr
# Use default console which writes to stdout, then capture with capsys
console = Console(force_terminal=True)
greet(console, "Test")
captured_capsys = capsys.readouterr()
assert "Hello, Test!" in captured_capsys.stdout
7. Virtual Environments & Packaging
Always use a virtual environment (venv or pipenv) for rich projects. Define rich as a dependency in pyproject.toml and use pip install -e . for editable installs during development. This ensures consistent environments and proper packaging for your CLI tool, making it easily distributable.
# pyproject.toml
[project]
name = "my-rich-cli"
version = "0.1.0"
dependencies = [
"rich>=13.0.0",
# other dependencies
]
[project.scripts]
my-cli = "my_rich_cli.main:main" # Define entry point for your CLI
# Example: my_rich_cli/main.py
from rich.console import Console
def main():
console = Console()
console.print("[green]Welcome to My Rich CLI![/green]")
# To set up and run your CLI:
# 1. python -m venv .venv
# 2. source .venv/bin/activate (or .venv\Scripts\activate on Windows)
# 3. pip install -e .
# 4. my-cli