`types` --- ایجاد نوع پویا و نام‌هایی برای انواع توکار¶

کد منبع: Lib/types.py

این ماژول توابع کمکی را برای کمک به ایجاد پویای انواع جدید تعریف می‌کند.

همچنین نام‌هایی را برای برخی از انواع شیء تعریف می‌کند که توسط مفسر استاندارد پایتون استفاده می‌شوند، اما مانند int یا str به‌عنوان توکارها در دسترس نیستند.

در نهایت، این ماژول برخی کلاس‌ها و توابع کاربردی دیگر مرتبط با نوع را فراهم می‌کند که به‌اندازه‌ی کافی بنیادی نیستند که توکار باشند.

ایجاد نوع به‌صورت پویا¶

types.new_class(name, bases=(), kwds=None, exec_body=None)¶

یک شیء کلاس را به‌صورت پویا با استفاده از فراکلاس مناسب ایجاد می‌کند.

۳ آرگومان نخست، کامپوننت‌هایی هستند که سرآیند تعریف کلاس را تشکیل می‌دهند: نام کلاس، کلاس‌های پایه (به ترتیب)، آرگومان‌های کلیدواژه‌ای (مانند metaclass).

آرگومان exec_body یک کال‌بک است که برای پر کردن فضای نام کلاس به‌تازگی ایجادشده استفاده می‌شود. این کال‌بک باید فضای نام کلاس را به‌عنوان تنها آرگومان بپذیرد و فضای نام را مستقیماً با محتویات کلاس به‌روزرسانی کند. اگر کال‌بکی ارائه نشود، همان اثر ارسال lambda ns: None را دارد.

اضافه شده در نسخه‌ی 3.3.

types.prepare_class(name, bases=(), kwds=None)¶

فراکلاس مناسب را محاسبه می‌کند و فضای نام کلاس را ایجاد می‌کند.

آرگومان‌ها کامپوننت‌هایی هستند که سرآیند تعریف کلاس را تشکیل می‌دهند: نام کلاس، کلاس‌های پایه (به ترتیب) و آرگومان‌های کلیدواژه‌ای (مانند metaclass).

مقدار بازگشتی یک تاپل سه‌تایی است: metaclass, namespace, kwds

metaclass فراکلاس مناسب است، namespace فضای نام آماده‌شده‌ی کلاس است و kwds یک نسخه‌ی به‌روزشده از آرگومان kwds ارسال‌شده است که هر آیتم 'metaclass' از آن حذف‌شده است. اگر هیچ آرگومان kwds ارسال‌نشده باشد، این یک دیکشنری خالی خواهد بود.

اضافه شده در نسخه‌ی 3.3.

تغییر یافته در نسخه‌ی 3.6: مقدار پیش‌فرض عنصر namespace در تاپل برگردانده‌شده تغییر کرده است. اکنون هنگامی که فراکلاس متد __prepare__ نداشته باشد، از یک نگاشت حفظ‌کننده ترتیب درج استفاده می‌شود.

همچنین ملاحظه نمائید

فراکلاس‌ها: جزئیات کامل فرایند ایجاد کلاس که این توابع از آن پشتیبانی می‌کنند
PEP 3115 - فراکلاس‌ها در Python 3000: قلاب فضای نام __prepare__ معرفی شد

types.resolve_bases(bases)¶

مدخل‌های MRO به‌صورت پویا، مطابق PEP 560 حل می‌شوند.

این تابع در bases به دنبال آیتم‌هایی می‌گردد که نمونه‌هایی از type نیستند، و تاپلی برمی‌گرداند که در آن هر چنین شیءای که متد __mro_entries__() را داشته باشد، با نتیجه‌ی واگشایی‌شده‌ی فراخوانی این متد جایگزین می‌شود. اگر آیتمی در bases نمونه‌ای از type باشد، یا متد __mro_entries__() را نداشته باشد، بدون تغییر در تاپل بازگشتی گنجانده می‌شود.

اضافه شده در نسخه‌ی 3.7.

types.get_original_bases(cls, /)¶

تاپلی از اشیایی را برمی‌گرداند که در اصل، پیش از آنکه متد __mro_entries__() بر روی هیچ‌یک از پایه‌ها فراخوانی شده باشد، به‌عنوان پایه‌های cls داده شده‌اند (طبق سازوکارهای تشریح‌شده در PEP 560). این برای درون‌نگری Generics مفید است.

