آموزش کامل Type Hinting در پایتون

سطح مقدماتی (Beginner Level)

پایتون یک زبان Dynamic Type است، به این معنی که مفسر پایتون در زمان اجرا نوع داده‌ها (Type) را تشخیص می‌دهد و نیازی نیست شما آن‌ها را صریحاً بنویسید. اما در پروژه‌های بزرگ و کار تیمی، ندانستن نوع ورودی و خروجی توابع می‌تواند باعث سردرگمی و باگ شود.

تایپ هینتینگ (Type Hinting) راهی است برای مشخص کردن نوع داده‌ها در کد، که به خوانایی کمک می‌کند و ابزارهای ویرایشگر (IDE) را قادر می‌سازد تا خطاها را قبل از اجرا تشخیص دهند.

۱. تایپ هینتینگ متغیرها (Variable Annotations)

ساده‌ترین شکل استفاده از Type Hint، مشخص کردن نوع متغیر هنگام تعریف آن است. این کار با استفاده از علامت : انجام می‌شود.

توجه کنید که پایتون این‌ها را نادیده می‌گیرد و اگر نوع اشتباهی بریزید، خطا نمی‌دهد (مگر اینکه از ابزارهای جانبی استفاده کنید)، اما برای مستندسازی عالی است.

۲. تایپ هینتینگ در توابع (Function Annotations)

مهم‌ترین کاربرد Type Hinting در تعریف توابع است. شما می‌توانید نوع پارامترهای ورودی و نوع خروجی تابع (Return Type) را مشخص کنید. برای خروجی از علامت -> استفاده می‌شود.

# Example 2: Function that returns None (Static snippet)
# وقتی تابع چیزی برنمی‌گرداند، نوع خروجی None است
def greet(name: str) -> None:
    print(f"Hello, {name}")

سطح پیشرفته (Professional Level)

در سطح حرفه‌ای، نوع داده‌ها همیشه ساده (مثل int یا str) نیستند. ما با لیست‌ها، دیکشنری‌ها، مقادیر اختیاری (Optional) و انواع ترکیبی سروکار داریم. برای مدیریت این‌ها، پایتون ماژول typing را ارائه می‌دهد (هرچند در نسخه‌های جدیدتر پایتون ۳.۹+، بسیاری از این‌ها به صورت داخلی پشتیبانی می‌شوند).

۱. لیست‌ها و دیکشنری‌ها (Generics)

وقتی می‌گویید یک متغیر list است، کافی نیست. باید بگویید "لیستی از چه چیزی؟". برای این کار از براکت [] استفاده می‌کنیم.

• در پایتون ۳.۹ به بعد: list[int], dict[str, int]
• در نسخه‌های قدیمی‌تر: List[int], Dict[str, int] (از ماژول typing)

۲. نوع داده‌های ترکیبی (Union و Optional)

گاهی یک متغیر می‌تواند "یا عدد باشد یا رشته". برای این کار از Union یا عملگر | (در پایتون ۳.۱۰+) استفاده می‌کنیم. همچنین اگر مقداری بتواند None باشد، از Optional استفاده می‌شود.

۳. تعریف نوع‌های سفارشی (Type Aliases)

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

# Example 2: Complex Alias (Static)
from typing import Union

# یک تایپ پیچیده برای پاسخ API
JSONValue = Union[str, int, float, bool, None, list['JSONValue'], dict[str, 'JSONValue']]

def parse_data(data: JSONValue):
    pass

۴. نوع داده Callable (برای توابع)

اگر بخواهید تابعی را به عنوان آرگومان به تابع دیگر پاس دهید، باید مشخص کنید که آن ورودی یک "تابع" است. از Callable[[ArgTypes], ReturnType] استفاده می‌کنیم.