控制台 API¶

为了完全控制终端格式，Rich 提供了一个 Console 类。大多数应用程序只需要一个 Console 实例，因此您可能希望在模块级别或作为顶级对象的属性创建一个。例如，您可以在项目中添加一个名为“console.py”的文件

from rich.console import Console
console = Console()

然后，您可以像这样从项目中的任何地方导入控制台

from my_project.console import console

控制台对象负责生成 ANSI 转义序列以进行颜色和样式处理。它会自动检测终端的功能，并在必要时转换颜色。

属性¶

控制台会自动检测渲染时所需的许多属性。

size 是终端的当前尺寸（如果调整窗口大小，可能会发生变化）。
encoding 是默认编码（通常为“utf-8”）。
is_terminal 是一个布尔值，指示 Console 实例是否正在写入终端。
color_system 是一个包含 Console 颜色系统的字符串（见下文）。

颜色系统¶

有多种向终端写入颜色的“标准”，并非所有标准都得到普遍支持。Rich 会自动检测适当的颜色系统，或者您也可以通过为 color_system 提供一个值到 Console 构造函数中手动设置它。

您可以将 color_system 设置为以下值之一

None 完全禁用颜色。
"auto" 将自动检测颜色系统。
"standard" 可以显示 8 种颜色，包括普通和亮度变化，总共 16 种颜色。
"256" 可以显示“standard”中的 16 种颜色以及固定调色板中的 240 种颜色。
"truecolor" 可以显示 1670 万种颜色，这很可能是您的显示器可以显示的所有颜色。
"windows" 可以显示旧版 Windows 终端中的 8 种颜色。新的 Windows 终端可以显示“truecolor”。

警告

设置颜色系统时要小心，如果设置的颜色系统高于终端支持的颜色系统，您的文本可能无法读取。

打印¶

要将富内容写入终端，请使用 print() 方法。Rich 会通过对象的 (__str__) 方法将任何对象转换为字符串，并执行一些简单的语法高亮显示。它还会对任何容器（如字典和列表）进行美观打印。如果打印字符串，它将呈现控制台标记。以下是一些示例

console.print([1, 2, 3])
console.print("[blue underline]Looks like a link")
console.print(locals())
console.print("FOO", style="white on blue")

您还可以使用 print() 渲染支持控制台协议的对象，其中包括 Rich 的内置对象，如 Text、Table 和 Syntax — 或者其他自定义对象。

日志记录¶

log() 方法提供了与 print 相同的功能，但添加了一些对调试运行中的应用程序有用的功能。日志记录在左侧的列中写入当前时间，在右侧的列中写入调用该方法的文件和行号。以下是一个示例

>>> console.log("Hello, World!")

[16:32:08] Hello, World!                                         <stdin>:1

为了帮助调试，log() 方法有一个 log_locals 参数。如果您将其设置为 True，Rich 将显示调用该方法时局部变量的表格。

打印 JSON¶

print_json() 方法会美观打印（格式化和设置样式）包含 JSON 的字符串。以下是一个简短的示例

console.print_json('[false, true, null, "foo"]')

您还可以通过记录一个 JSON 对象来记录 json

from rich.json import JSON
console.log(JSON('["foo", "bar"]'))

由于打印 JSON 是一种常见的要求，您可以从主命名空间导入 print_json

from rich import print_json

您还可以通过以下命令行美观打印 JSON

python -m rich.json cats.json

低级输出¶

除了 print() 和 log() 之外，Rich 还具有一个 out() 方法，该方法提供了一种更低级的写入终端的方式。out() 方法将所有位置参数转换为字符串，并且不会美观打印、换行或对输出应用标记，但可以应用基本样式，并且可以选择性地进行高亮显示。

以下是一个示例

>>> console.out("Locals", locals())

规则¶

rule() 方法会绘制一条水平线，并带有可选标题，这是将终端输出分成多个部分的好方法。

>>> console.rule("[bold red]Chapter 2")

─────────────────────────────── Chapter 2 ───────────────────────────────

rule 方法还接受 style 参数来设置线的样式，以及 align 参数来对齐标题（“left”、“center”或“right”）。

