اگر برای پروژه‌های هوش مصنوعی‌ هر بار یک اسکریپت جدا با argparse می‌نویسید و از مدیریت --help و ولیدیشن خسته شده‌اید، Typer پایان همین دردسر است. Typer کتابخانه‌ای مدرن از خالق FastAPI است که با تایپ‌هینت، از یک تابع معمولی یک CLI کامل با راهنمای خودکار و ولیدیشن می‌سازد. در ادامه نصب، اولین دستور، ساب‌کامند و ترکیب با Rich را گام‌به‌گام می‌بینید.

Typer در پایتون چیست و چرا بهترین گزینه برای ساخت CLI است؟

Typer یک فریم‌ورک CLI بر پایه تایپ‌هینت است که تابع پایتون شما را به دستور ترمینال تبدیل می‌کند؛ نوع پارامتر را از int، Path یا Enum می‌خواند، ورودی را اعتبارسنجی و --help رنگی می‌سازد. برخلاف argparse که تعریف دستی می‌خواهد و Click که دکوراتور سنگین دارد، Typer با کمترین کد، امن‌تر و خواناتر است— به‌ویژه برای ابزارهای دیتا و AI. در ادامه نصب و هفت الگوی کاربردی را می‌خوانید.

فهرست مطالب

پیش‌نیازها و نصب Typer
اولین CLI با Typer؛ سلام دنیای تایپ‌محور
آرگومان‌ها، آپشن‌ها و انواع داده قدرتمند
زیرفرمان‌ها (Subcommands) و سازماندهی پروژه بزرگ
ترکیب Typer و Rich؛ CLI زیبا برای ابزارهای هوش مصنوعی
مقایسه Typer با Click و argparse
کاربرد واقعی؛ ساخت ابزار دانلود و پیش‌پردازش دیتاست AI
اشتباهات رایج هنگام کار با Typer
سوالات متداول
جمع‌بندی

پیش‌نیازها و نصب Typer

به پایتون ۳.۸+ و یک venv تمیز نیاز دارید. Typer سبک است و با یک دستور نصب می‌شود. اگر FastAPI کار کرده‌اید، منطق آن کاملاً آشناست.

python -m venv .venv
# ویندوز: .venv\Scripts\activate
source .venv/bin/activate
pip install --upgrade typer rich
typer --help  # باید راهنما نمایش داده شود

نسخه پیشنهادی: Typer نسخه 0.12 به بالا با Rich داخلی. با pip show typer نسخه را چک کنید.
ویرایشگر: VS Code با افزونه Pylance تا تایپ‌هینت‌ها را همان‌جا چک کند و غلط‌های نوع را قبل از اجرا بگیرید.
محیط تمیز: همیشه در venv کار کنید تا تداخل با click سیستم رخ ندهد.
جایگزین: اگر پروژه‌تان Poetry یا PDM دارد، poetry add typer rich کافی است.

Typer روی Click سوار است اما شما مستقیم با Click کار نمی‌کنید و سازگار می‌ماند.

اولین CLI با Typer؛ سلام دنیای تایپ‌محور

ساده‌ترین CLI فقط یک تابع است. نام تابع به دستور تبدیل می‌شود، پارامترها آرگومان و داک‌استرینگ به --help می‌رود.

# main.py
import typer

app = typer.Typer(help="ابزار خوش‌آمدگویی ساده")

@app.command()
def hello(name: str, formal: bool = False):
    """به کاربر سلام کن"""
    if formal:
        typer.echo(f"سلام جناب {name} عزیز")
    else:
        typer.echo(f"سلام {name}!")

if __name__ == "__main__":
    app()

python main.py --help
python main.py Ali
python main.py Ali --formal

توضیح خط‌به‌خط کد

app = typer.Typer(): اپ اصلی را می‌سازد؛ پارامتر help توضیح کلی CLI است.
@app.command(): تابع زیرش را به یک دستور ترمینال تبدیل می‌کند.
name: str: آرگومان اجباری؛ اگر ندهید Typer خطای واضح می‌دهد.
formal: bool = False: چون مقدار پیش‌فرض دارد، خودکار به آپشن --formal / --no-formal تبدیل می‌شود.
typer.echo: مانند print اما با پشتیبانی رنگ و تست‌پذیری بهتر.

خروجی --help رنگی و بخش‌بندی‌شده است و نیازی به نوشتن دستی راهنما نیست.

آرگومان‌ها، آپشن‌ها و انواع داده قدرتمند

