أساليب dunder الخاصة

أساليب dunder الخاصة — Special (Dunder) Methods

عندما تكتب len([1, 2, 3]) أو "a" + "b" أو print(obj) — Python في الحقيقة تستدعي أساليب خاصة في الخلفية. هذه الأساليب تُسمى dunder methods (اختصار Double Underscore) لأن اسمها يبدأ وينتهي بشرطتين سفليتين مزدوجتين: __str__, __add__, __eq__.

يمكنك تعريف هذه الأساليب في كلاساتك لتجعل كائناتك تستجيب لعمليات Python القياسية مثل الطباعة والمقارنة والجمع والتكرار.

لماذا dunder Methods؟

nums = [10, 20, 30]
print(len(nums))   # يستدعي nums.__len__()
print(nums[0])     # يستدعي nums.__getitem__(0)
nums2 = nums + [40]  # يستدعي nums.__add__([40])

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

`str` و`repr`

الفرق: __str__ للعرض للمستخدم، __repr__ للمطوّر والتصحيح.

main.go

class Book:
    def __init__(self, title, author, pages):
        self.title = title
        self.author = author
        self.pages = pages

    def __str__(self):
        # ما يراه المستخدم — User-facing representation
        return f"«{self.title}» — {self.author}"

    def __repr__(self):
        # ما يراه المطوّر في التصحيح — Developer/debug representation
        return f"Book(title={self.title!r}, author={self.author!r}, pages={self.pages})"


b = Book("البرمجة بـ Python", "عزيز محمد", 350)

# print يستدعي __str__ — print calls __str__
print(b)

# repr() يستدعي __repr__ — repr() calls __repr__
print(repr(b))

# في القوائم Python يستخدم __repr__ — In lists Python uses __repr__
books = [b, Book("تعلم Go", "سارة أحمد", 280)]
print(books)

Output:

متى تستخدم أيهما؟

__str__: لما يظهر للمستخدم — رسالة واضحة وجميلة.
__repr__: لما تريده في السجلات والتصحيح — دقيق ومحدد، يُفضَّل أن يكون valid Python يمكن تنفيذه لإعادة إنشاء الكائن.
إذا لم تُعرّف __str__، يرجع Python لـ__repr__. لذا ابدأ دائماً بـ__repr__ إذا كانت الأولوية للتصحيح.

`eq` — المقارنة بالمساواة

بدون __eq__، مقارنة كائنين دائماً False حتى لو حقولهما متطابقة (لأن Python يقارن الهوية في الذاكرة لا القيمة).

main.go

class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __eq__(self, other):
        # التحقق من النوع أولاً — Check type first
        if not isinstance(other, Point):
            return NotImplemented
        return self.x == other.x and self.y == other.y

    def __repr__(self):
        return f"Point({self.x}, {self.y})"


p1 = Point(3, 4)
p2 = Point(3, 4)
p3 = Point(1, 2)

print(p1 == p2)  # True — نفس القيم
print(p1 == p3)  # False — قيم مختلفة
print(p1 == "ليس نقطة")  # False — نوع مختلف

# قبل __eq__، هذا كان سيطبع False
# (Python كان يقارن عناوين الذاكرة)

Output:

NotImplemented (ليس None) قيمة خاصة تخبر Python أن هذه الكلاس لا تعرف كيف تقارن بالنوع الآخر، فيحاول Python الجهة الأخرى.

`len` — طول الكائن

main.go

class Classroom:
    def __init__(self, name):
        self.name = name
        self.students = []  # قائمة الطلاب — Student list

    def add_student(self, name):
        self.students.append(name)

    def __len__(self):
        # عدد الطلاب — Number of students
        return len(self.students)

    def __repr__(self):
        return f"Classroom({self.name!r}, {len(self)} students)"


room = Classroom("الفصل الأول")
room.add_student("أحمد")
room.add_student("نورة")
room.add_student("خالد")

print(len(room))    # 3 — يستدعي __len__
print(bool(room))   # True — كائن بطول > 0 يعتبر True
print(repr(room))

empty_room = Classroom("فصل فارغ")
print(len(empty_room))   # 0
print(bool(empty_room))  # False — طول صفر يعني False

Output:

بمجرد تعريف __len__، يعمل bool() تلقائياً: الكائن True إذا كان طوله أكبر من صفر، وFalse إذا كان صفراً.

`add` — عامل الجمع

main.go

