Python Rich 終端機美化與日誌

在開發命令行介面 (CLI) 工具或後端腳本時，傳統的純文字輸出往往顯得單調且難以閱讀，尤其在面對複雜資料或錯誤日誌時。Rich 是一個強大的 Python 函式庫，它能讓你輕易地在終端機中印出豐富的色彩、漂亮的表格、進度條、甚至是語法高亮，大幅提升工具的專業感與開發體驗。

安裝

pip install rich

核心組件：Console 與 Rich Printing

Console 物件是所有 Rich 功能的核心進入點。

from rich.console import Console

console = Console()

# 1. 直接列印並使用標記語言 (Markup)
# 支援顏色、粗體、斜體等
console.print("Hello [bold magenta]World[/bold magenta]!", ":vampire:")

# 2. 自動處理資料結構
# Rich 會自動幫 dict, list 上色並進行縮排，比 pprint 更好看
user_profile = {
    "id": 1024,
    "name": "Mike Lee",
    "tags": ["Python", "Developer", "Gamer"],
    "active": True
}
console.print(user_profile)

強大的排版工具

1. 表格 (Table)

當你需要呈現結構化資料時，表格是絕對的首選。

from rich.table import Table

table = Table(title="專案部署狀態", show_header=True, header_style="bold magenta")

table.add_column("服務名稱", style="dim", width=12)
table.add_column("版本", justify="center")
table.add_column("狀態", justify="right")

table.add_row("Web Server", "v2.1.0", "[green]Online[/green]")
table.add_row("Database", "v14.5", "[green]Online[/green]")
table.add_row("Cache", "v6.2", "[red]Offline[/red]")

console.print(table)

2. 進度條與狀態指示器 (Progress & Status)

處理由於網路或運算導致的等待時間，進度條能顯著降低使用者的焦慮。

快速進度條：使用 track() 包裝迭代器。
動態狀態：使用 console.status() 顯示旋轉動畫。

import time
from rich.progress import track

# 適用於已知總量的迭代
for n in track(range(10), description="正在下載資源..."):
    time.sleep(0.3)

# 適用於未知時間或啟動過程
with console.status("[bold green]正在檢查伺服器健康狀況...") as status:
    # 模擬耗時任務
    time.sleep(3)
    console.log("檢查完成！")

3. 面板與樹狀結構 (Panel & Tree)

讓輸出的層次感更加分明。

from rich.panel import Panel
from rich.tree import Tree

# 面板包裹
console.print(Panel("這是系統的重要通知內容", title="[bold red]警告", subtitle="2026-01-04"))

# 樹狀目錄
tree = Tree("Root Project")
src = tree.add("src")
src.add("main.py")
src.add("utils.py")
tree.add("tests")
tree.add("README.md")

console.print(tree)

除錯與日誌 (Debug & Logging)

一鍵檢查物件：Inspect

比 dir() 強大百倍。它能顯示物件的型別、值、甚至文件字串。

from rich import inspect

# 檢查 response 物件
inspect(user_profile, methods=True)

整合標準日誌：RichHandler

這是我最推薦的功能之一。你可以將 Python 內建的 logging 輸出替換成 Rich 的彩色版本。

import logging
from rich.logging import RichHandler

FORMAT = "%(message)s"
logging.basicConfig(
    level="INFO",
    format=FORMAT,
    datefmt="[%X]",
    handlers=[RichHandler(rich_tracebacks=True)] # 自動追蹤報錯行數與內容
)

log = logging.getLogger("rich")
log.info("API 服務已啟動")
log.warning("請求速度過快，觸發速率限制")
try:
    1 / 0
except ZeroDivisionError:
    log.exception("捕捉到非預期異常") # Rich 會輸出彩色的 Traceback

在終端機渲染 Markdown (Markdown Rendering)

如果你寫了 README.md 想在 CLI 直接展示：

from rich.markdown import Markdown

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

總結

Rich 能將你的終端機從 1980 年代的單色風格帶入現代。
Console 是核心，Table 是看板，Progress 是體驗。
透過 RichHandler 整合 Logging，能極大加快你開發時的除錯速度。

如果你在開發一個會給他人使用的套件或 CLI 工具，Rich 是那種能讓你的產品瞬間看起來「很貴」的秘密武器。