Python/collections.abc

تقدّم هذه الوحدة مجموعة من الأصناف الأساسية المجرّدة abstract base calsses (يرمز لها ABC اختصارًا) والتي يمكن استخدامها للتأكد ممّا إذا كان صنف معيّن يقدّم واجهة معينة، كأن يكون الصنف قابلًا للتقطيع hashable أو أنّه صنف ربط mapping.

ملاحظة: قبل الإصدار 3.3 من اللغة كانت هذه الوحدة جزءًا من وحدة collections.

الأصناف الأساسية المجرّدة في الوحدة collections تقدّم وحدة collections الأصناف الأساسية المجرّدة التالية:

class collections.abc.Container class collections.abc.Hashable class collections.abc.Sized class collections.abc.Callable أصناف أساسية مجرّدة للأصناف التي تقدّم التوابع ‎__contains__()‎، ‎__hash__()‎، ‎__len__()‎ و ‎__call__()‎.

class collections.abc.Iterable صنف أساسي مجرّد للأصناف التي تقدّم التابع ‎__iter__()‎.

تؤدي عملية التحقّق بواسطة الدالة isinstance(obj, iterable)‎ إلى الكشف عن الأصناف المسجّلة على أنّها صنف Iterable الأساسي المجرّد أو أنّها تمتلك التابع ‎__iter__()‎، ولكنّها لا تكتشف الأاصناف التي تجري عملية التكرار بواسطة التابع ‎__getitem__()‎. الطريقة الوحيدة لتحديد ما إذا كان الكائن قابلًا للتكرار هي استدعاء الدالة iter(obj)‎.

class collections.abc.Collection صنف أساسي مجرّد لأصناف الحاويات التكرارية المحجّمة. ملاحظة: هذا الصنف جديد في الإصدار 3.6 من بايثون.

class collections.abc.Iterator صنف أساسي مجرّد للأصناف التي تقدّم التابعين ‎__iter__()‎ و __next__()‎.

class collections.abc.Reversible صنف أساسي مجرّد للأصناف التكرارية التي تقدّم التابع ‎__reversed__()‎. ملاحظة: هذا الصنف جديد في الإصدار 3.6 من بايثون.

class collections.abc.Generator صنف أساسي مجرّد لإنشاء أصناف تستخدم البروتوكول المعرّف في PEP 342 والذي يضيف التوابع send()‎ و throw()‎ و close()‎ إلى المكرِّرات.

ملاحظة: هذا الصنف جديد في الإصدار 3.5 من بايثون.

class collections.abc.Sequence class collections.abc.MutableSequence class collections.abc.ByteString صنف أساسي مجرّد للتسلسلات التي تكون قابلة للتعديل mutable وللقراءة فقط read-only.

ملاحظة: بعض توابع mixin مثل ‎__iter__()‎ و ‎__reversed__()‎ و index()‎ تجري استدعاءات متكرّرة للتابع الضمني ‎__getitem__()‎. ونتيجة لذلك، إن كان التابع ‎__getitem__()‎ مُستخدمًا بسرعة وصول ثابتة، فإنّ أداء توابع mixin سيكون خطّيًا، ولكن إن كان التابع الضمني خطّيًا (كما هو الحال مع قائمة مرتبطة) فإنّ أداء توابع mixin سيكون تربيعيًا وهنا تظهر الحاجة إلى إعادة تعريفها. ملاحظة: في الإصدار 3.5 أضيف المعاملان stop و start إلى التابع index()‎.

class collections.abc.Set class collections.abc.MutableSet صنف أساسي مجرّد للمجموعات القابلة للتعديل والتي تكون للقراءة فقط.

class collections.abc.Mapping class collections.abc.MutableMapping صنف أساسي مجرّد للمجموعات لكائنات الربط القابلة للتعديل والتي تكون للقراءة فقط.

class collections.abc.MappingView class collections.abc.ItemsView class collections.abc.KeysView class collections.abc.ValuesView أصناف أساسية مجرّد لعروض كائنات الربط والعناصر items والمفاتيح keys والقيم values.

class collections.abc.Awaitable صنف أساسي مجرّد لكائنات awaitable، والتي يمكن استخدامها في تعابير await. يجب أن يقدّم الاستخدام المخصّص لهذا الصنف التابع ‎__await__‎()‎. كائنات Coroutine و نسخ الصنف الأساسي المجرّد Couroutine هي كلّها نسخ من هذا الصنف الأساسي المجرّد.

ملاحظة: تكون الـ coroutines المستندة على المولدات في CPython (المولّدات المزخرفة بواسطة التابع types.coroutine()‎ أو asyncio.coroutine()‎) من نوع awaitable على الرغم من عدم احتوائها على التابع ‎__await__()‎. تعيد الدالة isinstance(gencoro, Awaitable)‎ القيمة False، ويجب استخدام التابع Useinspect.isawaitable()‎ للكشف عنها.

ملاحظة: هذا الصنف جديد في الإصدار 3.5 من بايثون.

class collections.abc.Coroutine

