كيف تعمل تلميحات النوع وما فوائدها؟

Question

Accepted Answer

**تلميحات النوع** (PEP 484+) تتيح لك شرح الأنواع المتوقعة للمتغيرات وparameters الدوال وقيم الإرجاع. إنها **اختيارية** و**غير مفروضة أثناء التشغيل** — Python يتجاهلها عند التشغيل — لكنها تمكّن التحليل الثابت والأدوات الأفضل والكود الأوضح.

## البناء الأساسي

```python
def greet(name: str, times: int = 1) -> str:
    return name * times

age: int = 30
names: list[str] = ["Ann", "Bob"]
scores: dict[str, int] = {"math": 90}
```

تشرح `: type` parameters/المتغيرات و`-> type` الإرجاع. هذه توضح النية وتتحقق منها الأدوات، لكن Python **لا** تفرضها أثناء التشغيل (تمرير نوع خاطئ لن يرفع استثناء من تلقاء نفسه).

## تراكيب typing الشائعة

```python
from typing import Optional, Union, Callable, Any

def find(id: int) -> Optional[str]:    # str OR None (= str | None in 3.10+)
    ...

x: int | str                           # Union (3.10+ syntax)
handler: Callable[[int], bool]         # a function taking int, returning bool
items: list[dict[str, int]]            # nested generics
```

## فحص النوع الثابت يمسك الأخطاء قبل التشغيل

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

add("hello", 3)   # ✅ Python runs it (and crashes); ❌ mypy/pyright flags it BEFORE running
```

أداة فحص نوع مثل **mypy** أو **pyright** تحلل التلميحات وتبلغ عن أخطاء النوع *قبل* تشغيل الكود — مما يمسك فئة كاملة من الأخطاء (أنواع arguments خاطئة، misuse النوع None) مبكراً، مثلما يفعل compiler.

## الفوائد

```text
✓ Catch type bugs early via static checkers (mypy, pyright) — before runtime
✓ IDE support — better autocomplete, refactoring, inline error detection
✓ Self-documenting code — signatures show exactly what's expected/returned
✓ Powers frameworks — FastAPI/Pydantic USE hints for validation & docs
✓ Easier maintenance of large codebases (catch breaking changes)
```

## إنها اختيارية وتدريجية

```text
You can add hints incrementally — a few functions, or strictly everywhere.
Unannotated code still works. "Gradual typing" suits adopting them over time.
```

## الأطر العمل تستخدمها في التشغيل

```python
from pydantic import BaseModel
class User(BaseModel):
    name: str
    age: int            # Pydantic USES the hint to VALIDATE data at runtime
User(name="Ann", age="x")   # raises a validation error
```

بعض المكتبات (Pydantic, FastAPI) تقرأ تلميحات النوع للتحقق من البيانات وإنشاء المستندات — مما يجعلها ذات معنى وظيفي في التشغيل.

## لماذا يهم

تلميحات النوع تجلب العديد من فوائد النوع الثابت إلى Python دون التضحية بمرونتها الديناميكية: تمسك أخطاء type-related مبكراً (عبر mypy/pyright)، تحسّن بشكل كبير أدوات IDE والإعادة، تعمل كتوثيق حي، وتقوي الأطر الحديثة (FastAPI, Pydantic) التي تستخدمها للتحقق والمستندات المولدة تلقائياً.

بينما اختيارية وغير مفروضة في التشغيل من قبل Python نفسها، فقد أصبحت معيار في codebases Python الاحترافية والكبيرة الحجم لأنها تجعل الكود أكثر موثوقية وسهولة صيانة وتوثيق ذاتي — بشكل متزايد ممارسة متوقعة، خاصة مع نمو المشاريع.