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

پاسخ کوتاه: برای ساخت داشبورد خط فرمان پایتون، Textual را نصب کنید، یک کلاس از App بسازید، چیدمان را در متد compose با ویجت‌هایی مانند Header، Footer، Static و DataTable تعریف کنید و سپس با متدهای واکنشی، داده‌ها و رویدادهای صفحه را کنترل کنید.

Textual چیست و چه زمانی مفید است؟

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

تفاوت Textual با Rich

Rich بیشتر یک ابزار قالب‌بندی خروجی ترمینال است: جدول، پنل، رنگ، نوار پیشرفت و لاگ‌های زیبا را در اختیار شما می‌گذارد. Textual لایهٔ تعاملی را اضافه می‌کند؛ یعنی ویجت‌ها، فوکوس، رویداد، CSS مخصوص ترمینال و چرخهٔ اجرای برنامه. بنابراین Rich برای گزارش یک‌باره عالی است و Textual برای داشبوردی که کاربر در آن جست‌وجو یا انتخاب انجام می‌دهد.

برای چه پروژه‌هایی مناسب است؟

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

نصب و آماده‌سازی پروژه

ابتدا یک محیط مجازی بسازید تا وابستگی‌های داشبورد با پروژه‌های دیگر تداخل نداشته باشد:

python -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows
.venv\Scripts\activate
pip install textual

در ادامه فایل app.py را ایجاد کنید. اسکلت یک برنامهٔ Textual ساده چنین است:

from textual.app import App, ComposeResult
from textual.widgets import Footer, Header, Static

class MonitorApp(App):
    def compose(self) -> ComposeResult:
        yield Header()
        yield Static("در حال آماده‌سازی…", id="status")
        yield Footer()

if __name__ == "__main__":
    MonitorApp().run()

با اجرای python app.py باید سربرگ، یک پیام و نوار پایین صفحه را ببینید. استفاده از type hint در compose اجباری نیست، اما خوانایی و کمک ابزارهای ویرایشگر را بهتر می‌کند.

ساخت چیدمان داشبورد

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

تعریف کانتینرها با CSS

Textual از CSS مخصوص خود استفاده می‌کند. این CSS مانند CSS مرورگر همهٔ ویژگی‌ها را ندارد، اما برای اندازه، رنگ، حاشیه و چیدمان کافی است:

CSS = """
Screen {
    layout: horizontal;
    background: $surface;
}

#services {
    width: 32%;
    border: round $accent;
    padding: 1 2;
}

#details {
    width: 68%;
    border: round $success;
    padding: 1 2;
}
"""

سپس در compose از Horizontal یا Vertical استفاده کنید. هر ویجتی که شناسهٔ id دارد، بعداً با query_one قابل دسترسی است.

انتخاب ویجت مناسب

Static برای متن، Label برای برچسب کوتاه، DataTable برای دادهٔ ستونی و Log برای پیام‌های پیوسته کاربرد دارد. برای ورود اطلاعات، Input و برای عملیات مشخص، Button انتخاب‌های معمول هستند. بهتر است هر ناحیه فقط یک مسئولیت داشته باشد تا هم ظاهر و هم کد قابل نگهداری بماند.

افزودن ویجت‌ها و دادهٔ زنده

حالا یک جدول سرویس و یک متن آماری به داشبورد اضافه می‌کنیم:

from textual.containers import Horizontal, Vertical
from textual.widgets import DataTable, Static

class MonitorApp(App):
    CSS = """
    #services { width: 35%; border: round cyan; }
    #details { width: 65%; border: round green; }
    """

    def compose(self) -> ComposeResult:
        yield Header(show_clock=True)
        with Horizontal():
            with Vertical(id="services"):
                yield Static("سرویس‌ها", classes="title")
                yield DataTable(id="service-table")
            with Vertical(id="details"):
                yield Static("برای دیدن جزئیات یک ردیف را انتخاب کنید", id="details-text")
        yield Footer()

برای پر کردن جدول، از متد on_mount استفاده کنید؛ این متد پس از آماده شدن رابط اجرا می‌شود:

def on_mount(self) -> None:
    table = self.query_one("#service-table", DataTable)
    table.add_columns("سرویس", "وضعیت", "مصرف")
    table.add_rows([
        ("API", "فعال", "۲۳٪"),
        ("Database", "فعال", "۴۱٪"),
        ("Worker", "متوقف", "۰٪"),
    ])

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

به‌روزرسانی بدون متوقف کردن رابط