قدرت Typer در typer.Argument و typer.Option است. مقدار پیش‌فرض، راهنما و محدوده را بدون شرط‌نویسی تعریف می‌کنید.

import typer
from pathlib import Path
from typing_extensions import Annotated
from enum import Enum

class Mode(str, Enum):
    train = "train"
    eval = "eval"

app = typer.Typer()

@app.command()
def process(
    input: Annotated[Path, typer.Argument(help="مسیر فایل ورودی", exists=True)],
    output: Annotated[Path, typer.Option(help="پوشه خروجی")] = Path("./out"),
    mode: Mode = Mode.train,
    epochs: Annotated[int, typer.Option(min=1, max=100, help="تعداد اپوک")] = 10,
    lr: float = 0.001,
    verbose: bool = False
):
    """پردازش دیتاست برای آموزش مدل"""
    typer.echo(f"mode={mode.value} epochs={epochs} lr={lr}")
    typer.echo(f"input={input} -> output={output}")

if __name__ == "__main__":
    app()

Annotated: شیوه مدرن (پایتون ۳.۹+) برای افزودن متادیتا بدون تغییر نوع؛ جایگزین قدیمی typer.Argument(...) به‌عنوان مقدار پیش‌فرض است.
Path with exists=True: اگر فایل وجود نداشته باشد Typer قبل از اجرای تابع خطا می‌دهد.
Enum: فقط train یا eval قبول می‌شود؛ ورودی اشتباه با پیام راهنما رد می‌شود.
min/max: ولیدیشن عددی خودکار؛ نیازی به if epochs < 1 نیست.
bool: خودکار به پرچم --verbose / --no-verbose تبدیل می‌شود.

همین الگو را می‌توانید برای APIها تعمیم دهید؛ مثلاً یک CLI که مسیر فایل JSON را می‌گیرد و به API می‌فرستد. اگر وب‌سرویس می‌سازید، آموزش FastAPI در پایتون مکمل همین CLI خواهد بود.

زیرفرمان‌ها (Subcommands) و سازماندهی پروژه بزرگ

وقتی ابزارتان بیش از یک کار می‌کند — مثلاً dataset download، dataset clean، model train — باید از Typer اپ‌های تو‌در‌تو استفاده کنید. هر گروه یک Typer() جدا و با add_typer به اپ اصلی وصل می‌شود.

# cli.py
import typer

app = typer.Typer(help="ابزار مدیریت پروژه AI")
dataset_app = typer.Typer(help="مدیریت دیتاست")
model_app = typer.Typer(help="مدیریت مدل")

app.add_typer(dataset_app, name="dataset")
app.add_typer(model_app, name="model")

@dataset_app.command("download")
def dataset_download(url: str, out: str = "./data"):
    """دانلود دیتاست از URL"""
    typer.echo(f"downloading {url} -> {out}")

@dataset_app.command("clean")
def dataset_clean(path: str):
    """پاک‌سازی دیتاست"""
    typer.echo(f"cleaning {path}")

@model_app.command("train")
def model_train(epochs: int = 10):
    """آموزش مدل"""
    typer.echo(f"training {epochs} epochs")

if __name__ == "__main__":
    app()

python cli.py --help
python cli.py dataset --help
python cli.py dataset download https://example.com/data.zip
python cli.py model train --epochs 20

سلسله‌مراتب: هر add_typer یک گروه می‌سازد؛ می‌توانید سه سطح هم داشته باشید.
راهنمای لایه‌ای: --help در هر سطح فقط همان گروه را توضیح می‌دهد و شلوغ نمی‌شود.
تفکیک فایل: در پروژه واقعی، dataset_app را در commands/dataset.py و model_app را در commands/model.py نگه دارید و فقط import کنید.
کالبد پروژه پیشنهادی: cli.py + commands/ + core/ برای منطق اصلی تا تست جدا بماند.

ترکیب Typer و Rich؛ CLI زیبا برای ابزارهای هوش مصنوعی

اگر rich نصب باشد، --help رنگی می‌شود و می‌توانید خروجی‌های خود را هم با Rich بسازید.

import typer
from rich.console import Console
from rich.table import Table
from rich.progress import track
import time

app = typer.Typer()
console = Console()

@app.command()
def show(files: list[str]):
    """نمایش جدول فایل‌ها با Rich"""
    table = Table(title="فایل‌های پردازش شده")
    table.add_column("نام فایل", style="cyan")
    table.add_column("وضعیت", style="green")
    for f in track(files, description="پردازش..."):
        time.sleep(0.2)
        table.add_row(f, "✓ موفق")
    console.print(table)

