rich

Rich 知识

帮助编写正确的 Rich 终端 UI 代码——包括标记、样式化输出、表格、进度跟踪、实时显示、日志集成和自定义可渲染对象。

范围

应用通用架构、类型标注、测试或 CLI 规则时，请参阅 ../python3-development/references/python3-standards.md；完整标准、图表和修订流程均记录在该文件中。

触发条件：编写导入 rich 的 Python 代码，或收到请求，要为 Python CLI 添加终端 UI、彩色输出、进度条、表格、语法高亮或美化输出时，启用此项。

涵盖内容：

• Console 类、标记语法、样式字符串、颜色格式
• 所有可渲染类型（Panel、Table、Tree、Columns、Layout）
• 进度条（track()、Progress）和实时显示
• 用于标准库日志记录的 RichHandler 和 traceback 安装
• Text 类和程序化样式构建
• Syntax、Markdown、Pretty / pprint、JSON
• 自定义对象的 __rich_console__ 和 __rich_repr__ 协议

不涵盖：

• Textual（Rich 的同系列 TUI 框架，是独立库）
• Segment 级别以下的 Rich 内部实现
• Pygments 主题创作

工作流

flowchart TD
    Start([Rich task]) --> Q1{Task type?}
    Q1 -->|Print styled output or markup| Markup[Load console-and-markup.md]
    Q1 -->|Build table, panel, tree, columns| Render[Load renderables.md]
    Q1 -->|Progress bar or live update| Prog[Load progress-and-live.md]
    Q1 -->|Syntax highlight or pretty-print code/data| TextSyn[Load text-and-syntax.md]
    Q1 -->|Logging or traceback display| LogTB[Load logging-and-tracebacks.md]
    Q1 -->|Custom renderable, layout, or highlighter| Adv[Load advanced-patterns.md]

参考文件

Console 和标记

Console 类实例化和构造函数参数、print() / log() / rule() / status() 方法、标记语法（BBCode 风格标签）、样式定义字符串、颜色格式（命名颜色 / 256 位数字 / 十六进制 / RGB）、样式属性（粗体/斜体/下划线等）、Style 类、Theme 类、环境变量、输出捕获和导出。

编写 console.print()、应用颜色/样式、使用 Rich 标记标签或配置 Console 行为时加载。

references/console-and-markup.md

可渲染对象

Panel、Table（add_column、add_row、构造函数选项、列选项）、Tree（add、style、guide_style）、Columns 布局、Padding、Rule、Align 和 Box 样式。包含构造函数签名以及源文档中的所有关键参数原文。

使用框线、表格、树形视图或多列布局构建结构化输出时加载。

references/renderables.md

进度和实时显示

track() 函数、Progress 类（add_task、update、advance）、任务管理（visible、indeterminate、transient）、所有内置列类（BarColumn、TextColumn、TimeRemainingColumn、SpinnerColumn 等）、Live 类和 console.status() 微调指示器。

为 CLI 添加进度跟踪、微调指示器或实时更新输出时加载。

references/progress-and-live.md

文本和语法

Text 类（append、stylize、highlight_regex、assemble、from_markup）、Syntax 类（from_path、line_numbers、theme、line_range）、Markdown 可渲染对象、pprint / Pretty、JSON 可渲染对象，以及带有 @rich.repr.auto 装饰器的 __rich_repr__ 协议。

需要高亮代码块、渲染 Markdown、美化打印数据结构或自定义对象 repr 输出时加载。

references/text-and-syntax.md

日志和 Traceback

RichHandler 构造函数参数（完整表格）、通过 extra={} 为每条消息覆盖标记/高亮器、在日志输出中为异常启用 rich_tracebacks=True、使用 tracebacks_suppress 隐藏框架堆栈帧、使用 traceback.install() 安装全局处理器、console.print_exception() 参数以及 max_frames 的行为。

将 Rich 与 Python 的 logging 模块集成、安装全局 traceback 处理器或改进异常显示时加载。

references/logging-and-tracebacks.md

高级模式

__rich__ 协议（从对象返回可渲染对象）、__rich_console__ 协议（生成可渲染对象或 Segments）、用于报告自定义宽度的 __rich_measure__、Layout 类（split_column、split_row、update、命名窗格）、RegexHighlighter 子类化、内置高亮器、inspect() 函数和 REPL 安装。

编写自定义可渲染对象、构建多窗格全屏布局、实现自定义语法高亮或调试 Python 对象时加载。

references/advanced-patterns.md

Quick Reference

# Install
pip install rich

# Drop-in print replacement
from rich import print
print("[bold red]Hello[/bold red] [green]world[/green]")

# Console (preferred for production code)
from rich.console import Console
console = Console()
console.print("[bold]Hello[/bold]", style="green")
console.rule("[bold red]Section")

# Style string formats
console.print("text", style="bold red underline on white")
console.print("text", style="#af00ff")
console.print("text", style="rgb(175,0,255)")

# Progress bar — simple
from rich.progress import track
for item in track(sequence, description="Processing..."):
    process(item)

# Progress bar — multiple tasks
from rich.progress import Progress
with Progress() as progress:
    task = progress.add_task("[cyan]Working...", total=100)
    progress.update(task, advance=10)

# Logging
import logging
from rich.logging import RichHandler
logging.basicConfig(
    level="NOTSET", format="%(message)s",
    datefmt="[%X]", handlers=[RichHandler()]
)

# Tracebacks
from rich.traceback import install
install(show_locals=True)

# Table
from rich.table import Table
table = Table("Name", "Value")
table.add_row("foo", "bar")
console.print(table)

# Panel
from rich.panel import Panel
console.print(Panel("content", title="Title"))