اگر پروژه‌های هوش مصنوعی و ابزارهای خط فرمان خود را با پایتون می‌نویسید، بارها شده خطای نوع را فقط وقتی دیده‌اید که برنامه وسط اجرا کرش کرده است. mypy یک تایپ‌چک ایستا (static type checker) است که بدون اجرای کد، تایپ‌هینت‌ها را می‌خواند و خطاهای پنهان را قبل از اجرا یا در CI لو می‌دهد. در این آموزش از نصب و اولین خطا تا حالت strict و اجرای موازی نسخه ۲ را گام‌به‌گام می‌بینید.

mypy چیست و چه خطاهایی را قبل از اجرا می‌گیرد؟

mypy یک تایپ‌چک ایستا برای پایتون است که با تحلیل تایپ‌هینت‌ها پیش از اجرا، ناسازگاری نوع‌ها را پیدا می‌کند؛ مثلاً پاس‌دادن int به تابعی که str می‌خواهد یا دسترسی به صفت ناموجود. نسخه ۲ آن اجرای موازی و تنظیمات سخت‌گیرانه‌تری دارد و مکمل Ruff برای لینت و Pytest برای تست است. ادامه را بخوانید تا از نصب تا اجرا در CI را کامل یاد بگیرید.

فهرست مطالب

mypy چیست و چرا برای پروژه‌های هوش مصنوعی مهم است؟
پیش‌نیازها و نصب mypy
اولین تایپ‌چک؛ از تایپ‌هینت تا خطای واقعی
حالت strict و فایل پیکربندی pyproject.toml
رفع خطاهای رایج: Optional، Any و type: ignore
mypy در برابر Pyright؛ کدام را انتخاب کنیم؟
خودکارسازی تایپ‌چک در CI و pre-commit
اشتباهات رایج هنگام کار با mypy
سوالات متداول
جمع‌بندی

mypy چیست و چرا برای پروژه‌های هوش مصنوعی مهم است؟

mypy ابزار اختیاریِ تایپ‌چک ایستا برای پایتون است که PEP 484 را پیاده می‌کند. برخلاف تست که کد را اجرا می‌کند، mypy فقط کد را می‌خواند و از تایپ‌هینت‌ها نتیجه می‌گیرد. مهم‌ترین سود آن برای پروژه‌های AI این است که ساختار داده‌ها (لیست امبدینگ‌ها، دیکشنری متادیتا، خروجی JSON مدل) حجیم و تودرتو است و یک اشتباه کوچک نوع، ساعاتی دیباگ رو‌تایم می‌سازد.

پیداکردن باگ قبل از اجرا: مثلاً وقتی خروجی تابع می‌تواند None باشد ولی کد بدون بررسی از آن استفاده می‌کند.
مستندسازی زنده: امضای تابع با تایپ، قرارداد ورودی و خروجی را برای تیم روشن می‌کند.
ری‌فکتور مطمئن: با تغییر نام یا جابه‌جایی تابع، mypy نقاطی که باید به‌روز شوند را نشان می‌دهد.
تکمیل خودکار بهتر: ادیتورهایی مثل VS Code با Pylance از همین انوتیشن‌ها برای پیشنهاد دقیق‌تر استفاده می‌کنند.

mypy را در کنار لینتر نگذارید؛ Ruff کیفیت و سبک کد را می‌سنجد و mypy صحت نوع‌ها را. این دو مکمل هم‌اند، نه رقیب.

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

mypy از نسخه ۱.۲۰ به بعد دیگر با پایتون ۳.۹ اجرا نمی‌شود و کمینه نسخه هدف هم ۳.۱۰ است؛ پس روی پایتون ۳.۱۰ به بالا کار کنید. نصب آن سبک است و نباید وابستگی‌های رانتایم پروژه را شلوغ کند.

python -m venv .venv
# ویندوز: .venv\Scripts\activate
source .venv/bin/activate
python -m pip install -U mypy
python -m mypy --version

محیط تمیز: همیشه داخل venv نصب کنید تا mypy با نسخه پایتون سیستم قاطی نشود.
وابستگی توسعه: آن را در گروه dev بگذارید، مثلاً uv add --dev mypy یا poetry add --group dev mypy؛ نه در وابستگی‌های اجرای سرویس.
ساختار پیشنهادی: کد را در پوشه src/ نگه دارید تا اجرای python -m mypy src/ ساده باشد.
بدون وابستگی سنگین: mypy به‌طور پیش‌فرض روی خودش هیچ افکت اجرایی ندارد و کد را اجرا نمی‌کند.

اولین تایپ‌چک؛ از تایپ‌هینت تا خطای واقعی

ساده‌ترین راه دیدن قدرت mypy، یک خطای عمدی است. فایل زیر را بسازید؛ تابع انتظار دارد لیستی از قیمت‌ها و «درصد تخفیف به‌صورت عدد» بگیرد، اما نوع اشتباهی اعلام شده است.

# money.py
def total_price(prices: list[int], discount: str) -> int:
    return sum(prices) - discount

print(total_price([100, 250], "10"))