برای کلاس‌هایی که ویژگی __orig_bases__ دارند، این تابع مقدار cls.__orig_bases__ را بازمی‌گرداند. برای کلاس‌های فاقد ویژگی __orig_bases__، cls.__bases__ بازگردانده می‌شود.

مثال‌ها:

from typing import TypeVar, Generic, NamedTuple, TypedDict

T = TypeVar("T")
class Foo(Generic[T]): ...
class Bar(Foo[int], float): ...
class Baz(list[str]): ...
Eggs = NamedTuple("Eggs", [("a", int), ("b", str)])
Spam = TypedDict("Spam", {"a": int, "b": str})

assert Bar.__bases__ == (Foo, float)
assert get_original_bases(Bar) == (Foo[int], float)

assert Baz.__bases__ == (list,)
assert get_original_bases(Baz) == (list[str],)

assert Eggs.__bases__ == (tuple,)
assert get_original_bases(Eggs) == (NamedTuple,)

assert Spam.__bases__ == (dict,)
assert get_original_bases(Spam) == (TypedDict,)

assert int.__bases__ == (object,)
assert get_original_bases(int) == (object,)

اضافه شده در نسخه‌ی 3.12.

همچنین ملاحظه نمائید

PEP 560 - پشتیبانی هسته از ماژول typing و انواع عام

انواع استاندارد مفسر¶

این ماژول نام‌هایی را برای بسیاری از انواعی که برای پیاده‌سازی یک مفسر پایتون لازم هستند، فراهم می‌کند. این ماژول عمداً از گنجاندن برخی از انواعی که تنها به‌صورت جانبی در حین پردازش به وجود می‌آیند، مانند نوع listiterator، خودداری می‌کند.

کاربرد معمول این نام‌ها برای بررسی‌های isinstance() یا issubclass() است.

اگر هر یک از این نوع‌ها را نمونه‌سازی می‌کنید، توجه داشته باشید که امضاها ممکن است بین نسخه‌های پایتون متفاوت باشند.

نام‌های استاندارد برای انواع زیر تعریف شده‌اند:

class types.NoneType¶: نوع None.

اضافه شده در نسخه‌ی 3.10.

class types.FunctionType¶

class types.LambdaType¶

نوع توابع تعریف‌شده توسط کاربر و توابع ایجادشده با عبارت‌های lambda.

یک رویداد حسابرسی function.__new__ را با آرگومان code پرتاب می‌کند.

رویداد حسابرسی فقط برای نمونه‌سازی مستقیم اشیای تابع رخ می‌دهد، و در کامپایل معمولی پرتاب نمی‌شود.

class types.GeneratorType¶: نوع اشیای پیمایش‌گر تولیدگر، که توسط توابع تولیدگر ایجاد می‌شوند.

class types.CoroutineType¶: نوع اشیای هم‌روال، که با توابع async def ایجاد می‌شوند.

اضافه شده در نسخه‌ی 3.5.

class types.AsyncGeneratorType¶: نوع اشیاء پیمایش‌گر asynchronous generator، که توسط توابع تولیدگر ناهمگام ایجاد می‌شوند.

اضافه شده در نسخه‌ی 3.6.

class types.CodeType(**kwargs)¶

نوع اشیای کد (code objects)، مانند آنچه توسط compile() برگردانده می‌شود.

یک رویداد حسابرسی code.__new__ را با آرگومان‌های code، filename، name، argcount، posonlyargcount، kwonlyargcount، nlocals، stacksize، flags پرتاب می‌کند.

توجه داشته باشید که ممکن است آرگومان‌های حسابرسی‌شده با نام‌ها یا جایگاه‌های مورد نیاز مقداردهنده اولیه مطابقت نداشته باشند. رویداد حسابرسی فقط برای نمونه‌سازی مستقیم اشیای کد رخ می‌دهد و برای کامپایل معمولی پرتاب نمی‌شود.

class types.CellType¶: نوع اشیای سلول: از چنین اشیایی به‌عنوان ظرفی برای متغیرهای بستار تابع استفاده می‌شود.

اضافه شده در نسخه‌ی 3.8.

class types.MethodType¶: نوع متدهای نمونه‌های کلاس تعریف‌شده توسط کاربر.

