Type Hints في بايثون: دليل شامل لاستخدام التعليقات التوضيحية للأنواع

ما هي Type Hints في بايثون؟

Type Hints (التعليقات التوضيحية للأنواع) هي نظام لتحديد أنواع البيانات المتوقعة في كود بايثون، مما يساعد على تحسين قابلية القراءة والموثوقية وجودة البرامج. على الرغم من أن بايثون تظل لغة ديناميكية الأنواع، إلا أن إمكانية تحديد الأنواع بوضوح تساعد في تجنب العديد من الأخطاء أثناء مرحلة التطوير.

لماذا نحتاج إلى التعليقات التوضيحية للأنواع؟

تشتهر بايثون بمرونتها، ولكن هذه المرونة غالبًا ما تؤدي إلى أخطاء خفية بسبب أنواع البيانات غير المتوقعة. لنلق نظرة على مثال بدون تعليقات توضيحية:

def add(a, b):
    return a + b

print(add(5, 10))    # 15
print(add("5", "10"))  # '510' — نتيجة غير متوقعة

التعبير add("5", "10") لن يتسبب في خطأ، لكن النتيجة قد تكون غير متوقعة للمطور.

تحل Type Hints المشكلات التالية:

• تحديد الأنواع بوضوح للمعاملات والقيم المُرجعة
• تحسين قابلية قراءة الكود لفريق التطوير
• التحليل الثابت لاكتشاف الأخطاء قبل تنفيذ البرنامج
• الإكمال التلقائي في بيئة التطوير مع تلميحات أكثر دقة
• توثيق API دون الحاجة إلى تعليقات إضافية

أمثلة أساسية لاستخدام Type Hints

التعليق على الدوال

def add(a: int, b: int) -> int:
    return a + b

def calculate_area(radius: float) -> float:
    return 3.14159 * radius ** 2

def format_greeting(name: str) -> str:
    return f"مرحبًا، {name}!"

التعليق على المتغيرات

name: str = "أحمد"
age: int = 30
pi: float = 3.14159
is_active: bool = True

العمل مع المجموعات

from typing import List, Dict, Tuple, Set

def process_scores(scores: List[int]) -> float:
    return sum(scores) / len(scores)

def get_user_data() -> Dict[str, str]:
    return {"name": "John", "email": "john@example.com"}

def get_coordinates() -> Tuple[float, float]:
    return (10.5, 20.3)

def unique_values(items: List[str]) -> Set[str]:
    return set(items)

إمكانيات متقدمة في Type Hints

Optional و Union

from typing import Optional, Union

def greet(name: Optional[str] = None) -> str:
    if name:
        return f"مرحبًا، {name}!"
    return "مرحبًا، ضيف!"

def process_value(value: Union[int, float, str]) -> str:
    return str(value)

# في Python 3.10+ يمكن استخدام العامل |
def process_new_syntax(value: int | float | str) -> str:
    return str(value)

أنواع Callable

from typing import Callable

def apply_function(func: Callable[[int, int], int], a: int, b: int) -> int:
    return func(a, b)

def multiply(x: int, y: int) -> int:
    return x * y

result = apply_function(multiply, 5, 3)  # 15

أنواع Generic

from typing import TypeVar, Generic, List

T = TypeVar('T')

class Stack(Generic[T]):
    def __init__(self) -> None:
        self.items: List[T] = []
    
    def push(self, item: T) -> None:
        self.items.append(item)
    
    def pop(self) -> T:
        if not self.items:
            raise IndexError("المكدس فارغ")
        return self.items.pop()
    
    def is_empty(self) -> bool:
        return len(self.items) == 0

# الاستخدام
int_stack = Stack[int]()
int_stack.push(42)

التعليقات التوضيحية في الكلاسات

from typing import List, Optional
from dataclasses import dataclass

class Person:
    def __init__(self, name: str, age: int, email: Optional[str] = None) -> None:
        self.name = name
        self.age = age
        self.email = email

@dataclass
class Employee:
    name: str
    position: str
    salary: float
    skills: List[str]