if __name__ == "__main__":
    app()

Console و Table: خروجی حرفه‌ای بدون HTML؛ رنگ‌ها در ترمینال ویندوز، مک و لینوکس درست نمایش داده می‌شود.
progress: با track یا Progress می‌توانید نوار پیشرفت برای دانلود دیتاست یا آموزش مدل بسازید.
typer.echo vs console.print: برای پیام ساده typer.echo، برای جدول و Markdown ترمینال console.print بهتر است.
تجربه کاربری: اگر CLI شما برای تیم دیتا است، همین جدول و نوار پیشرفت نرخ خطای اپراتور را کم می‌کند چون وضعیت شفاف است.

برای CLIهای آفلاین که با مدل محلی کار می‌کنند، همین الگو را می‌توانید به Ollama وصل کنید؛ مثلاً ai chat --prompt "خلاصه کن" که پشت‌صحنه به localhost:11434 می‌زند. اگر هنوز Ollama را ندارید، آموزش نصب Ollama و اجرای مدل آفلاین را بخوانید.

مقایسه Typer با Click و argparse

انتخاب ابزار به اندازه پروژه و نیاز به تایپ بستگی دارد.

معیار	Typer	Click	argparse (استاندارد)
تعریف دستور	تابع با تایپ‌هینت، بدون دکوراتور شلوغ	دکوراتورهای @click.command / @click.option	افزودن دستی parser.add_argument
ولیدیشن	خودکار از نوع (Path, Enum, min/max)	با callback دستی	دستی با if و type
راهنمای خودکار	بله، رنگی با Rich	بله اما بدون رنگ پیش‌فرض	بله، ساده و بی‌رنگ
ساب‌کامند	بسیار ساده با add_typer	با group	با subparsers پیچیده
یادگیری	بسیار آسان اگر تایپ‌هینت بدانید	متوسط	آسان برای یک فایل، سخت برای پروژه بزرگ
وابستگی	وابسته به Click (نصب خودکار)	مستقل	بدون وابستگی
مناسب برای	ابزار AI/دیتا مدرن، FastAPI کارها	CLIهای بزرگ سازمانی قدیمی	اسکریپت یک‌فایلی ساده

اگر اسکریپت‌تان یک فایل ۵۰ خطی است، argparse کافی است. اگر CLI چنددستوری با ولیدیشن و رنگ می‌خواهید، Typer سریع‌ترین راه و اگر پروژه قدیمی Click دارد، همان Click را نگه دارید.

کاربرد واقعی؛ ساخت ابزار دانلود و پیش‌پردازش دیتاست AI

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

# ai_tool.py
import typer
from pathlib import Path
import httpx
import zipfile
from rich.progress import Progress

app = typer.Typer(help="ابزار دیتاست AI")

@app.command()
def prepare(
    url: str = typer.Argument(help="لینک zip دیتاست"),
    out: Path = typer.Option(Path("./data"), help="پوشه خروجی"),
    clean: bool = typer.Option(False, help="حذف فایل‌های temp پس از اتمام")
):
    """دانلود و آماده‌سازی دیتاست"""
    out.mkdir(parents=True, exist_ok=True)
    zip_path = out / "dataset.zip"

    # دانلود با نوار پیشرفت
    with httpx.stream("GET", url, follow_redirects=True) as r:
        r.raise_for_status()
        total = int(r.headers.get("content-length", 0))
        with Progress() as progress:
            task = progress.add_task("دانلود...", total=total)
            with open(zip_path, "wb") as f:
                for chunk in r.iter_bytes(8192):
                    f.write(chunk)
                    progress.update(task, advance=len(chunk))

    # استخراج
    with zipfile.ZipFile(zip_path) as z:
        z.extractall(out)
    typer.echo(f"استخراج شد در {out}")

    if clean:
        zip_path.unlink(missing_ok=True)
        typer.echo("فایل zip حذف شد")

if __name__ == "__main__":
    app()

httpx: جایگزین مدرن requests با پشتیبانی stream و async؛ برای CLIهای دانلود عالی است.
Progress: تجربه کاربری را از «آیا هنگ کرده؟» به «۳۲٪ مانده» تبدیل می‌کند.
Path: تایپ Path مسیر را به شیء قابل اطمینان تبدیل و ساخت پوشه را با mkdir ایمن می‌کند.
قابل تست: منطق دانلود را در core/download.py جدا کنید و در تست با typer.testing.CliRunner فقط CLI را تست کنید.

