企业官网建设流程全解析

Rich 终端美化库完全指南：用 Python 打造绚丽多彩的命令行输出

【免费下载链接】richRich is a Python library for rich text and beautiful formatting in the terminal.项目地址: https://gitcode.com/gh_mirrors/ri/rich

Rich 是一个专注于在终端中渲染富文本与精美格式的 Python 库，它让你无需触碰底层 ANSI 转义序列，就能为命令行输出添加颜色与样式，并直接渲染漂亮的表格、进度条、Markdown、语法高亮源码、traceback 等。本文以仓库中的 README.tr.md（土耳其语官方文档）为骨架，结合 rich/ 目录下的真实源码实现，系统讲解从安装、快速上手到各内置渲染组件的完整用法，读完你可以在自己的 CLI 工具、调试脚本和日志系统中直接落地这些能力。

兼容性与环境要求

Rich 设计为跨平台库，官方文档明确指出它可以在 Linux、macOS（OSX）和 Windows 上运行。在 Windows 上，新版 Windows Terminal 能够正确显示真彩色与 emoji，而经典终端（legacy terminal）受限于 16 色，展示效果会打折扣。

关于 Python 版本，需要以当前仓库的实际配置为准：项目采用 Poetry 管理，pyproject.toml 中声明python = ">=3.9.0"，同时 classifiers 覆盖 Python 3.9 至 3.14。因此在当前版本（pyproject.toml 中版本号为 15.0.0）下，建议使用 Python 3.9 或更高版本（README.tr.md 中保留的 "3.6.3" 是较早版本的信息，已不再适用于当前代码库）。

此外，Rich 可以直接在 Jupyter notebook）。pyproject.toml还提供了可选的jupyter额外依赖（ipywidgets），用于增强 notebook 中的交互式组件。

安装与快速验证

通过pip或任意 PyPI 包管理器即可安装：

python -m pip install rich

安装完成后，运行下面的命令可以在终端中直接看到 Rich 的自检输出——它会渲染一张包含颜色、样式、Markdown、表格、语法高亮等所有核心特性的演示卡片：

python -m rich

这个命令的入口定义在 rich/main.py，它内部的make_test_card()构建了一张综合展示 Rich 各类功能的表格：4-bit / 8-bit / 真彩色颜色支持、ANSI 样式（bold、dim、italic、underline、strike、reverse、blink）、中/日/韩等亚洲语言文本、bbcode 风格 markup、表格、语法高亮、pretty print 和 Markdown 等。该卡片还会统计渲染耗时（冷缓存与热缓存），帮助你直观感受 Rich 的渲染性能。

Rich Print：一行代码美化输出

最快上手 Rich 的方式是直接覆盖 Python 内置的print函数：

from rich import print print("Merhaba, [bold magenta]Dünya[/bold magenta]!", ":vampire:", locals())

这段代码同时展示了三个特性：

• console markup：[bold magenta]...[/bold magenta]这种 BBCode 风格的标签可以对输出中的指定片段着色、加粗；
• emoji 代码：:vampire:会被自动替换为对应的 emoji 字符；
• 任意对象：locals()这样的字典会被 Rich 以漂亮的语法高亮形式打印出来。

底层实现上，模块级print定义在 rich/init.py，它与内置print拥有完全相同的签名（sep、end、file、flush），内部通过get_console()获取一个全局Console实例再调用其print方法，因此你在替换print后，现有代码几乎无需改动即可获得美化输出。

Rich REPL：让交互式解释器自动美化

在 Python REPL 中安装 Rich 的 pretty 渲染器后，任何数据结构在输出时都会被自动美化并语法高亮：

>>> from rich import pretty >>> pretty.install()

pretty.install()的实现位于 rich/pretty.py，它会替换掉sys.displayhook，从而接管 REPL 中所有表达式的输出。从签名可以看到它还支持overflow、crop、indent_guides、max_length、max_string、max_depth、expand_all等参数，用于控制大对象展示时的截断与缩进引导线。

Console 对象：终端输出的完全控制

当需要对输出进行更精细的控制时，导入并构造一个Console对象：

from rich.console import Console console = Console()

Console类的定义在 rich/console.py，其print方法（rich/console.py）与内置print接口故意保持相似：

console.print("Merhaba", "Dünya!")

这段代码会在终端输出Merhaba Dünya!。与内置print的关键区别是：Rich 会根据终端宽度自动对超长文本进行单词换行（word-wrap），而不会让内容溢出屏幕。

通过 style 参数整体着色

最简单的着色方式是通过style关键字参数为整行输出设置样式：