class Vector:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __add__(self, other):
        # جمع متجهين — Add two vectors
        if not isinstance(other, Vector):
            return NotImplemented
        return Vector(self.x + other.x, self.y + other.y)

    def __mul__(self, scalar):
        # ضرب المتجه بثابت — Scalar multiplication
        return Vector(self.x * scalar, self.y * scalar)

    def __rmul__(self, scalar):
        # ضرب من اليمين: 3 * v — Right multiplication: 3 * v
        return self.__mul__(scalar)

    def magnitude(self):
        # حجم المتجه — Vector magnitude
        return (self.x ** 2 + self.y ** 2) ** 0.5

    def __repr__(self):
        return f"Vector({self.x}, {self.y})"


v1 = Vector(1, 2)
v2 = Vector(3, 4)

print(v1 + v2)           # Vector(4, 6)
print(v1 * 3)            # Vector(3, 6) — يستدعي __mul__
print(3 * v1)            # Vector(3, 6) — يستدعي __rmul__
print((v1 + v2).magnitude())  # 7.21

Output:

__rmul__ يُستدعى عندما Python لا يعرف كيف يُنجز 3 * v1 من جهة العدد — يجرب الجانب الأيمن بدلاً من ذلك.

`iter` — جعل الكائن قابلاً للتكرار

main.go

class Countdown:
    def __init__(self, start):
        self.start = start

    def __iter__(self):
        # إرجاع iterator — Return iterator
        current = self.start
        while current >= 0:
            yield current   # yield يحوّل الأسلوب لـ generator
            current -= 1

    def __repr__(self):
        return f"Countdown(from={self.start})"


cd = Countdown(5)

# يعمل مع for مباشرة — Works directly with for
for n in cd:
    print(n, end=" ")
print()

# يعمل مع list() — Works with list()
print(list(Countdown(3)))

# يعمل مع sum() — Works with sum()
print("المجموع:", sum(Countdown(10)))

Output:

yield داخل __iter__ يُحوّله إلى generator تلقائياً — أبسط من كتابة __iter__ و__next__ منفصلَين.

جمع dunder Methods في كلاس واحد

main.go

class ShoppingCart:
    def __init__(self):
        self.items = []  # قائمة (اسم، سعر) — List of (name, price)

    def add(self, name, price):
        self.items.append((name, price))

    def __len__(self):
        # عدد العناصر — Number of items
        return len(self.items)

    def __str__(self):
        if not self.items:
            return "السلة فارغة"
        lines = [f"  - {name}: {price:.2f} ر.س" for name, price in self.items]
        total = sum(p for _, p in self.items)
        lines.append(f"  الإجمالي: {total:.2f} ر.س")
        return "سلة التسوق:\n" + "\n".join(lines)

    def __repr__(self):
        return f"ShoppingCart({len(self)} items)"

    def __add__(self, other):
        # دمج سلتين — Merge two carts
        if not isinstance(other, ShoppingCart):
            return NotImplemented
        merged = ShoppingCart()
        merged.items = self.items + other.items
        return merged

    def __iter__(self):
        # التكرار على العناصر — Iterate over items
        return iter(self.items)


cart1 = ShoppingCart()
cart1.add("كتاب Python", 49.99)
cart1.add("قلم حبر", 5.50)

cart2 = ShoppingCart()
cart2.add("دفتر", 12.00)

print(cart1)
print(f"عدد العناصر: {len(cart1)}")

merged = cart1 + cart2
print("\nبعد الدمج:")
print(merged)

# التكرار المباشر — Direct iteration
for name, price in cart1:
    print(f"  {name}: {price}")

Output:

جدول مرجعي سريع

أسلوب dunder	متى يُستدعى	مثال
`__str__`	`print(obj)`, `str(obj)`	عرض لطيف للمستخدم
`__repr__`	`repr(obj)`, في القوائم	تمثيل تقني دقيق
`__eq__`	`obj1 == obj2`	مقارنة بالقيمة
`__len__`	`len(obj)`, `bool(obj)`	حجم/طول الكائن
`__add__`	`obj1 + obj2`	عملية الجمع
`__mul__`	`obj * n`	عملية الضرب
`__iter__`	`for x in obj`, `list(obj)`	التكرار
`__contains__`	`item in obj`	اختبار الاحتواء
`__getitem__`	`obj[key]`	الفهرسة

تحدي — Challenge

class Vector:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __add__(self, other):
        # أكمل الجمع — complete addition
        pass

    def __str__(self):
        # أكمل التمثيل النصي — complete string representation
        # المطلوب: "Vector(x, y)"
        pass


v1 = Vector(2, 3)
v2 = Vector(3, 4)
result = v1 + v2
print(f"مجموع النقاط: {result}")

أساليب dunder الخاصة