状态¶

Rich 可以使用“旋转器”动画显示状态消息，这不会干扰常规控制台输出。运行以下命令以演示此功能

python -m rich.status

要显示状态消息，请使用状态消息调用 status()（可以是字符串、Text 或其他可渲染对象）。结果是一个上下文管理器，它在代码块周围启动和停止状态显示。以下是一个示例

with console.status("Working..."):
    do_work()

您可以通过 spinner 参数更改旋转器动画

with console.status("Monkeying around...", spinner="monkey"):
    do_work()

运行以下命令以查看 spinner 的可用选项

python -m rich.spinner

对齐方式¶

print 和 log 都支持一个 justify 参数，如果设置，它必须是“default”、“left”、“right”、“center”或“full”之一。如果为“left”，则打印（或记录）的任何文本都将左对齐，如果为“right”，则文本将右对齐到终端，如果为“center”，则文本将居中对齐，如果为“full”，则文本将与终端的左右边缘对齐（就像书中的印刷文本一样）。

justify 的默认值为 "default"，它通常看起来与 "left" 相同，但有一个细微的差别。左对齐将在文本的右侧用空格填充，而默认对齐则不会。只有当您使用 style 参数设置背景颜色时，您才会注意到这种区别。以下示例演示了这种区别

from rich.console import Console

console = Console(width=20)

style = "bold white on blue"
console.print("Rich", style=style)
console.print("Rich", style=style, justify="left")
console.print("Rich", style=style, justify="center")
console.print("Rich", style=style, justify="right")

这将生成以下输出

Rich
Rich                
        Rich        
                Rich

溢出¶

溢出是指打印的文本大于可用空间时发生的情况。如果打印的“单词”很长（例如 URL），或者如果面板或表格单元格中的文本空间有限，则可能会发生溢出。

您可以使用 overflow 参数在 print() 中指定 Rich 如何处理溢出，该参数应为以下字符串之一：“fold”、“crop”、“ellipsis”或“ignore”。默认值为“fold”，它将把任何多余的字符放在下一行，并根据需要创建新行以容纳文本。

“crop”方法将在行尾截断文本，丢弃任何会溢出的字符。

“ellipsis”方法类似于“crop”，但会在任何被截断的文本末尾插入省略号字符（“...”）。

以下代码演示了基本的溢出方法

from typing import List
from rich.console import Console, OverflowMethod

console = Console(width=14)
supercali = "supercalifragilisticexpialidocious"

overflow_methods: List[OverflowMethod] = ["fold", "crop", "ellipsis"]
for overflow in overflow_methods:
    console.rule(overflow)
    console.print(supercali, overflow=overflow, style="bold blue")
    console.print()

这将生成以下输出

──── fold ────
supercalifragi
listicexpialid
ocious

──── crop ────
supercalifragi

── ellipsis ──
supercalifrag…

您也可以将 overflow 设置为 “ignore”，这允许文本继续到下一行。在实践中，这看起来与 “crop” 相同，除非您还在调用 print() 时设置 crop=False。

控制台样式¶

控制台有一个 style 属性，您可以使用它将样式应用于您打印的所有内容。默认情况下 style 为 None，这意味着没有应用额外的样式，但您可以将其设置为任何有效的样式。以下是一个设置了 style 属性的控制台示例

from rich.console import Console
blue_console = Console(style="white on blue")
blue_console.print("I'm blue. Da ba dee da ba di.")

软换行¶

Rich 通过插入换行符来对您打印的文本进行换行。您可以通过在调用 print() 时设置 soft_wrap=True 来禁用此行为。启用 *软换行* 后，任何不适合的文本都会像内置的 print 一样继续到下一行。

裁剪¶

print() 方法有一个布尔值 crop 参数。crop 的默认值为 True，它告诉 Rich 裁剪任何本来会继续到下一行的内容。您通常不需要考虑裁剪，因为 Rich 会调整内容大小以适合可用宽度。

注意

如果您使用 soft_wrap=True 打印，则裁剪会自动禁用。

输入¶

