控制台API¶

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

from rich.console import Console
console = Console()

然后，您可以从项目中的任何位置导入控制台，如下所示：

from my_project.console import console

Console对象处理为颜色和样式生成ANSI转义序列的机制。它将自动检测终端的功能，并在必要时转换颜色。

属性¶

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

size 是端子的当前尺寸(如果调整窗口大小，该尺寸可能会更改)。
encoding 是默认编码(通常为“utf-8”)。
is_terminal 是一个布尔值，它指示控制台实例是否正在写入终端。
color_system 是一个包含控制台颜色系统的字符串(见下文)。

颜色系统¶

有几种向终端写入颜色的“标准”，并不是所有的标准都被普遍支持。Rich将自动检测适当的配色系统，或者您可以通过为 color_system 发送到 Console 构造函数。

您可以设置 color_system 设置为下列值之一：

None 完全禁用颜色。
"auto" 将自动检测颜色系统。
"standard" 可以显示8种颜色，有正常和明亮的变化，总共16种颜色。
"256" 可以显示“标准”中的16种颜色，以及240种颜色的固定调色板。
"truecolor" 可以显示1670万种颜色，这可能是您的显示器可以显示的所有颜色。
"windows" 在传统的Windows终端上可以显示8种颜色。新的Windows终端可以显示“真彩色”。

警告

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

打印¶

要将丰富的内容写入终端，请使用 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() 方法提供与打印相同的功能，但增加了一些对调试正在运行的应用程序有用的功能。日志记录将当前时间写入左侧的列中，并将调用方法的文件和行写入右侧的列。以下是一个示例：

>>> 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"]')

你也可以 log 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 ───────────────────────────────

规则方法还接受 style 参数来设置线条的样式，并使用 align 参数对齐标题(“左”、“中”或“右”)。

状态¶

Rich可以用不会干扰常规控制台输出的“微调”动画显示状态消息。运行以下命令以演示此功能：

python -m rich.status

要显示状态消息，请调用 status() 以及状态消息(其可以是字符串、文本或其他可呈现的)。结果是一个上下文管理器，它启动和停止代码块周围的状态显示。以下是一个示例：

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

可以通过以下方式更改微调控件动画 spinner 参数：：

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

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

python -m rich.spinner

对齐/对齐¶

打印和日志都支持 justify 参数，如果设置该参数，则必须是“Default”、“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)，或者如果面板或表格单元格中的文本空间有限，则可能会发生溢出。

您可以指定Rich应该如何使用 overflow 参数为 print() 它应该是以下字符串之一：“折叠”、“裁剪”、“省略号”或“忽略”。缺省值为“Fold”，它会将任何多余的字符放在下一行上，根据需要创建尽可能多的新行来适应文本。

“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=False 当呼叫时 print() 。

控制台风格¶

该控制台有一个 style 属性，您可以使用该属性将样式应用于打印的所有内容。默认情况下 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 Word通过插入换行符来换行打印的文本。您可以通过设置来禁用此行为 soft_wrap=True 当呼叫时 print() 。使用 soft wrapping 启用了任何不适合的文本都会排到下面一行(S)，就像内置的 print 。

修剪¶

这个 print() 方法具有布尔值 crop 争论。Crop的缺省值为True，这会告诉Rich裁剪任何原本会继续到下一行的内容。您通常不需要考虑裁剪，因为Rich会调整内容大小以适应可用宽度。

备注

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

输入¶

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

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

如果构建了Python readline 模块已预先加载，将提供详细的行编辑和历史记录功能。

正在导出¶

Console类可以将写入它的任何内容导出为文本、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() 要将内容直接写入磁盘，请执行以下操作。

有关富控制台生成的html输出的示例，请参见标准颜色。

导出SVG¶

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

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

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

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

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代码字体。如果在页面中嵌入Rich SVG，则可能还需要添加指向 Fira Code CSS

错误控制台¶

控制台对象将写入 sys.stdout 默认情况下(这样您就可以在终端中看到输出)。如果您使用以下工具构建控制台 stderr=True 里奇会写信给 sys.stderr 。您可能希望使用它来创建一个 error console 因此，您可以从常规输出中拆分错误消息。以下是一个示例：

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 从控制台输出，而不是直接将其写入终端。您可以使用 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 来展示它。寻呼机通常是操作系统上的一个应用程序，它至少支持按下一个键来滚动，但通常会支持上下滚动文本和其他功能。

可以通过调用以下方法从控制台对输出进行分页 pager() 它返回一个上下文管理器。当寻呼机退出时，打印的所有内容都将发送到寻呼机。以下是一个示例：

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

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

由于大多数平台上的默认寻呼机不支持颜色，Rich将从输出中剥离颜色。如果您知道您的寻呼机支持颜色，则可以设置 styles=True 在调用 pager() 方法。

备注

里奇会看着 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以禁用动画。

备注

某些配置项系统支持ANSI颜色和样式，但不支持移动光标或选择性刷新终端部分的任何内容。对于这些，您可能需要设置 force_terminal 至 True 和 force_interactive 至 False 。

环境变量¶

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

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

如果环境变量 FORCE_COLOR ，则将启用颜色/样式 TERM 。这在CI系统上很有用，CI系统不是终端，但仍然可以显示ANSI转义序列。

如果环境变量 NO_COLOR 设置后，Rich将禁用输出中的所有颜色。这一点优先于 FORCE_COLOR 。看见 no_color 了解更多细节。

备注

这个 NO_COLOR 环境变量删除 color 只有这样。保留模糊、粗体、斜体、下划线等样式。

如果 width / height arguments are not explicitly provided as arguments to Console then the environment variables COLUMNS/LINES 可用于设置控制台的宽度/高度。 JUPYTER_COLUMNS/JUPYTER_LINES 行为相似，在木星中也用到。