Python/types

تقدّم هذه الوحدة عددًا من الدوال المساعدة لإنشاء أنواع بيانات جديدة بصورة ديناميكية، إضافة إلى أنّها تعرّف أسماءً لبعض أنواع الكائنات التي يستخدمها مفسّر بايثون المعياري، ولكنّها ليست كائنات داخلية مثل int أو str، إلى جانب أنّ هذه الوحدة تقدم بعض الأصناف والدوال المساعدة الخاصة ببعض الأنواع، والتي لا تعدّ أساسية بما يكفي لتصبح أصنافًا ودوالّ داخلية.

إنشاء الأنواع ديناميكيًا

تقدّم هذه الوحدة ثلاث دوالّ تساعد في إنشاء أنواع البيانات ديناميكيًا:

الدالة types.new_class()‎‎

تنشئ هذه الدالة ديناميكيًا كائن صنف باستخدام صنف ميتا (metaclass) المناسب.

الدالة types.prepare_class()‎‎

تحسب هذه الدالة صنف ميتا المناسب وتنشئ نطاق الأسماء.

الدالة types.reslove_bases()‎‎

تحلّل الدالة مدخلات (ترتيب تحليل التوابع MRO) بصورة ديناميكية وكما هو محدّد في PEP 560.

الأنواع الخاصة بالمفسّر المعياري لبايثون

تقدّم هذه الوحدة أسماء للكثير من الأنواع التي تكون مطلوبة لاستخدام مفسّر بايثون. يتجنّب مفسّر بايثون تضمين بعض الأنواع التي تظهر فقط أثناء عمليات المعالجة مثل النوع listiterator.

تستخدم هذه الأسماء عادة من قبل دوال التحقّق isinstance()‎ و issubclass()‎.

تعرّف الأسماء المعيارية للأنواع التالية:

النوع types.LambdaType

النوع الخاص بالدوال المعرّفة من قبل المستخدمة والدوال التي تنشأ من تعابير lambda.

النوع types.GeneratorType

النوع الخاص بكائنات المولدات-المكرّرات، والتي تنشأ من دوال المولّدات.

النوع types.CoroutineType

النوع الخاص بكائنات corotuine، والتي تنشأ من دوال async def.

ملاحظة: جديد في الإصدار 3.5.

النوع types.AsyncGeneratorType

النوع الخاص بكائنات المولدات-المكرّرات غير المتزامنة، والتي تنشأ من دوال المولّدات غير المتزامنة. ملاحظة: جديد في الإصدار 3.6.

النوع types.CodeType

النوع الخاص بكائنات code كتلك التي تعيدها الدالة compile()‎.

النوع types.MethodType

النوع الخاص بالتوابع الخاصّة بنسخ الأصناف المعرّفة من قبل المستخدم.

النوع types.BuiltinMethodType

النوع الخاص بالدوال الداخلية مثل len()‎ أو sys.exit()‎، والتوابع الخاصة بالأصناف الداخلية. (المقصود بكلمة "الداخلية" هنا أنّها مكتوبة بلغة C).

النوع types.WrapperDescriptorType

النوع الخاص بالتوابع الخاصة ببعض أنواع البيانات الداخلية والأصناف الأساسية مثل object.__init__()‎ أو object.__lt__()‎.

ملاحظة: جديد في الإصدار 3.7.

النوع types.MethodWrapperType

النوع الخاص بالتوابع المرتبطة bound methods الخاصّة ببعض أنواع البيانات الداخلية والأصناف الأساسية، مثل object().__str__‎.

ملاحظة: جديد في الإصدار 3.7.

النوع types.MethodDescriptorType

النوع الخاص بالتوابع الخاصّة ببعض أنواع البيانات الداخلية مثل str.join()‎.

ملاحظة: جديد في الإصدار 3.7.

النوع types.ClassMethodDescriptorType

النوع الخاص بتوابع الأصناف غير المرتبطة الخاصّة ببعض أنواع البيانات الداخلية مثل asdict.__dict__['fromkeys']‎.

ملاحظة: جديد في الإصدار 3.7.

الصنف types.ModuleType(name, doc=None)‎

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

ملاحظة: استخدم importlib.util.module_from_spec()‎ لإنشاء وحدة جديدة إن كنت ترغب في تعين الخصائص المتعدّدة التي يجري التحكم بها عند استيراد الوحدة.

__doc__

سلسلة التوثيق النصية الخاصّة بالوحدة. القيمة الافتراضية هي None.

__loader__

المحمِّل الذي حمّل الوحدة. القيمة الافتراضية هي None.

ملاحظة: في الإصدار 3.4 تأخذ الخاصية القيمة الافتراضية None. أما في السابق فقد كانت الخاصّية اختيارية.

__name__

اسم الوحدة.

__package__

الحزمة التي تنتمي إليها الوحدة. إن كانت الوحدة من المستوى العالي (أي أنّها لا تنتمي لحزمة معيّنة) فيجب حينئذ تعيين القيمة لهذه الخاصية، وإلا يجب تعيين اسم الحزمة (والذي يمكن أن يكون __name__ إن كانت الوحدة هي الحزمة ذاتها). تأخذ هذه الخاصية القيمة الافتراضية None.

ملاحظة: في الإصدار 3.4 تأخذ الخاصية القيمة الافتراضية None. أما في السابق فقد كانت الخاصّية اختيارية.

الصنف ‎types.TracebackType(tb_next, tb_frame, tb_lasti, tb_lineno)‎

النوع الخاص بكائنات traceback مثل الموجود في sys.exc_info()‎[2]‎.

راجع دليل اللغة للحصول على المزيد من التفاصيل حول الخصائص والعمليات المتوفرة، والاطلاع على كيفية إنشاء كائنات traceback ديناميكيًا.