class types.BuiltinFunctionType¶
class types.BuiltinMethodType¶: نوع توابع توکار مانند len() یا sys.exit() و متدهای کلاس‌های توکار. (در اینجا، اصطلاح «توکار» به معنای «نوشته‌شده به C» است.)

class types.WrapperDescriptorType¶: نوع متدهای برخی از انواع داده توکار و کلاس‌های پایه مانند object.__init__() یا object.__lt__().

اضافه شده در نسخه‌ی 3.7.

class types.MethodWrapperType¶: نوع متدهای مقید برخی از انواع داده توکار و کلاس‌های پایه. برای مثال، این نوعِ object().__str__ است.

اضافه شده در نسخه‌ی 3.7.

class types.NotImplementedType¶: نوع NotImplemented.

اضافه شده در نسخه‌ی 3.10.

class types.MethodDescriptorType¶: نوع متدهای برخی از انواع داده‌ی توکار مانند str.join().

اضافه شده در نسخه‌ی 3.7.

class types.ClassMethodDescriptorType¶: نوع متدهای کلاسی مقیدنشده (unbound) برخی از انواع داده توکار مانند dict.__dict__['fromkeys'].

اضافه شده در نسخه‌ی 3.7.

class types.ModuleType(name, doc=None)¶

نوع ماژول‌ها. سازنده، نام ماژولی را که قرار است ایجاد شود و به‌اختیار رشته مستند آن را دریافت می‌کند.

همچنین ملاحظه نمائید

مستندات اشیای ماژول: جزئیاتی درباره ویژگی‌های خاصی که می‌توان در نمونه‌های ModuleType یافت، ارائه می‌دهد.
importlib.util.module_from_spec(): ماژول‌هایی که با استفاده از سازنده‌ی ModuleType ایجاد می‌شوند، به‌گونه‌ای ایجاد می‌شوند که بسیاری از ویژگی‌های خاص آن‌ها یا تنظیم‌نشده‌اند یا روی مقادیر پیش‌فرض تنظیم شده‌اند. module_from_spec() روش مطمئن‌تری برای ایجاد نمونه‌های ModuleType ارائه می‌کند که تضمین می‌کند ویژگی‌های مختلف به‌درستی تنظیم می‌شوند.

class types.EllipsisType¶: نوع Ellipsis.

اضافه شده در نسخه‌ی 3.10.

class types.GenericAlias(t_origin, t_args)¶

نوع عام‌های پارامتریزه‌شده (parameterized generics) مانند list[int].

t_origin باید یک کلاس عام پارامتریزه‌نشده باشد، مانند list، tuple یا dict. t_args باید یک tuple (احتمالاً به طول ۱) از انواعی باشد که t_origin را پارامتریزه می‌کنند:

>>> from types import GenericAlias

>>> list[int] == GenericAlias(list, (int,))
True
>>> dict[str, int] == GenericAlias(dict, (str, int))
True

اضافه شده در نسخه‌ی 3.9.

تغییر یافته در نسخه‌ی 3.9.2: اکنون می‌توان این نوع را زیرکلاس‌سازی کرد.

همچنین ملاحظه نمائید

انواع نام‌های مستعار عام: مستندات تفصیلی درباره‌ی نمونه‌های types.GenericAlias
PEP 585 - راهنمای نوع برای عام‌ها در مجموعه‌های استاندارد: معرفی کلاس types.GenericAlias

class types.UnionType¶: نوع عبارت‌های نوع union.

اضافه شده در نسخه‌ی 3.10.

تغییر یافته در نسخه‌ی 3.14: این اکنون یک نام مستعار برای typing.Union است.

class types.TracebackType(tb_next, tb_frame, tb_lasti, tb_lineno)¶

نوع اشیای ردگیری پشته، مانند آنچه در sys.exception().__traceback__ یافت می‌شود.

برای جزئیات ویژگی‌ها و عملیات در دسترس و راهنمایی درباره‌ی ایجاد ردگیری‌ها به‌صورت پویا، مرجع زبان را ببینید.

class types.FrameType¶: نوع اشیاء فریم، مانند آنچه در tb.tb_frame یافت می‌شود، اگر tb یک شیء ردگیری پشته باشد.