python -m mypy money.py
# money.py:2: error: Unsupported operand types for - ("int" and "str")  [operator]
# Found 1 error in 1 file (checked 1 source file)

توضیح خط‌به‌خط خروجی

نام فایل و شماره خط: mypy دقیقاً می‌گوید کدام خط مشکل دارد تا در ادیتور پرش کنید.
پیام خطا: «عملگر - بین int و str پشتیبانی نمی‌شود» — همان باگی که در اجرای واقعی کرش می‌کرد.
کد خطا داخل براکت: مثل [operator]؛ برای نادیده‌گرفتن دقیق یا خاموش‌کردن گروهی همان قاعده به کار می‌آید.
خلاصه: تعداد خطا و فایل‌های بررسی‌شده را می‌شمارد تا در CI معیار بگذارید.

تابع را اصلاح کنید (مثلاً discount: int یا محاسبه درصد) و دوباره اجرا کنید؛ خروجی موفق Success: no issues found in 1 source file است.

حالت strict و فایل پیکربندی pyproject.toml

اجرای پیش‌فرض mypy محافظه‌کار است و بدنه توابع بدون انوتیشن را بررسی نمی‌کند. برای پروژه جدی، تنظیمات را در pyproject.toml بگذارید تا همه اعضای تیم یکسان اجرا کنند.

# pyproject.toml
[tool.mypy]
python_version = "3.12"
strict = true
warn_unused_ignores = true
warn_return_any = true
pretty = true

[[tool.mypy.overrides]]
module = "some_legacy_package.*"
ignore_missing_imports = true

python -m mypy src/

strict = true: بسته‌ای از بررسی‌های سخت‌گیرانه (انوتیشن اجباری، Any ضمنی و...) را روشن می‌کند؛ فهرست این بسته بین نسخه‌ها تغییر می‌کند.
python_version: نسخه هدف را مشخص می‌کند تا mypy از قابلیت‌های نحو جدیدتر به‌اشتباه استفاده نکند.
overrides: برای کتابخانه‌های قدیمی که استاب ندارند، به‌جای خاموش‌کردن کل پروژه فقط همان ماژول را استثنا کنید.
نسخه ۲ و اجرای موازی: از mypy 2.0 گزینه -n یا --num-workers اضافه شده؛ مثلاً python -m mypy -n 8 src/ برای پروژه‌های بزرگ تا چند برابر سریع‌تر است. این حالت هنوز آزمایشی است، پس برای گیت CI حساس، حالت تک‌پروسه محافظه‌کارانه‌تر است.

رفع خطاهای رایج: Optional، Any و type: ignore

بیشتر خطاهای mypy حول سه مفهوم می‌چرخند: نوع‌های نال‌پذیر، نوع Any و نادیده‌گرفتن آگاهانه. نمونه زیر خطای کلاسیک «شاید None باشد» را نشان می‌دهد.

from typing import Optional

def find_user(name: str) -> Optional[dict[str, str]]:
    return {"id": "1", "name": name} if name else None

user = find_user("ali")
print(user["id"])  # error: Value of type "dict[str, str] | None" is not indexable

user = find_user("ali")
if user is not None:
    print(user["id"])  # اینجا mypy نوع را باریک می‌کند و خطا نمی‌دهد

باریک‌سازی نوع (narrowing): بعد از if x is not None یا isinstance، mypy نوع را دقیق‌تر می‌داند.
Any را کوچک نگه دارید: وقتی تابعی خروجی بدون تایپ می‌دهد، به‌جای پر کردن کد با Any، یک cast یا انوتیشن دقیق بنویسید.
type: ignore هدفمند: همیشه کد قاعده را بنویسید: value = legacy() # type: ignore[no-any-return]؛ با warn_unused_ignores اگر روزی لازم نبود، mypy خودش هشدار می‌دهد.
reveal_type برای دیباگ: موقتاً reveal_type(user) بنویسید تا mypy نوعی که استنتاج کرده را چاپ کند.
افزونه Pydantic: اگر از Pydantic استفاده می‌کنید، در پیکربندی plugins = ["pydantic.mypy"] را اضافه کنید تا مدل‌ها دقیق‌تر بررسی شوند.

mypy در برابر Pyright؛ کدام را انتخاب کنیم؟

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

معیار	mypy	Pyright
زبان پیاده‌سازی	پایتون	TypeScript
حالت اصلی	ابزار خط فرمان و CI	سرور زبان و ادیتور (VS Code/Pylance)
سرعت	از نسخه ۲ با اجرای موازی سریع‌تر شده	به‌طور کلی سریع‌تر در ادیتور
پیکربندی	بخش `[tool.mypy]` در pyproject.toml	`pyrightconfig.json` یا `[tool.pyright]`
تطابق با تایپینگ‌اسپک	خوب و در حال بهبود	در آزمون‌های عمومی جلوتر
مناسب برای	پروژه‌های کتابخانه‌ای و پایپ‌لاین AI با CI سخت‌گیر	تجربه ادیتور لحظه‌ای و تیم‌های بزرگ