النوع types.FrameType

النوع الخاص بكائنات frame كتلك الموجودة في tb.tb_frame إن كانت tb كائن traceback.

راجع دليل اللغة للحصول على المزيد من التفاصيل حول الخصائص والعمليات المتوفرة.

النوع types.GetSetDescriptorType

النوع الخاص بالكائنات المعرّفة في الوحدات الملحقة مع PyGetSetDef، مثل FrameType.f_locales أو array.array.typecode. يستخدم هذا النوع كواصف descriptor لخصائص الكائن، وهو يؤدي وظفية نوع الخاصية ذاتها، ولكن في الأصناف المعرّفة في الوحدات الملحقة.

النوع types.MemberDescriptorType

النوع الخاص بالكائنات المعرّفة في الوحدات الملحقة مع PyMemberDef، مثل datetime.timedelta.days. يستخدم هذا النوع كواصف لعناصر بيانات C البسيطة والتي تستخدم دوال تحويل معيارية، وتؤدي وظيفة نوع الخاصية ولكن في الأصناف المعرّفة في الوحدات الملحقة.

ملاحظة في CPython: في طرق الاستخدام الأخرى لبايثون، يمكن لهذا النوع أن يصبح مماثلًا للنوع GetSetDescriptorType.

الصنف types.MappingProxyType(mapping)‎

وسيط proxy للقراءة فقط خاصّ بكائن ربط. يوفّر هذا النوع عرضًا ديناميكيًا على عناصر كائن الربط، وهذا يعني أنّه في حال طرأ أيّ تغير على كائن الربط، فإنّ العرض سيعكس تلك التغيرات.

ملاحظة: هذا النوع جديد في الإصدار 3.3 من اللغة.

key in proxy

تعيد هذه العملية القيمة True إن امتلك كائن الربط الضمني المفتاح المعطى، وإلا فتعيد العملية القيمة False.

proxy[key]‎

يعيد التعبير العنصر الموجود في كائن الربط الضمني والذي يمتلك المفتاح المعطى، ويطلق التعبير الاستثناء KeyError إن كان المفتاح المعطى غير موجود في كائن الربط الضمني.

iter(proxy)‎

تعيد الدالة كائن تكرار يمرّ على مفاتيح كائن الربط الضمني، وهي اختصار للتعبير iter(proxy.keys())‎.

len(proxy)‎

تعيد الدالة عدد العناصر في كائن الربط الضمني.

copy()‎

تعيد الدالة نسخة سطحية لكائن الربط الضمني.

get(key[, default])‎

تعيد قيمة المرتبطة بالمفتاح المعطى إن كان موجودًا في كائن الربط الضمني، وإلّا تعيد القيمة الممرّرة في المعامل default. وفي حال عدم تمرير قيمة لهذا المعامل، فإنّه يأخذ القيمة الافتراضية None، بحيث لا يطلق هذا التابع الاستثناء KeyError.

items()‎

يعيد التابع عرضًا جديدًا لعناصر كائن الربط الضمني (على هيئة أزواج (مفتاح، قيمة)).

keys()‎

يعيد التابع عرضًا جديدًا لمفاتيح كائن الربط الضمني.

values()‎

يعيد التابع عرضًا جديدًا لقيم كائن الربط الضمني.

أصناف ودوال مساعدة إضافية

الصنف types.SimpleNamespace

صنف بسيط متفرّع من الصنف object يوفّر الوصول إلى نطاق الأسماء الخاص به عن طريق الخصائص، إلى جانب تقديم تمثيل يحمل معنى واضحًا.

على عكس الصنف object، يمكان إضافة وحذف الخصائص بواسطة الصنف SimpleNamespace. وإذا هُيّئَ كائن SimpleNamespace مع معاملات مفتاحية، فإنّه هذه المعاملات تضاف مباشرة إلى نطاق الأسماء الضمني.

هذا النوع مشابه تقريبًا للشيفرة التالية:

class SimpleNamespace:
    def __init__(self, **kwargs):
        self.__dict__.update(kwargs)

    def __repr__(self):
        keys = sorted(self.__dict__)
        items = ("{}={!r}".format(k, self.__dict__[k]) for k in keys)
        return "{}({})".format(type(self).__name__, ", ".join(items))

    def __eq__(self, other):
        return self.__dict__ == other.__dict__

يمكن للصنف SimpleNamespace أن يكون بديلًا عن class NS: pass، ولكن إن كنت بحاجة إلى نوع ذي سجلات منظّمة، فعليك باستخدام الصفوف المسمّاة namedtuple()‎.

ملاحظة: هذا الصنف جديد في الإصدار 3.3 من اللغة.

الدالة types.DynamicClassAttribute()‎

تربط الدالة وصول الخصائص في صنف معيّن بالتابع __getattr__.

يستخدم هذا الواصف لتعريف الخصائص التي تسلك سلوكًا مغايرًا عند الوصول إليها عن طريق نسخة الصنف وعن طريق الصنف. يبقى الوصول عن طريق نسخة الصنف كما هو، ولكن الوصول إلى الخاصية عن طريق الصنف سيوجَّه إلى تابع الصنف __getattr__، ويتم ذلك عن طريق إطلاق الخطأ AttributeError.

تسمح هذه الطريقة بجعل الخصائص فعالة في نسخة من الصنف، والحصول على خصائص ظاهرية في الصنف تحمل الاسم نفسه (راجع Enum للاطلاع على مثال بهذا الخصوص).

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

دوال coroutine مساعدة

الدالة types.coroutine()‎

تحوّل هذه الدالة دالة مولّدة إلى دالة coroutine تعيد coroutine مستندًا على مولّد. 

مصادر

• صفحة Dynamic type creation and names for built-in types في توثيق بايثون الرسمي.