Textual برای کارهای پس‌زمینه decoratorهایی مانند work دارد. یک worker می‌تواند داده را بخواند و نتیجه را با متد update به ویجت برساند. بازهٔ زمانی به‌روزرسانی را نیز با set_interval تنظیم کنید. برای داده‌های حساس، زمان آخرین دریافت و پیام خطا را در خود داشبورد نمایش دهید تا کاربر تصور نکند عدد قدیمی تازه است.

مدیریت رویدادها و کلیدهای میانبر

یک داشبورد خوب فقط زیبا نیست؛ واکنش‌پذیر است. Textual رویداد انتخاب ردیف، فشردن کلید و کلیک دکمه را به متدهای مشخص تحویل می‌دهد.

افزودن کلید خروج و تازه‌سازی

کلیدهای برنامه در فهرست BINDINGS تعریف می‌شوند:

BINDINGS = [
    ("q", "quit", "خروج"),
    ("r", "refresh", "تازه‌سازی"),
]

def action_refresh(self) -> None:
    self.query_one("#details-text", Static).update("داده‌ها تازه‌سازی شدند")

برای انتخاب یک ردیف، handler مربوط به DataTable.RowSelected را بنویسید و شناسهٔ ردیف را به تابع دریافت جزئیات بدهید. پیام‌های کوتاه را می‌توان با self.notify نمایش داد. این اعلان‌ها برای تأیید ذخیره، هشدار خطای شبکه یا اعلام موفقیت عملیات بسیار مناسب‌اند.

جلوگیری از شلوغی کد

منطق دریافت داده را از کلاس رابط جدا کنید. یک کلاس سرویس یا تابع مستقل بسازید و در رابط فقط loading، موفقیت و خطا را مدیریت کنید. همچنین برای رخدادهای پیچیده، نام‌گذاری دقیق و type hint به مراتب بهتر از چند callback تو در توست. اگر ابزار شما قرار است بزرگ شود، هر ویجت اصلی را در یک کلاس جداگانه از Widget پیاده‌سازی کنید.

نکات تکمیل و انتشار ابزار

پیش از انتشار، داشبورد را در ترمینال‌های مختلف امتحان کنید. عرض کم پنجره، کاراکترهای فارسی، نبودن رنگ و تفاوت Windows با Linux می‌تواند چیدمان را به‌هم بزند. برای حالت بارگذاری یک پیام واضح و برای خطای شبکه مسیر بازگشت بگذارید.

نیاز پروژه	ویجت یا راهکار	نکتهٔ اجرایی
نمایش متن ثابت	Static یا Label	شناسهٔ مشخص برای update کردن
دادهٔ ستونی	DataTable	ستون‌ها را یک‌بار در mount بسازید
پیام‌های پیوسته	Log	حجم لاگ را کنترل کنید
کار زمان‌بر	Worker	رشتهٔ اصلی رابط را مسدود نکنید

برای بسته‌بندی، وابستگی Textual را در pyproject.toml ثبت کنید و یک دستور اجرای روشن در README بنویسید. اگر ابزار شما فرمان‌های متعددی دارد، معماری آن را با یک CLI جدا مدیریت کنید؛ سپس داشبورد Textual را یکی از commandها قرار دهید. برای مقایسه، در آموزش ساخت CLI پایتون با Typer می‌توانید الگوی مناسب‌تری برای طراحی فرمان‌ها ببینید. همچنین اگر داشبورد باید به یک سرویس پیام‌رسان وصل شود، آموزش ساخت ربات تلگرام با پایتون ایده‌هایی برای جدا کردن لایهٔ ارتباطی ارائه می‌دهد.

جمع‌بندی

Textual فاصلهٔ میان یک اسکریپت ساده و یک ابزار حرفه‌ای خط فرمان را کوتاه می‌کند. با شروع از App، چیدمان کانتینری، ویجت‌های کوچک، worker برای کارهای زمان‌بر و چند کلید میانبر می‌توانید داشبوردی سریع و قابل استفاده بسازید. ابتدا یک سناریوی کوچک مانند نمایش وضعیت سه سرویس را پیاده کنید، سپس جست‌وجو، فیلتر، اتصال API و اعلان خطا را مرحله‌به‌مرحله اضافه کنید.

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

آیا Textual فقط روی Linux کار می‌کند؟

خیر. Textual با Python روی Windows، macOS و Linux اجرا می‌شود؛ فقط باید تفاوت فونت، اندازهٔ پنجره و پشتیبانی ترمینال از رنگ را آزمایش کنید.

آیا برای استفاده از Textual باید Rich را جدا نصب کنیم؟

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

چطور اطلاعات API را بدون فریز شدن صفحه نمایش دهیم؟

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

آموزش ساخت داشبورد خط فرمان تعاملی پایتون با Textual