اگر ابزار خط فرمان پایتونی شما فقط چند print ساده دارد، کاربر خیلی زود در خروجی‌های طولانی گم می‌شود. کتابخانه Rich راهی سریع و خوانا برای ساخت رابط متنی حرفه‌ای است: می‌توانید متن رنگی، جدول، پنل، خطای خوانا، نوار پیشرفت و حتی نمایش درختی بسازید؛ بدون اینکه سراغ رابط گرافیکی بروید. در این آموزش، یک ابزار کوچک گزارش‌گیری می‌سازیم و قدم‌به‌قدم یاد می‌گیریم چگونه خروجی ترمینال را زیباتر و کاربردی‌تر کنیم.

Rich چیست و چرا برای ابزارهای خط فرمان پایتون مناسب است؟

Rich یک کتابخانه متن‌باز پایتون برای نمایش محتوای قالب‌بندی‌شده در ترمینال است. این کتابخانه روی محیط‌های رایج لینوکس، macOS و ویندوز کار می‌کند و بیشتر امکاناتش با یک API ساده در دسترس است. برخلاف رنگ‌آمیزی دستی با کدهای ANSI، Rich جزئیات سازگاری با ترمینال را مدیریت می‌کند و اجازه می‌دهد داده‌های واقعی برنامه را با ساختاری منظم به کاربر نشان دهید.

برای نصب، در محیط مجازی پروژه این دستور را اجرا کنید:

python -m pip install rich

اگر ابزار شما چند فرمان و گزینه دارد، می‌توانید آن را کنار Typer یا argparse قرار دهید. Typer مسئول دریافت ورودی است و Rich مسئول ارائه خروجی؛ همین جداسازی باعث می‌شود کد تمیزتر بماند. برای آشنایی با ساخت ابزارهای خط فرمان، آموزش ساخت داشبورد خط فرمان تعاملی با Textual هم مثال‌های مفیدی دارد.

راه‌اندازی Console و چاپ متن رنگی

مرکز اصلی Rich کلاس Console است. یک نمونه بسازید و از متد print آن استفاده کنید:

from rich.console import Console

console = Console()
console.print("اتصال با موفقیت برقرار شد", style="bold green")
console.print("هشدار: فایل پیکربندی پیدا نشد", style="yellow")
console.print("خطای دسترسی", style="bold white on red")

استایل‌ها می‌توانند رنگ، ضخامت، زیرخط و رنگ پس‌زمینه داشته باشند. اگر بخشی از جمله باید ظاهر متفاوتی داشته باشد، از نشانه‌گذاری Rich استفاده کنید:

console.print("نسخه [bold cyan]1.4.0[/bold cyan] آماده است")

برای متن‌های چندخطی یا متنی که از کاربر می‌گیرید، بهتر است قالب‌بندی را با احتیاط انجام دهید. گزینه markup=False مانع می‌شود براکت‌های موجود در داده خام به‌عنوان تگ تفسیر شوند.

ساخت جدول خوانا برای گزارش برنامه

جدول یکی از ارزشمندترین قابلیت‌های Rich است؛ چون داده‌های ستونی را بدون محاسبه دستی فاصله‌ها نمایش می‌دهد. فرض کنید ابزار ما وضعیت چند سرویس را گزارش می‌کند:

from rich.table import Table

table = Table(title="وضعیت سرویس‌ها")
table.add_column("سرویس", style="cyan", no_wrap=True)
table.add_column("وضعیت", justify="center")
table.add_column("زمان پاسخ", justify="right")

table.add_row("درگاه پرداخت", "[green]فعال[/green]", "182 ms")
table.add_row("ذخیره‌سازی", "[green]فعال[/green]", "74 ms")
table.add_row("گزارش‌گیری", "[red]قطع[/red]", "--")

console.print(table)

پارامترهایی مانند justify، width و expand ظاهر جدول را کنترل می‌کنند. برای خروجی فارسی، متن را کوتاه نگه دارید و ستون‌های عددی را راست‌چین کنید. در داده‌های بزرگ، همه رکوردها را یکجا چاپ نکنید؛ صفحه‌بندی یا فیلتر اختیاری تجربه بهتری می‌سازد.

نمایش داده‌های دیکشنری در جدول