صنف أساسي مجرّد للأصناف المتوافقة مع الـ coroutine. تستخدم هذه الأصناف التوابع send()‎ و throw()‎ و close()‎ والمعرّفة في كائنات Coroutine. إلى جانب ذلك يجب أن يتضمّن الاستخدام المخصّص لهذا الصنف الأساسي المجرد تضمين التابع ‎__await__()‎. جميع نسخ الصنف Coroutine هي نسخ للصنف Awaitable أيضًا.

ملاحظة: تكون الـ coroutines المستندة على المولدات في CPython (المولّدات المزخرفة بواسطة التابع types.coroutine()‎ أو asyncio.coroutine()‎) من نوع awaitable على الرغم من عدم احتوائها على التابع ‎__await__()‎. تعيد الدالة isinstance(gencoro, Coroutine)‎ القيمة False، ويجب استخدام التابع Useinspect.isawaitable()‎ للكشف عنها.

ملاحظة: هذا الصنف جديد في الإصدار 3.5 من بايثون.

class collections.abc.AsyncIterable صنف أساسي مجرّد للأصناف التي تقدّم التابع ‎__aiter__‎. ملاحظة: هذا الصنف جديد في الإصدار 3.5 من بايثون.

class collections.abc.AsyncIterator صنف أساسي مجرّد للأصناف التي تقدّم التابعين ‎__aiter__‎ و ‎__anext__‎. ملاحظة: هذا الصنف جديد في الإصدار 3.5 من بايثون.

class collections.abc.AsyncGenerator صنف أساسي مجرّد للأصناف المولّدة غير المتزامنة asynchronous generator classes والتي تعتمد البروتوكول المعرف في PEP 525 و PEP 492.

ملاحظة: هذا الصنف جديد في الإصدار 3.6 من بايثون.

تتيح هذه الأصناف الأساسية المجرّد معرفةما إذا كانت الأصناف أو النسخ تقدّم وظيفة معيّنة، فعلى سبيل المثال:

size = None if isinstance(myvar, collections.abc.Sized):

   size = len(myvar)

هناك عدد من الأصناف الأساسية المجرّدة التي يمكن الاستفادة منها كـ mixin تسهّل عملية تطوير أصناف تدعم الواجهات البرمجية الخاصة بالصنف الحاوي.

فمثلًا، لكتابة صنف يدعم الواجهة البرمجية الكامل للصنف الأساسي المجرد Set، يكفي تزويد الصنف بالتوابع الضمنية المجرّدة التالية: ‎__contains__()‎ و ‎__iter__()‎ و ‎__len__()‎، ويزوّد الصنف الأساسي المجرد بقية التوابع مثل ‎‎__and__‎()‎ و isdisjoint()‎:

class ListBasedSet(collections.abc.Set):

    Alternate set implementation favoring space over speed
       and not requiring the set elements to be hashable. 
   def __init__(self, iterable):
       self.elements = lst = []
       for value in iterable:
           if value not in lst:
               lst.append(value)

   def __iter__(self):
       return iter(self.elements)

   def __contains__(self, value):
       return value in self.elements

   def __len__(self):
       return len(self.elements)

s1 = ListBasedSet('abcdef') s2 = ListBasedSet('defghi') overlap = s1 & s2 # مدعوم تلقائيًا ‎__and__()‎ التابع

ملاحظات على استخدام Set و MutableSet كـ mixin:

1- لمّا كانت بعض عمليات المجموعات تنشئ مجموعات جديدة فإنّ توابع mixin الافتراضية تكون بحاجة إلى غنشاء نسخ جديدة من المكرِّر. ويُفترض أن تتضمّن الدالة البانية للصنف توقيعًا بالصيغة form ClassName(iterable)‎.

يجري تحليل ذلك الافتراض إلى تابع صنف داخلي يدعى ‎_from_iterable()‎ والذي يستدعي الدالة cls(iterable)‎ لإنشاء مجموعة جديدة. إن استخدم Set mixin في صنف ذي توقع مختلف في دالته البانية، فيجب إعادة تعريف override التابع ‎_from_iterable()‎ بتابع صنف يمكنه بناء نسخ جديد من معامل مكرِّر iterable argument.

2- لإعادة تعريف عمليات المقارنة (لأغراض السرعة على الأرجح وذلك لأنّها عمليات ثابتة) يجب إعادة تعريف التابعين ‎__le__‎()‎ و ‎__ge__()‎ وستتبع بقية العمليات هذين التابعين بصورة تلقائية. 3- يقدّم Set mixin تابع ‎_hash()‎ لحساب قيمة hash للمجموعة، ولكن لا يجري تعريف التابع ‎__hash__()‎ لأنّ جميع المجموعات تكون قابلة للتقطيع hashable أو غير قابلة للتعديل immutable. ولإضافة قابلية التقطيع باستخدام mixins، يمكن الوراثة من الصنفين Set()‎ و Hashable()‎ ثم تعريف القيمة ‎__hash__ ‎ = Set._hash.