控制台类有一个 input() 方法，其工作方式与 Python 的内置 input() 函数相同，但可以使用 Rich 可以打印的任何内容作为提示。例如，这是一个带有表情符号的彩色提示

from rich.console import Console
console = Console()
console.input("What is [i]your[/i] [bold red]name[/]? :smiley: ")

如果 Python 的内置 readline 模块已加载，将可以使用复杂的行编辑和历史记录功能。

导出¶

控制台类可以将写入它的任何内容导出为文本、svg 或 html。要启用导出，首先在构造函数上设置 record=True。这告诉 Rich 保存您 print() 或 log() 的任何数据的副本。以下是一个示例

from rich.console import Console
console = Console(record=True)

在写入内容后，您可以调用 export_text()、export_svg() 或 export_html() 以获取控制台输出作为字符串。您也可以调用 save_text()、save_svg() 或 save_html() 以将内容直接写入磁盘。

有关 Rich Console 生成的 html 输出的示例，请参阅标准颜色。

导出 SVG¶

使用 export_svg() 或 save_svg() 时，SVG 的宽度将与您的终端窗口宽度（以字符为单位）匹配，而高度将自动缩放以适应控制台输出。

您可以在 Web 浏览器中打开 SVG。您也可以使用 <img> 标签将其插入网页，或将标记复制到您的 HTML 中。

下图显示了 Rich 导出的 SVG 示例。

您可以通过从 rich.terminal_theme 模块导入所需主题并将其通过 theme 参数传递给 export_svg() 或 save_svg() 来自定义 SVG 导出期间使用的主题

from rich.console import Console
from rich.terminal_theme import MONOKAI

console = Console(record=True)
console.save_svg("example.svg", theme=MONOKAI)

或者，您可以通过自己构造一个 rich.terminal_theme.TerminalTheme 实例并将其传递进来，来创建自己的主题。

注意

SVG 引用 Fira Code 字体。如果您在页面中嵌入 Rich SVG，您可能还希望添加指向 Fira Code CSS 的链接

错误控制台¶

控制台对象默认情况下会写入 sys.stdout（这样您就可以在终端中看到输出）。如果您使用 stderr=True 构造控制台，Rich 会写入 sys.stderr。您可能希望使用它来创建一个 *错误控制台*，以便您可以将错误消息与常规输出分开。以下是一个示例

from rich.console import Console
error_console = Console(stderr=True)

您可能还想在控制台上设置 style 参数，以使错误消息在视觉上更具区分性。以下是如何做到这一点

error_console = Console(stderr=True, style="bold red")

文件输出¶

您可以通过在构造函数上设置 file 参数来告诉控制台对象写入文件，该参数应该是一个以写入文本方式打开的文件类对象。您可以使用它将内容写入文件，而不会在终端上显示输出。以下是一个示例

import sys
from rich.console import Console
from datetime import datetime

with open("report.txt", "wt") as report_file:
    console = Console(file=report_file)
    console.rule(f"Report Generated {datetime.now().ctime()}")

请注意，当写入文件时，如果您不希望将输出换行到当前控制台宽度，您可能需要显式设置 width 参数。

捕获输出¶

在某些情况下，您可能希望 *捕获* 来自控制台的输出，而不是将其直接写入终端。您可以使用 capture() 方法来完成此操作，该方法返回一个上下文管理器。退出此上下文管理器后，调用 get() 以返回将写入终端的字符串。以下是一个示例

from rich.console import Console
console = Console()
with console.capture() as capture:
    console.print("[bold red]Hello[/] World")
str_output = capture.get()

捕获输出的另一种方法是将控制台文件设置为 io.StringIO。如果您在单元测试中测试控制台输出，建议使用此方法。以下是一个示例

from io import StringIO
from rich.console import Console
console = Console(file=StringIO())
console.print("[bold red]Hello[/] World")
str_output = console.file.getvalue()

分页¶

如果您有一些要呈现给用户的长输出，您可以使用 *分页器* 来显示它。分页器通常是您操作系统上的一个应用程序，它至少支持按一个键滚动，但通常支持在文本中向上和向下滚动以及其他功能。