در برنامه واقعی معمولاً داده از API یا فایل JSON می‌آید. بهتر است ابتدا کلیدها را به ستون‌های ثابت نگاشت کنید تا نبودن یک فیلد باعث خطا نشود:

services = [
    {"name": "درگاه پرداخت", "ok": True, "latency": 182},
    {"name": "ذخیره‌سازی", "ok": True, "latency": 74},
]

for service in services:
    status = "[green]فعال[/green]" if service.get("ok") else "[red]قطع[/red]"
    table.add_row(service.get("name", "نامشخص"), status,
                  f"{service.get('latency', 0)} ms")

این الگو از نمایش عبارت‌های خالی یا توقف برنامه هنگام ناقص بودن پاسخ جلوگیری می‌کند.

استفاده از Panel و Markdown برای خروجی‌های مهم

وقتی یک پیام باید به‌صورت یک واحد دیده شود، Panel آن را در کادر قرار می‌دهد. این کار برای خلاصه گزارش، نتیجه نصب یا دستور بعدی مناسب است:

from rich.panel import Panel

summary = """[bold]گزارش آماده شد[/bold]

فایل‌های بررسی‌شده: ۱۲
هشدارها: ۲
زمان اجرا: ۳.۸ ثانیه"""
console.print(Panel(summary, title="نتیجه", border_style="blue"))

برای مستندات یا متن‌هایی که از Markdown می‌آیند، از Markdown استفاده کنید:

from rich.markdown import Markdown

console.print(Markdown("## راهنمای سریع\n- گزینه `--check` را اجرا کنید\n- سپس گزارش را بخوانید"))

اگر محتوای Markdown از کاربر یا منبع ناشناس می‌آید، آن را قبل از نمایش اعتبارسنجی کنید و اطلاعات محرمانه را در گزارش چاپ نکنید. خروجی زیبا نباید به قیمت افشای توکن، مسیر خصوصی یا داده مشتری تمام شود.

اضافه کردن نوار پیشرفت به کارهای زمان‌بر

دانلود فایل، پردازش پوشه یا ارسال چند درخواست ممکن است چند ثانیه طول بکشد. سکوت ترمینال در این فاصله شبیه هنگ کردن برنامه است. Rich با track یک نوار پیشرفت ساده می‌سازد:

from time import sleep
from rich.progress import track

for filename in track(files, description="در حال بررسی فایل‌ها..."):
    check_file(filename)
    sleep(0.1)

برای چند مرحله هم از Progress استفاده کنید. در این حالت تعداد کل، مقدار فعلی و زمان باقی‌مانده را کنترل می‌کنید:

from rich.progress import Progress

with Progress() as progress:
    task = progress.add_task("پردازش", total=len(files))
    for filename in files:
        check_file(filename)
        progress.advance(task)

در آزمایش‌ها و CI بهتر است امکان خاموش کردن انیمیشن را فراهم کنید؛ خروجی متحرک در لاگ‌های غیرتعاملی خوانایی ندارد. می‌توانید یک گزینه مثل --plain داشته باشید و در آن حالت فقط پیام‌های ساده چاپ کنید.

مدیریت خطا با Traceback خوانا

Traceback معمولی برای توسعه‌دهنده مفید است، اما در ابزار نهایی اغلب طولانی و گیج‌کننده می‌شود. Rich می‌تواند خطا را با زمینه بیشتری نمایش دهد:

from rich.traceback import install

install(show_locals=False)

def load_config(path):
    with open(path, encoding="utf-8") as file:
        return file.read()

نمایش متغیرهای محلی را فقط در محیط توسعه فعال کنید؛ ممکن است مقدار رمز عبور یا داده حساس در آن‌ها باشد. در محیط تولید، خطا را ثبت کنید و به کاربر پیام قابل‌فهم بدهید:

try:
    config = load_config("settings.toml")
except FileNotFoundError:
    console.print("فایل settings.toml پیدا نشد؛ با --init آن را بسازید.",
                  style="bold red")

طراحی یک CLI قابل نگهداری با Rich

