type hints و dataclasses

Type Hints و dataclasses

تلميحات الأنواع (Type Hints) وصفت بها Python عام 2015 (PEP 484) طريقة لتوثيق الأنواع المتوقعة مباشرةً في الكود. لا تُنفَّذ عند التشغيل — Python تتجاهلها — لكنها تُساعد أدوات مثل mypy وPyCharm في اكتشاف الأخطاء قبل التشغيل. و@dataclass هو مُزخرف يُولّد كوداً متكرراً لك.

التلميحات الأساسية — Basic Type Hints

main.go

# دالة بدون تلميحات — Function without hints
def add(a, b):
    return a + b

# دالة مع تلميحات — Function with type hints
def add_typed(a: int, b: int) -> int:
    return a + b

# التلميحات لا تمنع استدعاء خاطئ — Hints don't prevent wrong calls
print(add_typed(3, 4))        # 7 — صحيح
print(add_typed(3.5, 1.5))    # 5.0 — Python لا تُوقف هذا!

# تلميحات للمتغيرات — Variable annotations
name: str = "أحمد"
age: int = 25
score: float = 9.5
active: bool = True

# يمكن التعريف بدون قيمة أولية — Can annotate without initial value
future_value: int  # لم تُسنَد بعد — not yet assigned

print(f"{name}، العمر {age}، النقاط {score}")

Output:

التلميحات وثيقة حية في الكود — أوضح بكثير من تعليق منفصل مثل # a هو int.

`Optional` — القيم الاختيارية

main.go

from typing import Optional


def find_user(user_id: int) -> Optional[str]:
    """يُرجع اسم المستخدم أو None — Returns user name or None."""
    users = {1: "أحمد", 2: "فاطمة", 3: "عمر"}
    return users.get(user_id)  # قد يُرجع None — might return None


# Optional[str] == str | None في Python 3.10+
result = find_user(1)
if result is not None:
    print(f"وُجد المستخدم: {result}")

missing = find_user(99)
print(f"غير موجود: {missing}")


# معامل اختياري — Optional parameter
def greet(name: str, title: Optional[str] = None) -> str:
    if title:
        return f"أهلاً، {title} {name}"
    return f"أهلاً، {name}"


print(greet("محمد"))
print(greet("سارة", "د."))

Output:

Optional[X] يعني أن القيمة إما X أو None. استخدمه دائماً عندما يمكن للدالة أن تُرجع None.

`List`، `Dict`، `Tuple`، `Set`

main.go

from typing import List, Dict, Tuple, Set


def process_scores(scores: List[int]) -> Dict[str, float]:
    """يعالج قائمة نقاط ويُرجع إحصاءات — Processes scores and returns stats."""
    if not scores:
        return {"min": 0.0, "max": 0.0, "avg": 0.0}
    return {
        "min": float(min(scores)),
        "max": float(max(scores)),
        "avg": sum(scores) / len(scores),
    }


def parse_coordinate(text: str) -> Tuple[float, float]:
    """يُحوّل نص إلى إحداثيات — Converts text to coordinates."""
    lat, lon = text.split(",")
    return float(lat.strip()), float(lon.strip())


def unique_tags(tag_lists: List[List[str]]) -> Set[str]:
    """يجمع وسوماً فريدة من قوائم متعددة — Collects unique tags from multiple lists."""
    result: Set[str] = set()
    for tags in tag_lists:
        result.update(tags)
    return result


scores = [85, 92, 78, 95, 88]
stats = process_scores(scores)
print(f"أدنى: {stats['min']}, أعلى: {stats['max']}, معدل: {stats['avg']:.1f}")

lat, lon = parse_coordinate("24.6877, 46.7219")
print(f"الرياض: {lat}°N, {lon}°E")

tags = unique_tags([["Python", "برمجة"], ["Python", "AI"], ["Go", "برمجة"]])
print(f"وسوم فريدة: {sorted(tags)}")

Output:

`Union` — أنواع متعددة

main.go

from typing import Union


def parse_number(value: Union[str, int, float]) -> float:
    """يُحوّل نص أو رقم إلى float — Converts string or number to float."""
    if isinstance(value, str):
        return float(value.replace(",", ""))  # "1,234" -> 1234.0
    return float(value)


print(parse_number("1,234.56"))  # 1234.56
print(parse_number(42))          # 42.0
print(parse_number(3.14))        # 3.14


# في Python 3.10+ يمكنك كتابة str | int بدلاً من Union[str, int]
# In Python 3.10+ you can write str | int instead of Union[str, int]
def describe(value: Union[int, str, list]) -> str:
    if isinstance(value, int):
        return f"رقم: {value}"
    if isinstance(value, str):
        return f"نص: '{value}'"
    return f"قائمة بـ {len(value)} عنصر"


