collections --- أنواع المجموعات والحاويات

توفر هذه الوحدة أنواع بيانات حاوية متخصصة تكمّل الأنواع المدمجة list و tuple و dict و set: طابور مزدوج الطرفين (deque)، ومصنع لإنشاء صفوف ذات حقول مسماة (namedtuple())، وقاموس يحافظ على ترتيب العناصر (OrderedDict).

الأصناف

class collections.deque(iterable: Iterable, maxlen: int, flags: int = 0)

الطوابير المزدوجة (deques) هي حاوية شبيهة بالقائمة تدعم عمليات الإضافة والإزالة من أي من طرفيها بزمن O(1). تُنشأ الطوابير الجديدة باستخدام المعطيات التالية:

• iterable هو كائن قابل للتكرار يُستخدم لملء الطابور عند إنشائه. يمكن أن يكون صفاً أو قائمة فارغة لإنشاء طابور يبدأ فارغاً.

• يجب تحديد maxlen، وسيكون الطابور محدوداً بهذا الطول الأقصى. وبمجرد امتلاء الطابور، فإن أي عناصر جديدة تُضاف ستتسبب في التخلص من عناصر من الطرف المقابل.

• يمكن أن تكون قيمة flags الاختيارية 1 للتحقق من تجاوز السعة عند إضافة العناصر.

تدعم كائنات الطابور bool و len() والتكرار وقراءة وتخزين العناصر عبر الفهرسة. كما أن لها الطرائق التالية:

append(x: Any) → None

تضيف x إلى الجانب الأيمن من الطابور. تُطلق IndexError إذا كان التحقق من تجاوز السعة مفعّلاً ولم يبقَ مكان في الطابور.

appendleft(x: Any) → None

تضيف x إلى الجانب الأيسر من الطابور. تُطلق IndexError إذا كان التحقق من تجاوز السعة مفعّلاً ولم يبقَ مكان في الطابور.

pop() → Any

تزيل وتُرجع عنصراً من الجانب الأيمن من الطابور. تُطلق IndexError إذا لم تكن هناك عناصر.

popleft() → Any

تزيل وتُرجع عنصراً من الجانب الأيسر من الطابور. تُطلق IndexError إذا لم تكن هناك عناصر.

extend(iterable: Iterable) → None

توسّع الطابور بإلحاق جميع العناصر من iterable إلى الجانب الأيمن منه. تُطلق IndexError إذا كان التحقق من تجاوز السعة مفعّلاً ولم يبقَ مكان في الطابور.

collections.namedtuple(name: str, fields: str | Sequence[str]) → type

هذه دالة مصنع لإنشاء نوع namedtuple جديد باسم محدد ومجموعة من الحقول. إن namedtuple هو صنف فرعي من tuple يتيح الوصول إلى حقوله ليس فقط عبر الفهرس الرقمي، بل أيضاً عبر صياغة الوصول إلى السمات باستخدام أسماء حقول رمزية. الحقول هي تسلسل من السلاسل النصية يحدد أسماء الحقول. وللتوافق مع CPython يمكن أن تكون أيضاً سلسلة نصية تحتوي على أسماء حقول مفصولة بمسافات (لكن هذا أقل كفاءة). مثال على الاستخدام:

from collections import namedtuple

MyTuple = namedtuple("MyTuple", ("id", "name"))
t1 = MyTuple(1, "foo")
t2 = MyTuple(2, "bar")
print(t1.name)
assert t2.name == t2[1]

توفر النسخ أيضاً الطريقة التالية:

collections._asdict() → OrderedDict

تُرجع أسماء الحقول وقيمها على شكل OrderedDict.

class collections.OrderedDict(*args: Any, **kwargs: Any)

صنف فرعي من نوع dict يتذكر ويحافظ على ترتيب المفاتيح المضافة. يقبل نفس صيغ المُنشئ التي يقبلها dict (كائن قابل للتكرار من أزواج (key, value)، أو خريطة أخرى، أو وسائط مفتاحية). عند التكرار على القاموس المرتب، تُرجع المفاتيح/العناصر بالترتيب الذي أُضيفت به:

from collections import OrderedDict

# To make benefit of ordered keys, OrderedDict should be initialized
# from sequence of (key, value) pairs.
d = OrderedDict([("z", 1), ("a", 2)])
# More items can be added as usual
d["w"] = 5
d["b"] = 3
for k, v in d.items():
    print(k, v)

الخرج:

z 1
a 2
w 5
b 3

popitem() → Tuple

تزيل وتُرجع زوج (key, value) من القاموس. تُرجع الأزواج بترتيب LIFO (آخر داخل، أول خارج).

الفرق عن CPython

إن OrderedDict.popitem() لا يدعم الوسيط last=False وسيزيل ويُرجع دائماً آخر عنصر إن وُجد.

أحد الحلول البديلة لهذا هو استخدام pop(<first_key>) لإزالة العنصر الأول:

first_key = next(iter(d))
d.pop(first_key)