class types.GetSetDescriptorType¶: نوع اشیاء تعریف‌شده در ماژول‌های توسعه با PyGetSetDef، مانند FrameType.f_locals یا array.array.typecode. این نوع به‌عنوان توصیف‌گر برای ویژگی‌های شیء استفاده می‌شود؛ همان هدفی را دارد که نوع property دارد، اما برای کلاس‌های تعریف‌شده در ماژول‌های توسعه.

class types.MemberDescriptorType¶

نوع اشیایی که در ماژول‌های توسعه با PyMemberDef تعریف می‌شوند، مانند datetime.timedelta.days. این نوع به‌عنوان توصیف‌گر برای اعضای داده‌ای ساده C که از توابع تبدیل استاندارد استفاده می‌کنند به کار می‌رود؛ این نوع همان هدف نوع property را دارد، اما برای کلاس‌های تعریف‌شده در ماژول‌های توسعه.

علاوه بر این، هنگامی که یک کلاس با ویژگی __slots__ تعریف می‌شود، به ازای هر جایگاه، نمونه‌ای از MemberDescriptorType به‌عنوان یک ویژگی به کلاس اضافه خواهد شد. این امر باعث می‌شود جایگاه در __dict__ کلاس ظاهر شود.

در سایر پیاده‌سازی‌های پایتون، این نوع ممکن است با GetSetDescriptorType یکسان باشد.

class types.MappingProxyType(mapping)¶

پراکسی فقط‌خواندنی از یک نگاشت. این پراکسی یک نمای پویا از آیتم‌های نگاشت فراهم می‌کند، به این معنا که هنگامی که نگاشت تغییر می‌کند، نما این تغییرات را بازتاب می‌دهد.

نمونه‌های MappingProxyType نسبت به دو نوع عام هستند، که (به‌ترتیب) نشان‌دهنده‌ی انواع کلیدها و مقادیر نگاشت زیرین هستند.

اضافه شده در نسخه‌ی 3.3.

تغییر یافته در نسخه‌ی 3.9: برای پشتیبانی از عملگر اجتماع جدید (|) در PEP 584 به‌روزرسانی شد، که به‌سادگی به نگاشت زیرین واگذار می‌شود.

key in proxy: اگر نگاشت زیرین کلید key را داشته باشد، True و در غیر این صورت False را برمی‌گرداند.

proxy[key]: آیتم نگاشت زیرین با کلید key را برمی‌گرداند. اگر key در نگاشت زیرین وجود نداشته باشد، KeyError پرتاب می‌شود.

iter(proxy): پیمایش‌گری بر روی کلیدهای نگاشت زیرین برمی‌گرداند. این یک میان‌بر برای iter(proxy.keys()) است.

len(proxy): تعداد آیتم‌های نگاشت زیرین را برمی‌گرداند.

copy()¶: یک کپی سطحی از نگاشت زیربنایی برمی‌گرداند.

get(key[, default])¶: اگر key در نگاشت زیرین موجود باشد، مقدار مربوط به key را بازمی‌گرداند، در غیر این صورت default را. اگر default داده نشده باشد، پیش‌فرض آن None است، بنابراین این متد هرگز KeyError پرتاب نمی‌کند.

items()¶: یک نمای جدید از آیتم‌های نگاشت زیربنایی برمی‌گرداند (جفت‌های (key, value)).

keys()¶: یک نمای جدید از کلیدهای نگاشت زیربنایی برمی‌گرداند.

values()¶: نمای جدیدی از مقادیر نگاشت زیربنایی برمی‌گرداند.

reversed(proxy): یک پیمایش‌گر معکوس روی کلیدهای نگاشت زیرین برمی‌گرداند.

اضافه شده در نسخه‌ی 3.9.

hash(proxy): هش نگاشت زیرین را برمی‌گرداند.

اضافه شده در نسخه‌ی 3.12.

class types.CapsuleType¶: نوع اشیای کپسول (capsule objects).

اضافه شده در نسخه‌ی 3.13.

کلاس‌ها و توابع سودمند اضافی¶

class types.SimpleNamespace¶

یک زیرکلاس ساده از object که دسترسی به ویژگی‌های فضای نام خود و همچنین یک repr معنادار را فراهم می‌کند.

برخلاف object، با SimpleNamespace می‌توانید ویژگی‌ها را اضافه و حذف کنید.

