rich

英文自述文件• 簡體中文自述文件• 正體中文自述文件• Lengua española 自述文件• 德語自述文件• Läs på svenska 自述文件• 日本文自述文件• 한국어自述文件• 法文自述文件• Schwizerdizer 自述文件• Schwizer•.巴西葡萄牙語自述文件• 義大利文自述文件• Рус ский 自述文件• 印尼語自述文件• فרག 自述文件 • Türkçe 自述文件 • Polskie 自述文件

Rich 是一個 Python 函式庫，用於在終端機中提供富文本和漂亮的格式設定。

豐富的 API 可以輕鬆地為終端輸出添加顏色和樣式。 Rich 還可以呈現漂亮的表格、進度條、markdown、語法反白的原始碼、回溯等，開箱即用。

有關 Rich 的影片介紹，請參閱 @fishnets88 提供的 calamcode.io。

看看人們對 Rich 的評價。

相容性

Rich 適用於 Linux、macOS 和 Windows。真彩色/表情符號適用於新的 Windows 終端，經典終端僅限於 16 種顏色。 Rich 需要 Python 3.8 或更高版本。

Rich 可與 Jupyter 筆記本搭配使用，無需額外配置。

安裝中

使用pip或您最喜歡的 PyPI 套件管理器安裝。

python -m pip install rich

執行以下命令在終端機上測試豐富的輸出：

python -m rich

豐富的印刷

要輕鬆地在應用程式中添加豐富的輸出，您可以匯入豐富的列印方法，該方法與內建的 Python 函數具有相同的簽名。試試這個：

 from rich import print

print ( "Hello, [bold magenta]World[/bold magenta]!" , ":vampire:" , locals ())

豐富的REPL

Rich 可以安裝在 Python REPL 中，這樣任何資料結構都會被漂亮地列印和突出顯示。

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

使用控制台

為了更好地控制豐富的終端內容，請匯入並建構一個 Console 物件。

 from rich . console import Console

console = Console ()

Console 物件有一個print方法，該方法具有與內建print函數類似的介面。這是一個使用範例：

 console . print ( "Hello" , "World!" )

正如您所期望的，這將列印"Hello World!"到航站樓。請注意，與內建print功能不同，Rich 會對文字進行自動換行以適合終端寬度。

有幾種方法可以為輸出添加顏色和樣式。您可以透過新增style關鍵字參數來設定整個輸出的樣式。這是一個例子：

 console . print ( "Hello" , "World!" , style = "bold red" )

輸出將類似以下內容：

這對於一次設定一行文字的樣式來說很好。為了獲得更細粒度的樣式，Rich 呈現了一個特殊的標記，其語法與 bbcode 相似。這是一個例子：

 console . print ( "Where there is a [bold cyan]Will[/bold cyan] there [u]is[/u] a [i]way[/i]." )

您可以使用 Console 物件以最少的努力產生複雜的輸出。有關詳細信息，請參閱控制台 API 文件。

豐富的檢查

Rich 有一個檢查函數，可以產生任何 Python 物件（例如類別、實例或內建物件）的報告。

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

有關詳細信息，請參閱檢查文件。

豐富的圖書館

Rich 包含許多內建可渲染對象，您可以使用它們在 CLI 中創建優雅的輸出並幫助您偵錯程式碼。

按一下以下標題以了解詳細資訊：

紀錄

Console 物件有一個log()方法，該方法具有與print()類似的接口，但也呈現當前時間以及進行呼叫的檔案和行的列。預設情況下，Rich 將為 Python 結構和 repr 字串進行語法突出顯示。如果您記錄一個集合（即字典或列表），Rich 會漂亮地列印它，以便它適合可用空間。下面是其中一些功能的範例。

 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_locals參數，它輸出一個包含呼叫 log 方法的局部變數的表。

log 方法可用於記錄到長時間運行的應用程式（例如伺服器）的終端，而且也是一個非常好的偵錯輔助工具。