您可以通过调用 pager() 来分页来自控制台的输出，该方法返回一个上下文管理器。当分页器退出时，打印的任何内容都将被发送到分页器。以下是一个示例

from rich.__main__ import make_test_card
from rich.console import Console

console = Console()
with console.pager():
    console.print(make_test_card())

由于大多数平台上的默认分页器不支持颜色，Rich 会从输出中删除颜色。如果您知道您的分页器支持颜色，您可以在调用 pager() 方法时设置 styles=True。

注意

Rich 会查看 MANPAGER 然后查看 PAGER 环境变量（MANPAGER 优先级更高）以获取分页器命令。在 Linux 和 macOS 上，您可以将其中一个设置为 less -r 以启用带有 ANSI 样式的分页。

备用屏幕¶

警告

此功能目前处于实验阶段。您可能希望在生产环境中使用它之前等待。

终端支持一个“备用屏幕”模式，该模式与常规终端分开，并允许全屏应用程序，这些应用程序会保留您的输入流和命令。Rich 通过 set_alt_screen() 方法支持此模式，尽管建议您使用 screen()，它返回一个上下文管理器，在退出时禁用备用模式。

以下是一个备用屏幕的示例

from time import sleep
from rich.console import Console

console = Console()
with console.screen():
    console.print(locals())
    sleep(5)

上面的代码将在备用屏幕上显示一个漂亮的打印字典，然后在 5 秒后返回命令提示符。

您也可以向 screen() 提供一个可渲染对象，当您调用 update() 时，该对象将在备用屏幕上显示。

以下是一个示例

from time import sleep

from rich.console import Console
from rich.align import Align
from rich.text import Text
from rich.panel import Panel

console = Console()

with console.screen(style="bold white on red") as screen:
    for count in range(5, 0, -1):
        text = Align.center(
            Text.from_markup(f"[blink]Don't Panic![/blink]\n{count}", justify="center"),
            vertical="middle",
        )
        screen.update(Panel(text))
        sleep(1)

使用可渲染对象更新屏幕可以让 Rich 裁剪内容以适合屏幕，而无需滚动。

要使用 Rich 构建更强大的全屏界面，请参阅实时显示。

注意

如果您在退出 Python 代码后发现自己处于备用模式，请在终端中输入 reset

终端检测¶

如果 Rich 检测到它没有写入终端，它将从输出中剥离控制代码。如果您想将控制代码写入普通文件，请在构造函数中设置 force_terminal=True。

让 Rich 自动检测终端很有用，因为它在您将输出管道到文件或其他应用程序时将写入纯文本。

交互模式¶

Rich 不会在不写入终端时删除动画（例如进度条和状态指示器），因为您可能不想将它们写入文本文件。您可以通过在构造函数中设置 force_interactive 参数来覆盖此行为。将其设置为 True 以启用动画，或将其设置为 False 以禁用动画。

注意

一些 CI 系统支持 ANSI 颜色和样式，但不支持移动光标或选择性刷新终端部分的任何操作。对于这些系统，您可能需要将 force_terminal 设置为 True，并将 force_interactive 设置为 False。

环境变量¶

Rich 尊重一些标准环境变量。

将环境变量 TERM 设置为 "dumb" 或 "unknown" 将禁用颜色/样式以及一些需要移动光标的功能，例如进度条。

如果设置了环境变量 FORCE_COLOR，则无论 TERM 的值如何，都会启用颜色/样式。这在 CI 系统中很有用，这些系统不是终端，但仍然可以显示 ANSI 转义序列。

如果设置了环境变量 NO_COLOR，Rich 将禁用输出中的所有颜色。这优先于 FORCE_COLOR。有关详细信息，请参阅 no_color。

注意

环境变量 NO_COLOR 仅删除颜色。样式（如淡色、粗体、斜体、下划线等）将保留。

如果未明确将 width / height 参数作为参数提供给 Console，则环境变量 COLUMNS/LINES 可用于设置控制台宽度/高度。 JUPYTER_COLUMNS/JUPYTER_LINES 的行为类似，并在 Jupyter 中使用。