console.print("Merhaba", "Dünya!", style="bold red")

style接受 Rich 的样式描述字符串，可以组合多种属性，如bold red、dim cyan、underline blue等，具体支持的样式在 rich/style.py 中定义。

BBCode 风格 markup：局部精细化样式

style参数适合整行统一着色；当你需要在一段文本内对不同区域施加不同样式时，应使用 Rich 特有的 markup 语法（语法与 BBCode 相似）：

console.print("[bold red]Mustafa Kemal Atatürk[/bold red] u[/u], [i]Türk asker ve devlet adamıdır[/i]. [bold cyan]Türk Kurtuluş Savaşı'nın başkomutanı ve Türkiye Cumhuriyeti'nin kurucusudur[/bold cyan].")

Markup 的解析实现在 rich/markup.py，它支持颜色名（如red、cyan）、样式名（bold、u下划线、i斜体）、以及#RRGGBB形式的十六进制颜色；[/xxx]关闭对应标签，[/]则关闭最近一个标签。console.print默认启用 markup 与 emoji 解析，但也可以分别用markup=False、emoji=False关闭。

Console 的其他常用能力

除了print，Console还提供了丰富的内置方法（详见 Console API）：

• console.log()：带时间戳与调用位置的日志输出（见下文）；
• console.status()：显示 spinner 动画与消息（见下文）；
• console.input()：带样式的交互式输入提示；
• console.rule()：渲染水平分隔线；
• console.clear()、console.show_cursor()：终端控制；
• 导出能力：配合record=True构造参数，可通过export_text()、export_html()、export_svg()（rich/console.py）把终端内容导出为纯文本、HTML 或 SVG 图片，便于分享到博客或文档。

Rich Inspect：对象的快速体检报告

inspect函数可以对任意 Python 对象（类、实例、内置类型）生成一份可视化的属性报告：

>>> my_list = ["foo", "bar"] >>> from rich import inspect >>> inspect(my_list, methods=True)

inspect定义在 rich/init.py，参数非常丰富，常用于调试：

其底层由 rich/_inspect.py 中的Inspect类实现，inspect(inspect)时还会自动展开所有选项，方便你直接查看函数自身的完整信息。

内置渲染组件（Rich Kütüphaneleri）

Rich 内置了大量可以直接使用的"可渲染对象"（renderables），文档中的这一大节是核心内容。这些组件有一个共同点：全部通过 Console Protocol 实现（rich/protocol.py），这意味着你可以像打印普通文本一样把它们交给console.print()，甚至可以将任意组件嵌入表格单元格或树节点。

Log：带时间戳与调用位置的日志

Console的log()方法（rich/console.py）接口与print()类似，但会在输出左侧额外渲染当前时间以及调用所在文件与行号，并对 Python 数据结构自动做语法高亮与 pretty print：