日誌處理程序

您也可以使用內建的 Handler 類別對 Python 日誌記錄模組的輸出進行格式化和著色。下面是輸出的範例：

表情符號

若要將表情符號插入控制台輸出，請將名稱放在兩個冒號之間。這是一個例子：

 >> > console . print ( ":smiley: :vampire: :pile_of_poo: :thumbs_up: :raccoon:" )
? ? ? ? ?

請明智地使用此功能。

表格

Rich 可以使用 unicode 框字元呈現靈活的表格。邊框、樣式、儲存格對齊等有多種格式選項。

上面的動畫是使用範例目錄中的 table_movie.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 )

這會產生以下輸出：

請注意，控制台標記的呈現方式與print()和log()相同。事實上，Rich 可呈現的任何內容都可以包含在標題/行（甚至其他表格）中。

Table類別足夠智能，可以調整列的大小以適應終端的可用寬度，並根據需要換行文字。這是相同的範例，但終端比上表小：

進度條

Rich 可以渲染多個無閃爍進度條來追蹤長時間運行的任務。

對於基本用法，將任何序列包裝在track函數中並迭代結果。這是一個例子：

 from rich . progress import track

for step in track ( range ( 100 )):
    do_step ( step )

新增多個進度條並不困難。這是來自文件的範例：

這些列可以配置為顯示您想要的任何詳細資訊。內建列包括完成百分比、檔案大小、檔案速度和剩餘時間。這是顯示正在進行下載的另一個範例：

要親自嘗試一下，請參閱 Examples/downloader.py，它可以在顯示進度的同時同時下載多個 URL。

地位

對於難以計算進度的情況，您可以使用 status 方法，該方法將顯示「旋轉」動畫和訊息。動畫不會阻止您正常使用控制台。這是一個例子：

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

這會在終端機中產生以下輸出。

旋轉器動畫是從 cli-spinners 借來的。您可以透過指定spinner參數來選擇微調器。執行以下命令查看可用值：

 python -m rich.spinner

上述命令在終端機中產生以下輸出：

樹

Rich 可以用引導線渲染樹。樹非常適合顯示文件結構或任何其他分層資料。

樹的標籤可以是簡單的文本，也可以是 Rich 可以呈現的任何其他內容。執行以下命令進行演示：

 python -m rich.tree

這會產生以下輸出：

請參閱 tree.py 範例，以了解顯示任何目錄的樹狀視圖的腳本，類似 linux tree指令。

專欄

Rich 可以在具有相等或最佳寬度的整齊列中呈現內容。這是 (MacOS / Linux) ls命令的一個非常基本的克隆，它以列顯示目錄列表：

 import os
import sys

from rich import print
from rich . columns import Columns

directory = os . listdir ( sys . argv [ 1 ])
print ( Columns ( directory ))

以下螢幕截圖是列範例的輸出，該範例顯示從列中的 API 提取的資料：

降價

Rich 可以渲染 Markdown 並合理地將格式轉換到終端。

要渲染 Markdown，請匯入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 )

這將產生如下輸出：

語法高亮

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 )

這將產生以下輸出：

回溯

Rich 可以呈現漂亮的回溯，這些回溯比標準 Python 回溯更易於閱讀並顯示更多程式碼。您可以將 Rich 設定為預設的回溯處理程序，以便 Rich 呈現所有未捕獲的異常。

這是 OSX 上的樣子（Linux 上類似）：

所有豐富的可渲染物件都使用控制台協議，您也可以使用它來實現您自己的豐富內容。

豐富的CLI

另請參閱 Rich CLI 以了解由 Rich 支援的命令列應用程式。直接從命令提示字元語法反白顯示程式碼、呈現 markdown、在表格中顯示 CSV 等。

文字

另請參閱 Rich 的姊妹專案 Textual，您可以使用它在終端中建立複雜的使用者介面。