اشیای SimpleNamespace می‌توانند به همان روش dict مقداردهی اولیه شوند: یا با آرگومان‌های کلیدواژه‌ای، یا با یک آرگومان جایگاهی، یا با هر دو. هنگامی که با آرگومان‌های کلیدواژه‌ای مقداردهی اولیه شوند، آن‌ها مستقیماً به فضای نام زیرین اضافه می‌شوند. در حالت دیگر، هنگامی که با یک آرگومان جایگاهی مقداردهی اولیه شوند، فضای نام زیرین با جفت‌های کلید-مقدار آن آرگومان به‌روزرسانی می‌شود (چه یک شیء نگاشت و چه یک شیء پیمایش‌پذیر که جفت‌های کلید-مقدار تولید می‌کند). همه‌ی چنین کلیدهایی باید رشته باشند.

این نوع تقریباً معادل کد زیر است:

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

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

    def __eq__(self, other):
        if isinstance(self, SimpleNamespace) and isinstance(other, SimpleNamespace):
           return self.__dict__ == other.__dict__
        return NotImplemented

SimpleNamespace ممکن است به‌عنوان جایگزینی برای class NS: pass مفید باشد. با این حال، برای یک نوع رکورد ساختاریافته، در عوض از namedtuple() استفاده کنید.

اشیای SimpleNamespace توسط copy.replace() پشتیبانی می‌شوند.

اضافه شده در نسخه‌ی 3.3.

تغییر یافته در نسخه‌ی 3.9: ترتیب ویژگی‌ها در repr از الفبایی به ترتیب درج تغییر کرد (مانند dict).

تغییر یافته در نسخه‌ی 3.13: پشتیبانی از یک آرگومان جایگاهی اختیاری افزوده شد.

types.DynamicClassAttribute(fget=None, fset=None, fdel=None, doc=None)¶

دسترسی به ویژگی‌های یک کلاس را به __getattr__ هدایت کنید.

این یک توصیف‌گر است که برای تعریف ویژگی‌هایی استفاده می‌شود که هنگام دسترسی از طریق یک نمونه و از طریق یک کلاس، رفتار متفاوتی دارند. دسترسی از طریق نمونه عادی باقی می‌ماند، اما دسترسی به یک ویژگی از طریق کلاس به متد __getattr__ کلاس هدایت می‌شود؛ این کار با پرتاب AttributeError انجام می‌شود.

این به شما امکان می‌دهد که پراپرتی‌ها روی یک نمونه فعال باشند و ویژگی‌های مجازی با همان نام روی کلاس وجود داشته باشند (برای مثال enum.Enum را ببینید).

اضافه شده در نسخه‌ی 3.4.

توابع سودمند هم‌روال¶

types.coroutine(gen_func)¶

این تابع، یک تابع تولیدگر را به یک coroutine function تبدیل می‌کند که یک هم‌روال مبتنی بر تولیدگر را برمی‌گرداند. هم‌روال مبتنی بر تولیدگر همچنان یک generator iterator است، اما همچنین یک شیء هم‌روال در نظر گرفته می‌شود و awaitable است. با این حال، ممکن است لزوماً متد __await__() را پیاده‌سازی نکند.

اگر gen_func یک تابع تولیدگر باشد، به‌صورت درجا تغییر داده خواهد شد.

اگر gen_func یک تابع تولیدگر نباشد، دربرگرفته خواهد شد. اگر نمونه‌ای از collections.abc.Generator را برگرداند، آن نمونه در یک شیء پراکسی awaitable دربرگرفته خواهد شد. تمام انواع دیگر اشیاء همان‌طور که هستند برگردانده خواهند شد.

اضافه شده در نسخه‌ی 3.5.

`types` --- ایجاد نوع پویا و نام‌هایی برای انواع توکار¶

ایجاد نوع به‌صورت پویا¶

انواع استاندارد مفسر¶

کلاس‌ها و توابع سودمند اضافی¶

توابع سودمند هم‌روال¶

فهرست مطالب

موضوع قبلی

موضوع بعدی

این صفحه

types --- ایجاد نوع پویا و نام‌هایی برای انواع توکار¶

ایجاد نوع به‌صورت پویا¶

انواع استاندارد مفسر¶

کلاس‌ها و توابع سودمند اضافی¶

توابع سودمند هم‌روال¶

`types` --- ایجاد نوع پویا و نام‌هایی برای انواع توکار¶