فصل دوم: راه‌اندازی تایپ‌هینت در VS Code

چالش

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

Pylance

Pylance موتورِ تحلیل کد در VS Code است و معمولاً همراه با افزونه‌ی Python نصب می‌شود. در صورت تردید، به بخش Extensions بروید و «Pylance» را جست‌وجو و نصب کنید.

سپس فایل settings.json را باز کنید؛ راه سریعش Ctrl+Shift+P و بعد Preferences: Open User Settings (JSON) است. این خط را اضافه کنید:

{
    "python.analysis.typeCheckingMode": "basic"
}

{
    "python.analysis.typeCheckingMode": "basic"
}

سه حالت وجود دارد:

• off — Pylance هیچ بررسی‌ای انجام نمی‌دهد.
• basic — خطاهای واضح را می‌گیرد. برای شروع همین را انتخاب کنید.
• strict — همه‌چیز را می‌گیرد، حتی توابع بدون هینت را. اگر در تایپ‌هینت تازه کار هستید، این حالت فعلاً برای شما زود است.

آزمایش کنید

این کد را در یک فایل پایتون بنویسید:

def add(x: int, y: int) -> int:
    return x + y

result: str = add(5, 3)

def add(x: int, y: int) -> int:
    return x + y

result: str = add(5, 3)

زیر result یک خط موج‌دار قرمز ظاهر می‌شود و با بردنِ موس روی آن، این پیام را می‌بینید:

Type "int" is not assignable to declared type "str"

نمایشِ این پیام نشان می‌دهد که Pylance درست کار می‌کند.

mypy در ترمینال

Pylance فایلِ باز را لحظه‌ای بررسی می‌کند. با این حال برای سنجشِ یکجای کلِ پروژه — مثلاً پیش از انتشار یا داخل GitHub Actions — به mypy نیاز دارید.

نصب:

pip install mypy

اجرا روی یک فایل:

mypy my_file.py

اجرا روی کل پروژه:

mypy .

فایل تنظیمات

در ریشه‌ی پروژه یک فایل mypy.ini بسازید:

[mypy]
python_version = 3.12
warn_return_any = True
warn_unused_configs = True
ignore_missing_imports = True

نقشِ هر خط چنین است:

• python_version — mypy کد را با قواعدِ همین نسخه می‌سنجد.
• warn_return_any — اگر تابعی نوع خروجیِ مشخصی اعلام کرده باشد ولی در عمل مقداری مبهم برگرداند، اخطار می‌دهد.
• warn_unused_configs — تنظیماتِ بی‌استفاده در همین فایل را گزارش می‌کند.
• ignore_missing_imports — کتابخانه‌هایی که خودشان تایپ‌هینت ندارند را نادیده می‌گیرد. بدون این خط، mypy روی پروژه‌های واقعی صدها خطای بی‌ربط گزارش می‌کند.

یک تنظیم دیگر هم هست که در مراحل بعدی کاربرد دارد:

disallow_untyped_defs = True

این تنظیم اعلام می‌کند که هر تابعی باید تایپ‌هینت داشته باشد. برای پروژه‌ی جدید انتخاب خوبی است، اما در پروژه‌ی قدیمی آن را روشن نکنید.

مقایسه Pylance و mypy

Pylance و mypy رقیب یکدیگر نیستند، بلکه تقسیم کار دارند:

بهتر است هر دو را در اختیار داشته باشید، زیرا Pylance جلوی اشتباهِ لحظه‌ای را می‌گیرد و mypy اشتباهی را می‌یابد که در فایلِ دیگری اثر گذاشته است.

باور غلط رایج

بعضی فکر می‌کنند نبودِ خطا در Pylance به معنای سالم بودنِ کل کد است. با این حال Pylance فقط فایل‌های باز و وابستگی‌های مستقیمشان را تحلیل می‌کند. بنابراین اگر تابعی را در models.py تغییر دهید، ممکن است views.py بشکند و تا زمانی که آن فایل را باز نکرده‌اید از آن خبردار نشوید. اجرای mypy . دقیقاً همین شکاف را پوشش می‌دهد.

خلاصه

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

• حالت بررسی Pylance: مقدار basic را در settings.json قرار دهید تا خطاهای واضح گزارش شوند و حالت strict را به پروژه‌های تازه واگذار کنید.
• نصب و اجرای mypy: با pip install mypy نصب کنید و کل پروژه را با mypy . بسنجید.
• فایل پیکربندی: یک mypy.ini در ریشه‌ی پروژه بسازید و نسخه‌ی پایتون و اخطارها را در آن مشخص کنید.
• کتابخانه‌های بدون هینت: ignore_missing_imports را روشن نگه دارید تا خطاهای بی‌ربط تولید نشود.
• محدوده‌ی دید: Pylance تنها فایل باز را می‌بیند، بنابراین نبود خطا در ویرایشگر به معنای سلامت کل پروژه نیست.

در فصل بعد

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