# test_cli.py
from typer.testing import CliRunner
from ai_tool import app

runner = CliRunner()
result = runner.invoke(app, ["--help"])
assert result.exit_code == 0
assert "prepare" in result.output
print("CLI test passed")

اشتباهات رایج هنگام کار با Typer

مخلوط کردن Annotated و مقدار پیش‌فرض قدیمی: یا از Annotated[str, typer.Argument(...)] استفاده کنید یا از typer.Argument("default") به‌عنوان مقدار؛ ترکیب هر دو باعث خطای مبهم می‌شود.
فراموشی if __name__ == "__main__": app(): بدون این خط، python main.py --help چیزی اجرا نمی‌کند و به‌نظر می‌رسد Typer خراب است.
استفاده از list بدون تایپ داخلی: بنویسید list[str] نه list تنها؛ وگرنه ولیدیشن و help درست کار نمی‌کند.
ولیدیشن را دوباره با if نوشتن: وقتی Path(exists=True) یا min/max دارید، شرط دستی تکراری است و پیام خطای یکدست Typer را خراب می‌کند.
اجرای منطق سنگین داخل تابع CLI: تابع CLI فقط باید آرگومان بگیرد و به تابع هسته در core/ بدهد؛ وگرنه تست با CliRunner کند و وابسته به شبکه می‌شود.

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

آیا Typer جایگزین کامل Click است؟

بله برای پروژه جدید؛ Typer روی Click ساخته شده و تمام قابلیت‌های Click را پوشش می‌دهد اما با API ساده‌تر. اگر پروژه قدیمی Click دارید، نیازی به مهاجرت نیست مگر اینکه به تایپ‌هینت و Rich نیاز داشته باشید.

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

argparse در کتابخانه استاندارد است و بدون نصب کار می‌کند اما تعریف دستی و ولیدیشن دستی می‌خواهد. Typer با تایپ‌هینت، راهنمای رنگی، ساب‌کامند آسان و ولیدیشن خودکار، برای ابزارهای چنددستوری و تیمی بسیار سریع‌تر است.

چطور ورودی کاربر را اعتبارسنجی کنم؟

از نوع‌ها استفاده کنید: Path(exists=True) برای وجود فایل، Enum برای انتخاب محدود، Annotated[int, typer.Option(min=1, max=100)] برای بازه عددی و Annotated[str, typer.Option(prompt=True)] برای پرسش تعاملی. نیازی به کد شرطی نیست.

آیا Typer با Rich حتماً باید نصب شود؟

خیر، ولی شدیداً توصیه می‌شود. بدون Rich، راهنما و خطاها ساده نمایش داده می‌شود؛ با pip install rich همان کد، خروجی رنگی، جدول و --help خواناتر می‌دهد بدون تغییر کد شما.

چطور CLI را تست کنم؟

از typer.testing.CliRunner استفاده کنید: runner.invoke(app, ["dataset", "download", "url"]) را صدا بزنید و exit_code و output را assert کنید. منطق اصلی را جدا نگه دارید تا تست‌ها بدون شبکه و سریع بمانند.

آیا Typer برای CLIهای سازمانی بزرگ مناسب است؟

بله. با add_typer می‌توانید ده‌ها ساب‌کامند را در پوشه commands/ تفکیک کنید، تست جدا بنویسید و حتی پلاگین لود کنید. برای تیم FastAPI، هماهنگی Typer + Pydantic یک مزیت بزرگ است.

جمع‌بندی

Typer را در venv با pip install typer rich نصب و با typer --help سلامت را چک کنید.
هر دستور یک تابع تایپ‌دار است؛ @app.command() و داک‌استرینگ، CLI و --help را خودکار می‌سازد.
از Annotated + typer.Argument/Option، Path، Enum و min/max برای ولیدیشن بی‌کد استفاده کنید.
برای ابزار بزرگ، گروه‌ها را با add_typer بسازید و هر گروه را در فایل جدا نگه دارید.
برای UX حرفه‌ای، rich را وصل کنید و با Table و Progress خروجی زیبا بسازید.
منطق هسته را از لایه CLI جدا و با CliRunner تست کنید؛ از امروز یک دستور prepare واقعی برای دیتاست خود بسازید.

آموزش Typer در پایتون؛ ساخت CLI حرفه‌ای برای ابزار AI