from rich.console import Console console = Console() test_data = [ {"jsonrpc": "2.0", "method": "sum", "params": [None, 1, 2, 4, False, True], "id": "1",}, {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]}, {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": "2"}, ] def test_log(): enabled = False context = { "foo": "bar", } movies = ["Deadpool", "Rise of the Skywalker"] console.log("Hello from", console, "!") console.log(test_data, log_locals=True) test_log()

log()还接受log_locals=True参数，它会在日志下方输出一个包含调用处局部变量的表格，这对调试极其有用。对于服务器这类长期运行的程序，log()是非常合适的终端日志手段；时间列的渲染逻辑位于 rich/_log_render.py。

Logging Handler：接管 Python 标准 logging

Rich 提供了内置的RichHandler类，可以把 Python 标准库logging模块的输出格式化成彩色、分栏的日志：

import logging from rich.logging import RichHandler logging.basicConfig( level="NOTSET", format="%(message)s", datefmt="[%X]", handlers=[RichHandler(rich_tracebacks=True)], ) log = logging.getLogger("rich") log.info("Merhaba, Dünya!")

RichHandler定义在 rich/logging.py，它将时间、日志级别、消息和文件名分栏显示，级别按颜色区分，消息自动语法高亮，并且通过rich_tracebacks=True可以让异常 traceback 也以 Rich 的富文本形式呈现。

Emoji：直接嵌入表情符号

在字符串中用冒号包裹 emoji 名称即可插入 emoji，用法与 Markdown 的 emoji 语法一致：

>>> console.print(":smiley: :vampire: :pile_of_poo: :thumbs_up: :raccoon:") 😃 🧛 💩 👍 🦝

Emoji 名称到字符的映射表维护在 rich/_emoji_codes.py 和 rich/_emoji_replace.py 中，支持上千个 emoji；当终端不支持 emoji 字体时会自动降级。当然，文档也提醒：请在合适的场景使用这个特性。

Tables：灵活的表格渲染

Rich 的Table类（rich/table.py）提供高度灵活的表格渲染，边框、样式、单元格对齐等都有大量选项。文档给出的经典电影票房示例：

from rich.console import Console from rich.table import Table console = Console() table = Table(show_header=True, header_style="bold magenta") table.add_column("Date", style="dim", width=12) table.add_column("Title") table.add_column("Production Budget", justify="right") table.add_column("Box Office", justify="right") table.add_row( "Dec 20, 2019", "Star Wars: The Rise of Skywalker", "$275,000,000", "$375,126,118" ) table.add_row( "May 25, 2018", "[red]Solo[/red]: A Star Wars Story", "$275,000,000", "$393,151,347", ) table.add_row( "Dec 15, 2017", "Star Wars Ep. VIII: The Last Jedi", "$262,000,000", "[bold]$1,332,539,889[/bold]", ) console.print(table)

值得注意的要点：

• 单元格内的 console markup 与print()/log()中同样生效（如[red]Solo[/red]、[bold]$1,332,539,889[/bold]）；
• 任何 Rich 可渲染对象都可以放进表头或单元格，包括其他表格（表格嵌套）；
• Column数据类（rich/table.py）展示了完整的列配置项：justify（left/center/right/full）、vertical（top/middle/bottom）、width、min_width、max_width、ratio、no_wrap、overflow（默认ellipsis）等；
• Table类会根据终端可用宽度自动调整列宽并换行。把终端窗口缩窄后，同样的表格会自动重新布局（见下图），这一自适应能力在 rich/_ratio.py 的宽度分配算法中实现。

文档中的表格动画示例由 examples/table_movie.py 生成，展示了表格随数据实时更新的效果。

Progress Bars：多任务进度条

Rich 可以渲染多个无闪烁（flicker-free）的进度条来追踪长时间运行的任务。最基础的用法是使用track函数包装任意可迭代对象：

from rich.progress import track for step in track(range(100)): do_step(step)

track定义在 rich/progress.py，它的完整签名支持description（默认"Working..."）、total、transient、refresh_per_second（默认 10）、console等参数。

添加多个进度条也毫不费力。进度条的各列（column）完全可配置——文档明确说明：内置列包括百分比、文件大小、下载速度、剩余时间等。下面的下载示例展示了这些列的组合（源码见 examples/downloader.py，可并发下载多个 URL 并实时显示进度）：

examples/downloader.py中展示了Progress类的进阶用法：通过TextColumn、BarColumn、DownloadColumn、TransferSpeedColumn、TimeRemainingColumn自由组合进度条列，并通过progress.update(task_id, advance=len(data))手动推进进度。Progress类完整的列机制定义在 rich/progress.py 中。

Status：无法计算进度时的 spinner 动画

当任务难以估算进度百分比时，可以用status方法显示 spinner 动画和提示消息，动画不会阻塞你对 console 的常规使用：

from time import sleep from rich.console import Console console = Console() tasks = [f"task {n}" for n in range(1, 11)] with console.status("[bold green]Working on tasks...") as status: while tasks: task = tasks.pop(0) sleep(1) console.log(f"{task} complete")

status方法（rich/console.py）的签名提供了spinner（默认"dots"）、spinner_style、speed、refresh_per_second（默认 12.5）等参数。spinner 动画取自 cli-spinners 项目，动画集合定义在 rich/_spinners.py，通过spinner参数选择不同的动画样式。运行以下命令可以查看所有可用的 spinner：

python -m rich.spinner

Tree：带引导线的树形结构

Rich 可以渲染带辅助引导线（guide lines）的树结构，非常适合展示文件目录或其他层级数据：

python -m rich.tree

Tree类定义在 rich/tree.py，其label可以是普通文本，也可以是任何 Rich 可渲染对象（甚至嵌套表格或面板）。文档还给出了 examples/tree.py 示例：它可以像 Linux 的tree命令一样，把任意目录结构以树形渲染出来。

Columns：等宽或最优宽度的多列排版

Columns可以把内容排成整齐的多列，列宽相等或按内容自动优化：

import os import sys from rich import print from rich.columns import Columns directory = os.listdir(sys.argv[1]) print(Columns(directory))

这段代码实际上就是一个极简的ls克隆。Columns类（rich/columns.py）接受任意 Rich renderable 的列表，并支持width、padding、expand、equal等参数；更完整的 API 数据列表示例见 examples/columns.py。

Markdown：在终端渲染 Markdown

Rich 可以将 Markdown 文档转换为适合终端的排版格式。用法是构造一个Markdown对象并打印：

from rich.console import Console from rich.markdown import Markdown console = Console() with open("README.md") as readme: markdown = Markdown(readme.read()) console.print(markdown)

Markdown类定义在 rich/markdown.py，底层依赖markdown-it-py解析（见 pyproject.toml）。它的构造参数包括code_theme（代码块主题，默认"monokai"）、justify、style、hyperlinks（默认启用）、inline_code_lexer与inline_code_theme（行内代码高亮）等。你可以用这个功能在 CLI 中直接渲染仓库的 README.md，效果如上图。

Syntax Highlighting：源码语法高亮

Rich 使用 Pygments 库实现语法高亮。用法与渲染 Markdown 类似——构造Syntax对象再打印：

from rich.console import Console from rich.syntax import Syntax my_code = ''' def iter_first_last(values: Iterable[T]) -> Iterable[Tuple[bool, bool, T]]: """Iterate and generate a tuple with a flag for first and last value.""" iter_values = iter(values) try: previous_value = next(iter_values) except StopIteration: return first = True for value in iter_values: yield first, False, previous_value first = False previous_value = value yield first, True, previous_value ''' syntax = Syntax(my_code, "python", theme="monokai", line_numbers=True) console = Console() console.print(syntax)

Syntax类定义在 rich/syntax.py，构造参数包括：lexer（Pygments 词法器名，如"python"）、theme（Pygments 配色主题，默认"monokai"）、line_numbers（是否显示行号）、start_line、line_range、highlight_lines、tab_size（默认 4）、word_wrap、indent_guides（缩进引导线）等。结合highlight_lines你可以高亮指定行，这在讲解代码或做代码评审工具时非常实用。

Tracebacks：更易读的异常回溯

Rich 可以渲染比 Python 标准 traceback更易读、包含更多代码上下文的异常回溯：

通过traceback.install()（定义在 rich/traceback.py）可以把 Rich 设为默认的未捕获异常处理器，让所有未捕获异常都以富文本形式呈现。该函数支持width（默认 100）、code_width（默认 88）、extra_lines（上下文代码行数，默认 3）、word_wrap、show_locals（显示异常位置的局部变量）等参数。对应的实现模块是 rich/traceback.py，你也可以通过console.print_exception()在except块中手动渲染当前异常。

扩展自己的渲染组件：Console Protocol

文档明确指出：Rich 的所有可渲染组件都建立在 Console Protocol 之上（定义在 rich/protocol.py）。这意味着你完全可以实现协议，让自定义对象被console.print()直接渲染：

from rich.console import Console, ConsoleOptions, RenderResult from rich.segment import Segment from rich.style import Style class Rainbow: def __rich_console__(self, console: Console, options: ConsoleOptions) -> RenderResult: for color in ("red", "yellow", "green", "cyan", "blue", "magenta"): yield Segment(color, Style(color=color)) console = Console() console.print(Rainbow())

只需实现__rich_console__方法（返回Segment序列），你的对象就成为一等公民，可以嵌套进表格、树、面板等任何容器。仓库中的 examples/rainbow.py 就是一个现成的协议实现示例。

生态延伸：Rich CLI 与 Textual

除了库本身，Rich 生态还有两个方向的延伸（均为独立的兄弟项目，不属于本仓库范围）：

• Rich CLI：一个由 Rich 驱动的命令行应用，可直接在命令提示符中对代码做语法高亮、渲染 Markdown、以表格展示 CSV 文件等；
• Textual：Rich 的姊妹项目，用于在终端中构建完整的用户界面（UI）。

小结

本文完整梳理了 Rich 的核心用法：从rich print的一行接入、REPL 美化、Console对象的精细控制，到 Log、Logging Handler、Emoji、Tables、Progress Bars、Status、Tree、Columns、Markdown、Syntax Highlighting、Tracebacks 十一个内置渲染组件，再到基于 Console Protocol 的自定义扩展。所有组件都在 rich/ 目录下有对应的源码实现，示例代码集中在 examples/，并有 tests/ 下对应的测试覆盖（如 tests/test_console.py、tests/test_table.py、tests/test_progress.py、tests/test_markdown.py、tests/test_syntax.py），你可以随时阅读源码与测试来深入理解每个组件的实现细节，并将其直接用于自己的 CLI 与调试工具中。

【免费下载链接】richRich is a Python library for rich text and beautiful formatting in the terminal.项目地址: https://gitcode.com/gh_mirrors/ri/rich