جمع‌بندی ساده: اگر تجربه ادیتور و بازخورد لحظه‌ای اولویت است، Pyright را با Pylance به کار ببرید. اگر گیت CI سبک، افزونه‌پذیری و اکوسیستم pydantic می‌خواهید، mypy انتخاب رایج است. حتی می‌توانید هر دو را در CI اجرا کنید؛ اما توجه کنید بسته strict هر کدام متفاوت است و لزوماً یک کد یکسانی را قبول نمی‌کنند.

خودکارسازی تایپ‌چک در CI و pre-commit

ارزش mypy وقتی کامل می‌شود که هیچ کامیت بدون تایپ‌چک رد نشود. آن را به پیش‌کامیت و گیت‌هاب اکشن وصل کنید.

# .pre-commit-config.yaml
- repo: https://github.com/pre-commit/mirrors-mypy
  rev: v2.3.1
  hooks:
    - id: mypy
      additional_dependencies: [pydantic]

# .github/workflows/ci.yml (بخش مرتبط)
- name: Type check
  run: |
    python -m pip install -U mypy
    python -m mypy src/

ترتیب ابزارها: اول Ruff (فرمت و لینت)، بعد mypy (نوع)، در انتها Pytest (تست). اگر می‌خواهید این زنجیره را کامل بچینید، آموزش Ruff در پایتون و آموزش Pytest را ببینید.
کش: اجرای mypy را در CI کش کنید تا هر پوش سرعت نگیرد.
گیت تدریجی: روی پروژه قدیمی، ابتدا فقط پوشه‌های هسته را با strict چک کنید و به‌تدریج جلو بروید.

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

اجرای strict روی کل پروژه از روز اول: صدها خطای قدیمی مو‌به‌مو می‌ریزد و تیم دلسرد می‌شود؛ تدریجی جلو بروید.
نصب mypy به‌عنوان وابستگی اجرای سرویس: این ابزار فقط برای توسعه و CI است؛ آن را در گروه dev بگذارید.
پرکردن کد با Any و type: ignore بدون کد خطا: این کار خودِ هدف mypy را خنثی می‌کند. کد قاعده را همیشه بنویسید.
نادیده‌گرفتن نسخه پایتون هدف: اگر python_version را نادرست بگذارید، mypy نحو یا API ناموجود نسخه دیگر را قبول می‌کند.
دوباره‌کاری منطق با شرط‌های اضافه: وقتی mypy از روی انوتیشن‌ها نوع را می‌داند، بررسی‌های تکراری و بی‌فایده فقط کد را شلوغ می‌کند.

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

تفاوت mypy و Pyright در چیست؟

mypy در پایتون نوشته شده و بیشتر ابزار خط فرمان و CI است؛ Pyright در TypeScript نوشته شده و به‌عنوان سرور زبان در VS Code (با نام Pylance) تجربه لحظه‌ای می‌دهد. هر دو تایپ‌چک ایستا هستند اما بسته strict و برخی قواعد استنتاج‌شان متفاوت است.

آیا mypy کد را اجرا می‌کند یا به داده نیاز دارد؟

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

mypy چه نسخه‌ای از پایتون را می‌خواهد؟

نسخه‌های اخیر (۱.۲۰ به بعد) خودشان روی پایتون ۳.۹ اجرا نمی‌شوند و از نسخه ۲ کمینه نسخه هدف هم ۳.۱۰ است. برای بررسی کدِ سازگار با نسخه قدیمی‌تر می‌توانید python_version را در پیکربندی تنظیم کنید.

آیا on کد بدون تایپ‌هینت هم کار می‌کند؟

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

چطور mypy را در گیت‌هاب اکشن اجرا کنم؟

یک استپ بسازید که mypy را نصب و روی پوشه کد اجرا کند: python -m pip install -U mypy و بعد python -m mypy src/. اگر خروجی خطا داشت، اکشن خودکار فیل می‌شود و کامیت نامعتبر جلو نمی‌رود.

آیا mypy با Pydantic و ابزارهای AI سازگار است؟

بله. Pydantic یک افزونه رسمی برای mypy دارد که با plugins = ["pydantic.mypy"] فعال می‌شود و ولیدیشن مدل‌ها را دقیق‌تر بررسی می‌کند. برای کتابخانه‌های بدون استاب هم با ignore_missing_imports فقط همان ماژول را استثنا کنید.

جمع‌بندی

mypy را داخل venv و به‌عنوان وابستگی dev نصب کنید: python -m pip install -U mypy.
اولین تایپ‌چک را با یک فایل کوچک و یک خطای عمدی امتحان کنید تا خروجی mypy را بشناسید.
پیکربندی [tool.mypy] را در pyproject.toml بگذارید و python_version را درست تنظیم کنید.
strict را تدریجی و پوشه‌به‌پوشه روشن کنید، نه یکجا روی کل پروژه قدیمی.
خطاهای Optional، Any و type: ignore را با باریک‌سازی نوع و کد قاعده هدفمند حل کنید.
مکمل‌ها را کامل کنید: Ruff برای لینت، mypy برای نوع، Pytest برای تست و اتصال همه به pre-commit و CI.

آموزش mypy در پایتون؛ تایپ‌چک ایستا برای پروژه‌های AI