خروجی حرفه‌ای فقط رنگ و کادر نیست؛ باید قابل تست، قابل خواندن و قابل استفاده در محیط‌های مختلف باشد. منطق برنامه را از لایه نمایش جدا کنید. تابع بررسی سرویس‌ها باید داده برگرداند و تابع دیگری جدول را بسازد. به این ترتیب می‌توانید منطق را بدون وابستگی به ترمینال تست کنید.

پیشنهاد ساختار فایل‌ها

project/
├── app.py
├── services.py
├── output.py
└── tests/
    └── test_services.py

در services.py درخواست و پردازش داده قرار می‌گیرد، در output.py جدول و پنل ساخته می‌شود و app.py ورودی فرمان را هماهنگ می‌کند. نام‌گذاری روشن از پیچیده شدن یک فایل بزرگ جلوگیری می‌کند.

مقایسه خروجی ساده و Rich

نیاز	print معمولی	Rich
رنگ و تاکید	نیازمند کد ANSI یا متن اضافی	استایل نام‌گذاری‌شده
جدول	محاسبه دستی فاصله ستون‌ها	ستون‌بندی خودکار
کار زمان‌بر	پیام‌های پراکنده	نوار پیشرفت
خطای توسعه	Traceback خام	نمایش زمینه‌دار و خوانا

اگر ابزار شما خروجی را برای پردازش ماشین تولید می‌کند، Rich را فقط برای حالت تعاملی فعال کنید و در حالت JSON خروجی استاندارد و بدون رنگ بدهید. این تفکیک باعث می‌شود اسکریپت‌های دیگر به ابزار شما اعتماد کنند.

چک‌لیست نهایی برای انتشار ابزار خط فرمان

وابستگی‌ها را در requirements.txt یا pyproject.toml ثبت کنید.
برای ترمینال‌های کوچک، جدول را آزمایش کنید.
گزینه خروجی ساده یا JSON را برای CI و اسکریپت‌ها در نظر بگیرید.
هیچ توکن و اطلاعات خصوصی را در پنل، traceback یا لاگ چاپ نکنید.
برای مسیر فایل و ورودی کاربر پیام خطای مشخص بنویسید.
کد منطق را جدا از نمایش تست کنید.

اگر پروژه شما قرار است چند دستور داشته باشد، می‌توانید همین لایه نمایش را کنار FastAPI برای ابزارهای مدیریتی یا اسکریپت‌های عملیاتی نگه دارید؛ آموزش ساخت API حرفه‌ای با FastAPI برای بخش سرویس و مستندسازی نقطه شروع خوبی است.

نتیجه‌گیری

Rich فاصله میان یک اسکریپت کاربردی و یک ابزار خط فرمان حرفه‌ای را کوتاه می‌کند. با Console پیام‌ها را واضح کنید، با Table داده را منظم نشان دهید، برای کارهای طولانی نوار پیشرفت بسازید و خطاها را طوری نمایش دهید که کاربر بداند قدم بعدی چیست. از رنگ به‌عنوان راهنمای معنا استفاده کنید، نه تزئین بی‌هدف؛ سپس خروجی تعاملی را از حالت مناسب برای ماشین جدا کنید. نتیجه ابزاری است که هم در ترمینال روزمره دلپذیر است و هم در پروژه واقعی قابل نگهداری.

سوالات متداول

آیا Rich روی ویندوز هم کار می‌کند؟

بله. Rich برای محیط‌های رایج ویندوز، لینوکس و macOS طراحی شده است. بااین‌حال بهتر است عرض کم ترمینال و اجرای برنامه در محیط‌های غیرتعاملی را هم آزمایش کنید.

آیا Rich جایگزین argparse یا Typer است؟

خیر. Rich بیشتر روی نمایش خروجی تمرکز دارد. argparse یا Typer ورودی‌ها، گزینه‌ها و فرمان‌ها را مدیریت می‌کنند و می‌توانند در کنار Rich استفاده شوند.

چطور رنگ‌ها را در لاگ CI خاموش کنم؟

برای محیط CI یک حالت plain یا JSON در برنامه تعریف کنید و در آن از خروجی ساده استفاده کنید. همچنین می‌توانید تشخیص تعاملی بودن ترمینال را مبنای انتخاب حالت نمایش قرار دهید.

آموزش ساخت ابزار خط فرمان حرفه‌ای با Rich در پایتون؛ از رنگ‌بندی تا جدول و نوار پیشرفت