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

فهرست مطالب

چرا Typer برای ساخت CLI پایتون مناسب است؟
راه‌اندازی پروژه و نصب وابستگی‌ها
طراحی فرمان‌های اصلی برنامه
اعتبارسنجی ورودی و مدیریت خطا
آزمون‌پذیر کردن CLI
بسته‌بندی و انتشار ابزار
سوالات متداول

چرا Typer برای ساخت CLI پایتون مناسب است؟

Typer روی قابلیت‌های type hint در پایتون ساخته شده است. یعنی نوع پارامتر تابع، نام فرمان و مقدار پیش‌فرض آن می‌تواند هم‌زمان برای تبدیل ورودی، تولید راهنما و نمایش خطا استفاده شود. در نتیجه، کدی که می‌نویسید شبیه یک تابع عادی پایتون است، اما کاربر آن را مانند یک برنامه خط فرمان اجرا می‌کند.

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

چه زمانی باید سراغ Typer برویم؟

هر وقت برنامه شما چند عملیات مشخص دارد، CLI انتخاب مناسبی است؛ برای نمونه تبدیل فایل، اجرای گزارش، مدیریت یک پروژه یا تعامل با API. اگر فقط یک بار قرار است کدی را اجرا کنید، یک اسکریپت ساده کافی است. اما وقتی کاربر باید بین چند فرمان انتخاب کند و برای هر فرمان ورودی متفاوتی بدهد، Typer از رشد بی‌نظم کد جلوگیری می‌کند.

راه‌اندازی پروژه و نصب وابستگی‌ها

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

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS و Linux
source .venv/bin/activate
pip install "typer[all]"

ساختار پیشنهادی ساده است:

taskcli/
  taskcli/
    __init__.py
    cli.py
    storage.py
  tests/
  pyproject.toml

در این مثال، اطلاعات کارها را ابتدا در یک فایل JSON نگه می‌داریم تا تمرکز روی طراحی CLI باشد. در پروژه واقعی می‌توانید لایه storage را با SQLite یا یک API جایگزین کنید، بدون آن‌که رابط فرمان‌ها تغییر کند.

تعریف نخستین برنامه

در فایل cli.py، یک شیء اصلی برای برنامه و یک فرمان برای افزودن کار بسازید:

from pathlib import Path
import typer

app = typer.Typer(help="ابزار مدیریت کارهای روزانه")

@app.command()
def add(title: str, priority: int = typer.Option(2, min=1, max=3)):
    """یک کار جدید به فهرست اضافه می‌کند."""
    typer.echo(f"کار ثبت شد: {title} | اولویت: {priority}")

if __name__ == "__main__":
    app()

اکنون اجرای python -m taskcli.cli --help راهنمای برنامه و اجرای python -m taskcli.cli add "مطالعه مستندات" فرمان را نمایش می‌دهد. توضیح داخل docstring به‌صورت خودکار در راهنما دیده می‌شود.

طراحی فرمان‌های اصلی برنامه

یک CLI خوب باید فرمان‌های کوتاه و قابل‌پیش‌بینی داشته باشد. برای ابزار مدیریت کار، چهار عملیات منطقی عبارت‌اند از add، list، done و remove. هر فرمان بهتر است فقط یک مسئولیت داشته باشد و منطق ذخیره‌سازی در تابعی جدا قرار بگیرد.

استفاده از فرمان‌های تو در تو

اگر برنامه بزرگ شد، می‌توانید گروه‌هایی مانند project یا config بسازید. این کار باعث می‌شود نام‌ها منظم بمانند؛ برای مثال taskcli project create از مجموعه بزرگی از گزینه‌های پراکنده خواناتر است. فرمان‌های تو در تو را با یک نمونه Typer دیگر تعریف و با add_typer به برنامه اصلی متصل می‌کنید.

انتخاب نوع خروجی

برای استفاده انسانی، خروجی جدولی یا رنگی مناسب است؛ اما اسکریپت‌های دیگر معمولاً JSON می‌خواهند. گزینه‌ای مانند --json اضافه کنید و منطق تولید داده را از منطق چاپ جدا نگه دارید. در حالت JSON، از چاپ جمله‌های اضافی در خروجی استاندارد خودداری کنید تا ابزارهایی مانند jq بتوانند نتیجه را پردازش کنند.

فرمان	کاربرد	نمونه اجرا
add	افزودن کار با اولویت	`taskcli add "خرید کتاب" --priority 1`
list	نمایش کارهای باز یا انجام‌شده	`taskcli list --open`
done	تغییر وضعیت یک کار	`taskcli done 4`
remove	حذف کار با تأیید کاربر	`taskcli remove 4`

