تلميحات الأنواع

تلميحات الأنواع تجعل كودك موثقاً ذاتياً وتساعد في اكتشاف الأخطاء قبل التشغيل. أُطر الذكاء الاصطناعي الحديثة تستخدمها بشكل مكثف.

تلميحات الأنواع الأساسية

# تعليقات المتغيرات
name: str = "Claude"
temperature: float = 0.7
max_tokens: int = 1000
is_streaming: bool = True

# تعليقات الدوال
def greet(name: str) -> str:
    return f"مرحباً، {name}!"

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

أنواع المجموعات

from typing import List, Dict, Tuple, Optional

# قائمة من السلاسل النصية
messages: List[str] = ["مرحباً", "عالم"]

# قاموس بمفاتيح نصية وقيم أي نوع
config: Dict[str, any] = {"model": "gpt-4", "temp": 0.7}

# قاموس منوّع
settings: Dict[str, str] = {"model": "gpt-4"}

# صف بأنواع محددة
point: Tuple[int, int] = (10, 20)

# قائمة من القواميس (شائع في الذكاء الاصطناعي)
chat_history: List[Dict[str, str]] = [
    {"role": "user", "content": "مرحباً"},
    {"role": "assistant", "content": "أهلاً!"}
]

Optional و Union

from typing import Optional, Union

# Optional: يمكن أن يكون النوع أو None
def get_user(id: int) -> Optional[str]:
    if id == 1:
        return "أليس"
    return None

# Union: يمكن أن يكون أنواع متعددة
def process(data: Union[str, bytes]) -> str:
    if isinstance(data, bytes):
        return data.decode()
    return data

# بناء جملة بايثون 3.10+ (أنظف)
def process(data: str | bytes) -> str:
    ...

توقيعات الدوال في كود الذكاء الاصطناعي

from typing import List, Dict, Optional, Callable

# اسم مستعار لنوع الرسالة
Message = Dict[str, str]

def chat_completion(
    messages: List[Message],
    model: str = "gpt-4",
    temperature: float = 0.7,
    max_tokens: Optional[int] = None,
    on_token: Optional[Callable[[str], None]] = None
) -> str:
    """توليد إكمال محادثة."""
    ...

# استخدام الأسماء المستعارة للوضوح
ApiResponse = Dict[str, any]
ToolResult = Dict[str, str]

def execute_tool(name: str, args: Dict[str, any]) -> ToolResult:
    ...

فوائد تلميحات الأنواع

الفائدة	الوصف
التوثيق	الكود يشرح نفسه
دعم IDE	إكمال تلقائي واكتشاف أخطاء أفضل
منع الأخطاء	اكتشاف أخطاء الأنواع قبل التشغيل
إعادة الهيكلة	تغييرات كود أكثر أماناً

ملاحظات مهمة

• تلميحات الأنواع اختيارية ولا تؤثر على التشغيل
• بايثون لا تفرض الأنواع (استخدم mypy للفحص)
• ابدأ بسيطاً، أضف التلميحات تدريجياً
• بايثون الحديث (3.9+) يسمح بـ list[str] بدلاً من List[str]

لقد أكملت وحدة هياكل البيانات! بعد ذلك، سنتعلم الدوال والفئات. :::