print(describe(42))
print(describe("مرحبا"))
print(describe([1, 2, 3]))

Output:

`@dataclass` — فئات البيانات

كتابة فئة بسيطة لتخزين بيانات تتطلب كوداً متكرراً: __init__، __repr__، __eq__. @dataclass يُولّد كل ذلك تلقائياً.

main.go

# الطريقة اليدوية — Manual way (متكرر ومؤلم — repetitive and painful)
class ProductManual:
    def __init__(self, name: str, price: float, quantity: int):
        self.name = name
        self.price = price
        self.quantity = quantity

    def __repr__(self):
        return f"Product(name={self.name!r}, price={self.price}, quantity={self.quantity})"

    def __eq__(self, other):
        if not isinstance(other, ProductManual):
            return NotImplemented
        return (self.name, self.price, self.quantity) == (other.name, other.price, other.quantity)


# مع @dataclass — With @dataclass (الكود نفسه بأسطر أقل بكثير — same result, much less code)
from dataclasses import dataclass


@dataclass
class Product:
    name: str           # حقل نصي — string field
    price: float        # حقل عشري — float field
    quantity: int       # حقل صحيح — integer field


# @dataclass يُولّد __init__ و__repr__ و__eq__ تلقائياً
p1 = Product("تفاح", 5.50, 100)
p2 = Product("تفاح", 5.50, 100)
p3 = Product("موز", 3.00, 50)

print(p1)            # __repr__ جاهز — __repr__ ready
print(p1 == p2)      # __eq__ جاهز — __eq__ ready (True)
print(p1 == p3)      # False

Output:

`@dataclass` — الميزات المتقدمة

main.go

from dataclasses import dataclass, field
from typing import List, Optional


@dataclass
class Address:
    city: str
    country: str = "السعودية"  # قيمة افتراضية — default value


@dataclass
class Customer:
    name: str
    email: str
    address: Address
    orders: List[str] = field(default_factory=list)  # قائمة فارغة لكل كائن — empty list per instance
    vip: bool = False

    # يمكن إضافة دوال عادية — Can add regular methods
    def place_order(self, order_id: str) -> None:
        self.orders.append(order_id)
        print(f"طُلب {order_id} لـ {self.name}")

    @property
    def order_count(self) -> int:
        return len(self.orders)


# إنشاء كائنات — Create instances
addr = Address(city="الرياض")
customer = Customer(
    name="أحمد العمري",
    email="ahmed@example.com",
    address=addr,
    vip=True,
)

print(customer)
customer.place_order("ORD-001")
customer.place_order("ORD-002")
print(f"عدد الطلبات: {customer.order_count}")
print(f"VIP: {customer.vip}")

Output:

field(default_factory=list) ضروري للحقول القابلة للتغيير (lists, dicts) — لا تستخدم orders: List[str] = [] مباشرةً لأن القائمة ستُشارَك بين جميع الكائنات.

`frozen=True` — كائنات غير قابلة للتعديل

main.go

from dataclasses import dataclass


@dataclass(frozen=True)  # لا يمكن تعديل الحقول بعد الإنشاء — fields immutable after creation
class Point:
    x: float
    y: float

    def distance_from_origin(self) -> float:
        return (self.x ** 2 + self.y ** 2) ** 0.5


p = Point(3.0, 4.0)
print(p)
print(f"المسافة: {p.distance_from_origin()}")

# p.x = 10  # FrozenInstanceError — غير مسموح
# يمكن استخدامها كمفتاح في dict لأنها hashable — Can use as dict key (hashable)
distances = {p: p.distance_from_origin()}
print(f"القاموس: {distances}")

Output:

mypy — فحص الأنواع

التلميحات لا تُنفَّذ عند التشغيل. mypy هو أداة مستقلة تفحص الأنواع قبل التشغيل:

pip install mypy
mypy your_script.py

سيكتشف mypy أخطاء مثل:

تمرير str حيث تُتوقع int
استخدام قيمة Optional دون التحقق من None
نسيان return في دالة تُرجع قيمة

تحدي — Challenge

from dataclasses import dataclass
from typing import List


# عرّف @dataclass للمنتج — Define @dataclass for Product
# الحقول: name (str)، price (float)، stock (int)، category (str)


# أضف دالة total_value تُرجع price * stock — Add total_value method


products: List  # أكمل النوع — complete the type

products = [
    # أنشئ منتجَين — create two products
]

for p in products:
    print(p)

total = sum(p.total_value() for p in products)
print(f"إجمالي قيمة المخزون: {total:.2f}")

type hints و dataclasses