اعتبارسنجی ورودی و مدیریت خطا

اعتبارسنجی را به بدنه فرمان موکول نکنید. گزینه‌هایی مانند min و max برای اعداد، ورودی نامعتبر را پیش از اجرای منطق اصلی متوقف می‌کنند. برای مسیر فایل نیز از نوع typer.File یا Path استفاده کنید و وجود فایل را صریحاً بررسی کنید.

پیام خطای مفید بنویسید

پیام «خطا رخ داد» کمکی به کاربر نمی‌کند. مشخص کنید کدام شناسه پیدا نشده، چه مقداری مجاز بوده و کاربر چگونه می‌تواند مشکل را رفع کند. برای خطاهای قابل انتظار، typer.BadParameter یا typer.Exit با کد خروج مناسب به کار ببرید. کد خروج صفر باید فقط به معنای موفقیت باشد؛ این نکته برای استفاده در CI و اسکریپت‌های زمان‌بندی‌شده مهم است.

تأیید عملیات مخرب

قبل از حذف یا بازنویسی اطلاعات، از typer.confirm استفاده کنید. برای اجرای خودکار می‌توانید گزینه‌ای مانند --yes ارائه دهید، اما آن را آگاهانه مستند کنید. ترکیب تأیید تعاملی و گزینه اجبار، هم امنیت استفاده دستی را حفظ می‌کند و هم اجرای خودکار را ممکن می‌سازد.

آزمون‌پذیر کردن CLI

بهترین روش این است که توابعی مثل افزودن یا خواندن کار را در ماژول‌های جدا بنویسید و فرمان Typer فقط ورودی را بگیرد و نتیجه را نمایش دهد. سپس با typer.testing.CliRunner می‌توانید برنامه را بدون باز کردن ترمینال واقعی آزمایش کنید:

from typer.testing import CliRunner
from taskcli.cli import app

def test_add_command():
    result = CliRunner().invoke(app, ["add", "یادگیری Typer"])
    assert result.exit_code == 0
    assert "کار ثبت شد" in result.stdout

علاوه بر مسیر موفق، ورودی خالی، اولویت خارج از بازه، شناسه ناموجود و لغو تأیید را هم تست کنید. اجرای Ruff و pytest در هر تغییر، کیفیت کد و قابل‌اعتماد بودن ابزار را بالا می‌برد؛ برای ایده‌های بیشتر درباره خودکارسازی این مرحله، راهنمای خودکارسازی کیفیت کد پایتون با Ruff و pytest را بخوانید.

بسته‌بندی و انتشار ابزار

وقتی CLI آماده شد، یک entry point در pyproject.toml تعریف کنید تا کاربر مجبور نباشد مسیر فایل پایتون را بداند:

[project.scripts]
taskcli = "taskcli.cli:app"

پس از نصب پروژه با pip install .، فرمان taskcli در سیستم در دسترس خواهد بود. نسخه ابزار، حداقل نسخه پایتون، روش نگهداری فایل داده و نمونه‌های رایج را در README بنویسید. اگر ابزار قرار است در تیم استفاده شود، خروجی و رفتار فرمان‌ها را بدون دلیل تغییر ندهید؛ ثبات رابط خط فرمان از تعداد زیاد قابلیت‌ها مهم‌تر است.

در ادامه می‌توانید تکمیل خودکار، لاگ‌گیری، تنظیمات قابل‌پیکربندی و پشتیبانی از خروجی CSV را اضافه کنید. این قابلیت‌ها را یکی‌یکی و با آزمون پوشش دهید. ابزارهای برنامه‌نویسی زمانی واقعاً مفیدند که نصب ساده، خطای قابل فهم و رفتار تکرارپذیر داشته باشند، نه فقط کد کوتاه.

جمع‌بندی

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

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

آیا Typer فقط برای پروژه‌های بزرگ مناسب است؟

خیر. برای یک اسکریپت چندفرمانی کوچک هم مناسب است، چون راهنما و اعتبارسنجی را با کد کمی فراهم می‌کند. اگر برنامه فقط یک ورودی ساده دارد، ممکن است argparse انتخاب سبک‌تری باشد.

تفاوت Typer و argparse چیست؟

argparse بخشی از کتابخانه استاندارد پایتون است و کنترل مستقیم‌تری می‌دهد، اما معمولاً به تعریف‌های بیشتری نیاز دارد. Typer با type hintها و دکوراتورها تجربه توسعه سریع‌تر و راهنمای خودکار فراهم می‌کند.

آیا می‌توان با Typer خروجی JSON تولید کرد؟

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

چطور با Typer یک ابزار خط فرمان حرفه‌ای در پایتون بسازیم؟