اشیاء نوع¶

type PyTypeObject¶: قسمتی از ABI پایدار (به‌عنوان یک ساختار مبهم).
ساختار C اشیایی که برای توصیف نوع‌های توکار استفاده می‌شوند.

PyTypeObject PyType_Type¶: قسمتی از ABI پایدار.
این شیء نوع برای اشیاء نوع است؛ این همان شیء type در لایه‌ی پایتون است.

int PyType_Check(PyObject *o)¶: اگر شیء o یک شیء نوع باشد، مقدار غیرصفر را برمی‌گرداند؛ این امر شامل نمونه‌هایی از نوع‌های مشتق‌شده از شیء نوع استاندارد نیز می‌شود. در تمام موارد دیگر، 0 را برمی‌گرداند. این تابع همیشه با موفقیت انجام می‌شود.

int PyType_CheckExact(PyObject *o)¶: اگر شیء o یک شیء نوع باشد، اما زیرنوعی از شیء نوع استاندارد نباشد، مقدار غیرصفر برمی‌گرداند. در تمام موارد دیگر ۰ برمی‌گرداند. این تابع همیشه با موفقیت اجرا می‌شود.

unsigned int PyType_ClearCache()¶: قسمتی از ABI پایدار.
نهانگاه جستجوی داخلی را پاک می‌کند. برچسب نسخه‌ی فعلی را برمی‌گرداند.

unsigned long PyType_GetFlags(PyTypeObject *type)¶: قسمتی از ABI پایدار.
عضو tp_flags از type را برمی‌گرداند. این تابع در درجه‌ی اول برای استفاده با Py_LIMITED_API در نظر گرفته شده است؛ تضمین شده است که بیت‌های منفرد پرچم در میان نسخه‌های پایتون پایدار باقی بمانند، اما دسترسی به خودِ tp_flags بخشی از API محدود نیست.

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

تغییر یافته در نسخه‌ی 3.4: نوع بازگشتی اکنون unsigned long است، به‌جای long.

PyObject *PyType_GetDict(PyTypeObject *type)¶

فضای نام داخلی شیء نوع را برمی‌گرداند که در غیر این صورت تنها از طریق یک پراکسی فقط‌خواندنی (cls.__dict__) در دسترس قرار می‌گیرد. این جایگزینی برای دسترسی مستقیم به tp_dict است. دیکشنری بازگردانده‌شده باید به‌عنوان فقط‌خواندنی در نظر گرفته شود.

این تابع برای موارد خاص تعبیه و پیوند زبانی (language binding) در نظر گرفته شده است؛ مواردی که دسترسی مستقیم به دیکشنری ضروری است و دسترسی غیرمستقیم (مثلاً از طریق پراکسی یا PyObject_GetAttr()) کافی نیست.

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

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

void PyType_Modified(PyTypeObject *type)¶: قسمتی از ABI پایدار.
نهانگاه جستجوی داخلی را برای نوع و همه‌ی زیرنوع‌های آن بی‌اعتبار می‌کند. این تابع باید پس از هرگونه تغییر دستی در ویژگی‌ها یا کلاس‌های پایه‌ی نوع فراخوانی شود.

int PyType_AddWatcher(PyType_WatchCallback callback)¶

کال‌بک را به‌عنوان دیده‌بان نوع (type watcher) ثبت می‌کند. یک شناسه‌ی عدد صحیح نا‌منفی برمی‌گرداند که باید به فراخوانی‌های آتی PyType_Watch() پاس داده شود. در صورت خطا (مثلاً وقتی شناسه‌ی دیده‌بان دیگری در دسترس نیست)، مقدار -1 را برمی‌گرداند و یک استثنا تنظیم می‌کند.

در ساخت‌های نخ‌آزاد، PyType_AddWatcher() نخ‌ایمن نیست، بنابراین باید هنگام راه‌اندازی (پیش از ایجاد اولین نخ) فراخوانی شود.

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

int PyType_ClearWatcher(int watcher_id)¶

پاک‌کردن دیده‌بان (watcher) شناسایی‌شده با watcher_id (که پیش‌تر از PyType_AddWatcher() برگردانده شده است). در صورت موفقیت 0 و در صورت خطا -1 برگردانده می‌شود (مثلاً اگر watcher_id هرگز ثبت نشده باشد.)

یک ماژول توسعه‌ای هرگز نباید PyType_ClearWatcher را با یک watcher_id که توسط فراخوانی قبلی PyType_AddWatcher() به آن بازگردانده نشده است، فراخوانی کند.

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

int PyType_Watch(int watcher_id, PyObject *type)¶

type را به‌عنوان تحت نظارت علامت‌گذاری می‌کند. کال‌بکی که PyType_AddWatcher() شناسه‌ی watcher_id را به آن اعطا کرده است، هر زمان که PyType_Modified() تغییری در type را گزارش کند، فراخوانی خواهد شد. (کال‌بک ممکن است برای یک سری تغییرهای متوالی در type تنها یک بار فراخوانی شود، اگر _PyType_Lookup() بین این تغییرها بر روی type فراخوانی نشود؛ این یک جزئیات پیاده‌سازی است و ممکن است تغییر کند.)

The callback is also invoked when a watched heap type is deallocated.

یک ماژول توسعه‌ای هرگز نباید PyType_Watch را با یک watcher_id که پیش‌تر توسط فراخوانی PyType_AddWatcher() به آن بازگردانده نشده است، فراخوانی کند.

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

تغییر یافته در نسخه‌ی 3.15: The callback is now also invoked when a watched heap type is deallocated.

int PyType_Unwatch(int watcher_id, PyObject *type)¶

type را به‌عنوان نظارت‌نشده علامت‌گذاری می‌کند. این کار، فراخوانی قبلیِ PyType_Watch() را خنثی می‌کند. type نباید NULL باشد.

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

در صورت موفقیت، این تابع 0 را برمی‌گرداند. در صورت شکست، این تابع -1 را همراه با استثنای تنظیم‌شده برمی‌گرداند.

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

typedef int (*PyType_WatchCallback)(PyObject *type)¶

نوع تابع کال‌بک دیده‌بان نوع (type-watcher).

کال‌بک نباید type را تغییر دهد یا باعث فراخوانی PyType_Modified() روی type یا هیچ نوعی در ترتیب حل متد (MRO) آن شود؛ نقض این قاعده می‌تواند منجر به بازگشت بی‌نهایت شود.

The callback may be called during type deallocation. In this case, the type object is temporarily resurrected (its reference count is at least 1) and all its attributes are still valid. However, the callback should not store new strong references to the type, as this would resurrect the object and prevent its deallocation.

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

تغییر یافته در نسخه‌ی 3.15: The callback may now be called during deallocation of a watched heap type.

int PyType_HasFeature(PyTypeObject *o, int feature)¶: اگر شیء نوع o ویژگی feature را تنظیم کرده باشد، مقدار غیرصفر برمی‌گرداند. ویژگی‌های نوع با پرچم‌های تک‌بیتی نشان داده می‌شوند.

int PyType_FastSubclass(PyTypeObject *type, int flag)¶: اگر شیء نوع type پرچم زیرکلاس flag را تنظیم کرده باشد، مقدار ناصفر برمی‌گرداند. پرچم‌های زیرکلاس با Py_TPFLAGS_*_SUBCLASS نشان داده می‌شوند. این تابع توسط بسیاری از توابع _Check برای نوع‌های رایج استفاده می‌شود.

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

PyObject_TypeCheck()، که در توابع _Check برای نوع‌هایی که پرچم‌های زیرکلاس ندارند، به‌عنوان جایگزینی کندتر استفاده می‌شود.

int PyType_IS_GC(PyTypeObject *o)¶: اگر شیء نوع شامل پشتیبانی از آشکارساز چرخه باشد، مقدار true را برمی‌گرداند؛ این تابع پرچم نوع Py_TPFLAGS_HAVE_GC را بررسی می‌کند.

int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)¶

قسمتی از ABI پایدار.

اگر a زیرنوعی از b باشد، مقدار درست را برمی‌گرداند.

این تابع فقط زیرنوع‌های واقعی را بررسی می‌کند، به این معنا که __subclasscheck__() روی b فراخوانی نمی‌شود. برای انجام همان بررسی‌ای که issubclass() انجام می‌دهد، PyObject_IsSubclass() را فراخوانی کنید.

PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

هندلر عام برای جایگاه tp_alloc در یک شیء نوع. از سازوکار تخصیص حافظه پیش‌فرض پایتون برای تخصیص حافظه به یک نمونه جدید استفاده می‌کند، حافظه را صفر می‌کند، سپس حافظه را مقداردهی اولیه می‌کند، گویی که PyObject_Init() یا PyObject_InitVar() فراخوانی شده باشد.

برای تخصیص حافظه به یک شیء، این را مستقیماً فراخوانی نکنید؛ در عوض، جایگاه tp_alloc نوع را فراخوانی کنید.

برای نوع‌هایی که از زباله‌روبی پشتیبانی می‌کنند (یعنی پرچم Py_TPFLAGS_HAVE_GC تنظیم شده باشد)، این تابع مانند PyObject_GC_New یا PyObject_GC_NewVar رفتار می‌کند (به‌جز اینکه تضمین می‌شود حافظه پیش از مقداردهی اولیه صفر شود)، و باید در tp_free با PyObject_GC_Del() جفت شود. در غیر این صورت، مانند PyObject_New یا PyObject_NewVar رفتار می‌کند (به‌جز اینکه تضمین می‌شود حافظه پیش از مقداردهی اولیه صفر شود) و باید در tp_free با PyObject_Free() جفت شود.

PyObject *PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
هندلر عام برای جایگاه tp_new در یک شیء نوع است. با استفاده از جایگاه tp_alloc نوع، نمونه‌ای جدید ایجاد می‌کند و شیء حاصل را برمی‌گرداند.

int PyType_Ready(PyTypeObject *type)¶: قسمتی از ABI پایدار.
یک شیء نوع را نهایی می‌کند. این تابع باید روی همه‌ی شیءهای نوع فراخوانی شود تا مقداردهی اولیه‌شان به پایان برسد. این تابع مسئول افزودن جایگاه‌های به‌ارث‌رسیده از کلاس پایه‌ی یک نوع است. در صورت موفقیت 0 را برمی‌گرداند، یا در صورت خطا -1 را برمی‌گرداند و یک استثنا تنظیم می‌کند.

توجه

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

PyObject *PyType_GetName(PyTypeObject *type)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار از نسخه‌ی 3.11.
نام نوع را برمی‌گرداند. برابر است با دریافت ویژگی __name__ نوع.

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

PyObject *PyType_GetQualName(PyTypeObject *type)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار از نسخه‌ی 3.11.
نام کامل نوع را برمی‌گرداند. این کار معادل گرفتن ویژگی __qualname__ نوع است.

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

PyObject *PyType_GetFullyQualifiedName(PyTypeObject *type)¶: قسمتی از ABI پایدار از نسخه‌ی 3.13.
نام کامل نوع را برمی‌گرداند. معادل f"{type.__module__}.{type.__qualname__}" است، یا type.__qualname__ اگر type.__module__ رشته نباشد یا برابر با "builtins" باشد.

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

PyObject *PyType_GetModuleName(PyTypeObject *type)¶: قسمتی از ABI پایدار از نسخه‌ی 3.13.
نام ماژول نوع را برمی‌گرداند. این معادل گرفتن ویژگی type.__module__ است.

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

void *PyType_GetSlot(PyTypeObject *type, int slot)¶

قسمتی از ABI پایدار از نسخه‌ی 3.4.

اشاره‌گر تابع ذخیره‌شده در جایگاه داده‌شده را برمی‌گرداند. اگر نتیجه NULL باشد، این نشان می‌دهد که یا جایگاه NULL است، یا اینکه تابع با پارامترهای نامعتبر فراخوانی‌شده است. فراخوانندگان معمولاً اشاره‌گر نتیجه را به نوع تابع مناسب قالب‌ریزی می‌کنند.

برای مقادیر ممکن آرگومان slot به PyType_Slot.slot مراجعه کنید.

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

تغییر یافته در نسخه‌ی 3.10: PyType_GetSlot() اکنون می‌تواند همه انواع را بپذیرد. پیش‌تر، محدود به نوع‌های هیپ بود.

PyObject *PyType_GetModule(PyTypeObject *type)¶

مقدار بازگشتی: مرجع امانتی. قسمتی از ABI پایدار از نسخه‌ی 3.10.

شیء ماژول مرتبط با نوع داده‌شده را برمی‌گرداند، هنگامی که این نوع با استفاده از PyType_FromModuleAndSpec() ایجاد شده باشد.

ارجاع بازگردانده‌شده از type به‌صورت امانتی است و تا زمانی که ارجاعی به type را نگه دارید، معتبر خواهد بود. آن را با Py_DECREF() یا مشابه آن آزاد نکنید.

اگر هیچ ماژولی با نوع داده‌شده مرتبط نباشد، TypeError را تنظیم می‌کند و NULL را برمی‌گرداند.

This function is usually used to get the module in which a method is defined. Note that in such a method, PyType_GetModule(Py_TYPE(self)) may not return the intended result. Py_TYPE(self) may be a subclass of the intended class, and subclasses are not necessarily defined in the same module as their superclass. See PyCMethod to get the class that defines the method. See PyType_GetModuleByToken() for cases when PyCMethod cannot be used.

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

void *PyType_GetModuleState(PyTypeObject *type)¶

قسمتی از ABI پایدار از نسخه‌ی 3.10.

وضعیت شیء ماژول مرتبط با نوع داده‌شده را برمی‌گرداند. این یک میان‌بر برای فراخوانی PyModule_GetState() بر روی نتیجه‌ی PyType_GetModule() است.

اگر هیچ ماژولی با نوع داده‌شده مرتبط نباشد، TypeError را تنظیم می‌کند و NULL را برمی‌گرداند.

اگر نوع ماژول مرتبطی داشته باشد اما وضعیت آن NULL باشد، NULL را بدون تنظیم استثنا برمی‌گرداند.

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

PyObject *PyType_GetModuleByToken(PyTypeObject *type, const void *mod_token)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار از نسخه‌ی 3.15.

Find the first superclass whose module has the given module token, and return that module.

اگر هیچ ماژولی یافت نشود، یک TypeError ایجاد می‌کند و NULL را برمی‌گرداند.

این تابع برای استفاده همراه با PyModule_GetState() جهت گرفتن وضعیت ماژول از متدهای جایگاه (مانند tp_init یا nb_add) و دیگر جاهایی که کلاس تعریف‌کننده‌ی متد را نمی‌توان با استفاده از قرارداد فراخوانی PyCMethod ارسال کرد، در نظر گرفته شده است.

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

PyObject *PyType_GetModuleByDef(PyTypeObject *type, struct PyModuleDef *def)¶

مقدار بازگشتی: مرجع امانتی. قسمتی از ABI پایدار از نسخه‌ی 3.13.

Find the first superclass whose module was created from the given PyModuleDef def, or whose module token is equal to def, and return that module.

Note that modules created from a PyModuleDef always have their token set to the PyModuleDef's address. In other words, this function is equivalent to PyType_GetModuleByToken(), except that it:

returns a borrowed reference, and
has a non-void* argument type (which is a cosmetic difference in C).

ارجاع بازگردانده‌شده از type به‌صورت امانتی است و تا زمانی که ارجاعی به type را نگه دارید، معتبر خواهد بود. آن را با Py_DECREF() یا مشابه آن آزاد نکنید.

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

int PyType_GetBaseByToken(PyTypeObject *type, void *tp_token, PyTypeObject **result)¶

قسمتی از ABI پایدار از نسخه‌ی 3.14.

Find the first superclass in type's method resolution order whose Py_tp_token token is equal to tp_token.

اگر یافت شود، *result را برابر با یک ارجاع قوی جدید به آن قرار می‌دهد و 1 را برمی‌گرداند.
اگر یافت نشد، *result را برابر NULL قرار دهید و 0 را برگردانید.
در صورت خطا، *result را برابر NULL قرار دهید و -1 را همراه با استثنای تنظیم‌شده برگردانید.

آرگومان result می‌تواند NULL باشد که در این صورت *result مقداردهی نمی‌شود. اگر فقط به مقدار بازگشتی نیاز دارید، از این استفاده کنید.

The tp_token argument may not be NULL.

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

int PyUnstable_Type_AssignVersionTag(PyTypeObject *type)¶

این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.

تلاش می‌کند تا یک برچسب نسخه را به نوع داده‌شده انتساب دهد.

اگر نوع از قبل برچسب نسخه‌ی معتبر داشته باشد یا برچسب جدیدی به آن اختصاص داده شود، مقدار ۱ را برمی‌گرداند، و اگر نتوان برچسب جدیدی به آن اختصاص داد، مقدار ۰ را برمی‌گرداند.

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

int PyType_SUPPORTS_WEAKREFS(PyTypeObject *type)¶

اگر نمونه‌های type از ایجاد ارجاع ضعیف پشتیبانی کنند، مقدار درست و در غیر این صورت مقدار نادرست را برمی‌گرداند. این تابع همیشه با موفقیت اجرا می‌شود. type نباید NULL باشد.

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

ایجاد نوع‌های تخصیص‌یافته از هیپ¶

The following function is used to create heap types:

PyObject *PyType_FromSlots(const PySlot *slots)¶

قسمتی از ABI پایدار از نسخه‌ی 3.15.

Create and return a heap type from a PySlot array. See Definition slots for general information on slots, and Type slot IDs for slots specific to type creation.

این تابع PyType_Ready() را روی نوع جدید فراخوانی می‌کند.

توجه داشته باشید که این تابع به‌طور کامل با رفتار فراخوانی type() یا استفاده از دستور class مطابقت ندارد. با نوع‌های پایه یا فراکلاس‌های ارائه‌شده از سوی کاربر، فراخوانی type (یا فراکلاس) را به توابع PyType_From* ترجیح دهید. به‌طور مشخص:

__new__() روی کلاس جدید فراخوانی نمی‌شود (و باید روی type.__new__ تنظیم شود).
__init__() روی کلاس جدید فراخوانی نمی‌شود.
__init_subclass__() روی هیچ‌یک از کلاس‌های پایه فراخوانی نمی‌شود.
__set_name__() روی توصیف‌گرهای جدید فراخوانی نمی‌شود.

Slots are typically defined as a global static constant arrays. However, sometimes slot values are not statically known at compile time. For example, slots like Py_tp_bases, Py_tp_metaclass and Py_tp_module require live Python objects. In this case, it is recommended to put such slots on the stack, and use Py_slot_subslots to refer to an array of static slots. For example:

static const PySlot my_slots[] = {
   PySlot_STATIC_DATA(Py_tp_name, "MyClass"),
   PySlot_FUNC(Py_tp_repr, my_repr_func),
   ...
   PySlot_END
};

PyObject *make_my_class(PyObject *module) {
   PySlot all_slots[] = {
      PySlot_STATIC_DATA(Py_slot_subslots, my_slots),
      PySlot_DATA(Py_tp_module, module),
      PySlot_END
   };
   return PyType_FromSlots(all_slots);
}

Heap types created without the Py_TPFLAGS_IMMUTABLETYPE flag may be modified, for example by setting attributes on them, as with classes defined in Python code. Sometimes, such modifications are necessary to fully initialize a type, but you may wish to prevent users from changing the type after the initialization is done:

int PyType_Freeze(PyTypeObject *type)¶

قسمتی از ABI پایدار از نسخه‌ی 3.14.

برای تغییرناپذیر کردن یک نوع: پرچم Py_TPFLAGS_IMMUTABLETYPE را تنظیم کنید.

همه‌ی کلاس‌های پایه‌ی نوع باید تغییرناپذیر باشند.

در صورت موفقیت، 0 را برمی‌گرداند. در صورت خطا، یک استثنا تنظیم کرده و -1 را برمی‌گرداند.

از نوع نباید پیش از تغییرناپذیر شدن آن استفاده شود. برای مثال، نمونه‌های نوع نباید پیش از تغییرناپذیر شدن نوع ایجاد شوند.

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

Type slot IDs¶

Most type slot IDs are named like the field names of the structures PyTypeObject, PyNumberMethods, PySequenceMethods, PyMappingMethods and PyAsyncMethods with an added Py_ prefix. For example, use:

Py_tp_dealloc برای تنظیم PyTypeObject.tp_dealloc
Py_nb_add برای تنظیم PyNumberMethods.nb_add
Py_sq_length برای تنظیم PySequenceMethods.sq_length

The following slots need additional considerations when specified as slots:

Py_tp_name
Py_tp_basicsize and Py_tp_extra_basicsize
Py_tp_itemsize
Py_tp_flags

Additional slots do not directly correspond to a PyTypeObject struct field:

Py_tp_token
Py_tp_metaclass
Py_tp_module

فیلدهای «آفست» زیر را نمی‌توان با استفاده از PyType_Slot تنظیم کرد:

tp_weaklistoffset (در صورت امکان، به‌جای آن از Py_TPFLAGS_MANAGED_WEAKREF استفاده کنید)
tp_dictoffset (در صورت امکان، به‌جای آن از Py_TPFLAGS_MANAGED_DICT استفاده کنید)
tp_vectorcall_offset (از "__vectorcalloffset__" در PyMemberDef استفاده کنید)

اگر تغییر به پرچم MANAGED ممکن نباشد (برای مثال، برای vectorcall یا برای پشتیبانی از پایتون قدیمی‌تر از 3.12)، آفست را در Py_tp_members مشخص کنید. برای جزئیات، مستندات PyMemberDef را ببینید.

هنگام ایجاد نوع هیپ، فیلد‌های داخلی زیر به هیچ وجه قابل تنظیم نیستند:

tp_dict، tp_mro، tp_cache، tp_subclasses، و tp_weaklist.

The Py_tp_base slot is equivalent to Py_tp_bases; both may be set either to a type or a tuple of types. If both are specified, the value of Py_tp_bases is used.

Slot values may not be NULL, except for the following:

Py_tp_doc
Py_tp_token (برای شفافیت، Py_TP_USE_SPEC را به‌جای NULL ترجیح دهید)

تغییر یافته در نسخه‌ی 3.9: جایگاه‌های PyBufferProcs را می‌توان در API نامحدود تنظیم کرد.

تغییر یافته در نسخه‌ی 3.11: bf_getbuffer و bf_releasebuffer اکنون در API محدود در دسترس هستند.

تغییر یافته در نسخه‌ی 3.14: فیلد tp_vectorcall اکنون می‌تواند با استفاده از Py_tp_vectorcall تنظیم شود. برای جزئیات، به مستندات این فیلد مراجعه کنید.

تغییر یافته در نسخه‌ی 3.15: The Py_tp_bases slot may be set to a single type object, making it equivalent to the Py_tp_base slot. Previously, a tuple of types was required.

The following slots correspond to fields in the underlying type structure, but need extra remarks for use as slots:

Py_tp_name¶

قسمتی از ABI پایدار از نسخه‌ی 3.15.

Slot ID for the name of the type, used to set PyTypeObject.tp_name.

This slot (or PyType_Spec.name) is required to create a type.

This may not be used in PyType_Spec.slots. Use PyType_Spec.name instead.

جزئیات پیاده‌سازی در CPython: CPython processes slots in order. It is recommended to put Py_tp_name at the beginning of the slots array, so that if processing of a later slots fails, error messages can include the name.

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

Py_tp_basicsize¶

قسمتی از ABI پایدار از نسخه‌ی 3.15.

Slot ID for the size of the instance in bytes. It is used to set PyTypeObject.tp_basicsize.

The value must be positive.

This may not be used in PyType_Spec.slots. Use PyType_Spec.basicsize instead.

This slot may not be used with PyType_GetSlot(). Use PyTypeObject.tp_basicsize instead if needed, but be aware that a type's size is often considered an implementation detail.

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

Py_tp_extra_basicsize¶

قسمتی از ABI پایدار از نسخه‌ی 3.15.

Slot ID for type data size in bytes, that is, how much space instances of the class need in addition to space needed for superclasses.

The value is used, together with the size of superclasses, to set PyTypeObject.tp_basicsize. Python will insert padding as needed to meet tp_basicsize's alignment requirements.

Use PyObject_GetTypeData() to get a pointer to subclass-specific memory reserved this way.

The value must be positive. To specify that instances need no additional size (that is, size should be inherited), omit the Py_tp_extra_basicsize slot rather than set it to zero.

Specifying both Py_tp_basicsize and Py_tp_extra_basicsize is an error.

This may not be used in PyType_Spec.slots. Use negative PyType_Spec.basicsize instead.

This slot may not be used with PyType_GetSlot().

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

Py_tp_itemsize¶

قسمتی از ABI پایدار از نسخه‌ی 3.15.

Slot ID for the size of one element of a variable-size type, in bytes. Used to set PyTypeObject.tp_itemsize. See tp_itemsize documentation for caveats.

The value must be positive.

If this slot is missing, tp_itemsize is inherited. Extending arbitrary variable-sized classes is dangerous, since some types use a fixed offset for variable-sized memory, which can then overlap fixed-sized memory used by a subclass. To help prevent mistakes, inheriting itemsize is only possible in the following situations:

پایه اندازه‌متغیر نیست (tp_itemsize آن صفر است).
مقدار درخواستی PyType_Spec.basicsize مثبت است، که نشان می‌دهد چیدمان حافظه‌ی کلاس پایه معلوم است.
PyType_Spec.basicsize درخواست‌شده صفر است، که نشان می‌دهد زیرکلاس مستقیماً به حافظه‌ی نمونه دسترسی ندارد.
با پرچم Py_TPFLAGS_ITEMS_AT_END.

This may not be used in PyType_Spec.slots. Use PyType_Spec.itemsize instead.

This slot may not be used with PyType_GetSlot().

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

Py_tp_flags¶

قسمتی از ABI پایدار از نسخه‌ی 3.15.

Slot ID for type flags, used to set PyTypeObject.tp_flags.

The Py_TPFLAGS_HEAPTYPE flag is not set, PyType_FromSpecWithBases() sets it automatically.

This may not be used in PyType_Spec.slots. Use negative PyType_Spec.basicsize instead.

This slot may not be used with PyType_GetSlot(). Use PyType_GetFlags() instead.

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

Py_tp_bases¶

قسمتی از ABI پایدار.

Slot ID for type flags, used to set PyTypeObject.tp_bases.

The slot can be set to a tuple of type objects which the newly created type should inherit from, like the "positional arguments" of a Python class definition.

Alternately, the slot can be set to a single type object to specify a single base. The effect is the same as specifying a one-element tuple.

تغییر یافته در نسخه‌ی 3.15: Previously, Py_tp_bases required a tuple of types.

Py_tp_base¶: قسمتی از ABI پایدار.
Equivalent to Py_tp_bases (with s at the end). If both are specified, Py_tp_bases takes priority and this slot is ignored.

تغییر یافته در نسخه‌ی 3.15: Previously, Py_tp_base required a single type, not a tuple.

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.15: When not targeting older Python versions, prefer Py_tp_bases.

The following slots do not correspond to public fields in the underlying structures:

Py_tp_metaclass¶

قسمتی از ABI پایدار از نسخه‌ی 3.15.

Slot ID for the metaclass used to construct the resulting type object. When omitted the metaclass is derived from bases (Py_tp_bases or the bases argument of PyType_FromMetaclass()).

فراکلاس‌هایی که tp_new را بازنویسی می‌کنند پشتیبانی نمی‌شوند، مگر آنکه tp_new برابر NULL باشد.

This may not be used in PyType_Spec.slots. Use PyType_FromMetaclass() to specify a metaclass with PyType_Spec.

This slot may not be used with PyType_GetSlot(). Use Py_TYPE() on the type object instead.

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

Py_tp_module¶

قسمتی از ABI پایدار از نسخه‌ی 3.15.

Slot ID for recording the module in which the new class is defined.

The value must be a module object. The module is associated with the new type and can later be retrieved with PyType_GetModule(). The associated module is not inherited by subclasses; it must be specified for each class individually.

This may not be used in PyType_Spec.slots. Use PyType_FromMetaclass() to specify a module with PyType_Spec.

This slot may not be used with PyType_GetSlot(). Use PyType_GetModule() instead.

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

Py_tp_token¶

قسمتی از ABI پایدار از نسخه‌ی 3.14.

Slot ID for recording a static memory layout ID for a class.

If the class is defined using a PyType_Spec, and that spec is statically allocated, the token can be set to the spec using the special value Py_TP_USE_SPEC:

static PyType_Slot foo_slots[] = {
   {Py_tp_token, Py_TP_USE_SPEC},

می‌توان آن را به یک اشاره‌گر دلخواه نیز تنظیم کرد، اما باید مطمئن شوید که:

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

از PyType_GetBaseByToken() برای بررسی این‌که آیا ابرکلاس یک کلاس توکن مشخصی دارد یا نه استفاده کنید — یعنی، بررسی کنید که آیا چیدمان حافظه سازگار است یا خیر.

برای به‌دست‌آوردن توکن یک کلاس معین (بدون در نظر گرفتن کلاس‌های والد)، از PyType_GetSlot() با Py_tp_token استفاده کنید.

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

Py_TP_USE_SPEC¶

قسمتی از ABI پایدار از نسخه‌ی 3.14.

Used as a value with Py_tp_token to set the token to the class's PyType_Spec. May only be used for classes defined using PyType_Spec.

Expands to NULL.

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

Py_tp_slots¶: قسمتی از ABI پایدار از نسخه‌ی 3.15.
Slot ID that works like Py_slot_subslots, except it specifies an array of PyType_Slot structures.

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

Soft-deprecated API¶

The following functions are soft deprecated. They will continue to work, but new features will be added as slots for PyType_FromSlots(), not as arguments to new PyType_From* functions.

PyObject *PyType_FromMetaclass(PyTypeObject *metaclass, PyObject *module, PyType_Spec *spec, PyObject *bases)¶

قسمتی از ABI پایدار از نسخه‌ی 3.12.

یک نوع هیپ از spec بسازید و بازگردانید (به Py_TPFLAGS_HEAPTYPE مراجعه کنید).

A non-NULL metaclass argument corresponds to the Py_tp_metaclass slot.

A non-NULL bases argument corresponds to the Py_tp_bases slot, and takes precedence over Py_tp_bases and Py_tp_bases slots.

A non-NULL module argument corresponds to the Py_tp_module slot.

این تابع PyType_Ready() را روی نوع جدید فراخوانی می‌کند.

Note that this function does not fully match the behavior of calling type() or using the class statement. See the note in PyType_FromSlots() documentation for details.

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

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.15: Prefer PyType_FromSlots() in new code.

PyObject *PyType_FromModuleAndSpec(PyObject *module, PyType_Spec *spec, PyObject *bases)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار از نسخه‌ی 3.10.
معادل PyType_FromMetaclass(NULL, module, spec, bases) است.

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

تغییر یافته در نسخه‌ی 3.10: این تابع اکنون یک کلاس منفرد را به‌عنوان آرگومان bases و NULL را به‌عنوان جایگاه tp_doc می‌پذیرد.

تغییر یافته در نسخه‌ی 3.12: این تابع اکنون فراکلاسی متناظر با کلاس‌های پایه‌ی ارائه‌شده را می‌یابد و از آن استفاده می‌کند. پیش‌تر، تنها نمونه‌های type برگردانده می‌شدند.

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

تغییر یافته در نسخه‌ی 3.14: ساخت کلاس‌هایی که فراکلاس آن‌ها tp_new را بازنویسی می‌کند، دیگر مجاز نیست.

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.15: Prefer PyType_FromSlots() in new code.

PyObject *PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار از نسخه‌ی 3.3.
معادل PyType_FromMetaclass(NULL, NULL, spec, bases) است.

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

تغییر یافته در نسخه‌ی 3.12: این تابع اکنون فراکلاسی متناظر با کلاس‌های پایه‌ی ارائه‌شده را می‌یابد و از آن استفاده می‌کند. پیش‌تر، تنها نمونه‌های type برگردانده می‌شدند.

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

تغییر یافته در نسخه‌ی 3.14: ساخت کلاس‌هایی که فراکلاس آن‌ها tp_new را بازنویسی می‌کند، دیگر مجاز نیست.

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.15: Prefer PyType_FromSlots() in new code.

PyObject *PyType_FromSpec(PyType_Spec *spec)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
معادل PyType_FromMetaclass(NULL, NULL, spec, NULL) است.

تغییر یافته در نسخه‌ی 3.12: این تابع اکنون فراکلاسی متناظر با کلاس‌های پایه‌ی ارائه‌شده در جایگاه‌های Py_tp_base[s] را می‌یابد و از آن استفاده می‌کند. پیش‌تر، تنها نمونه‌های type برگردانده می‌شدند.

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

تغییر یافته در نسخه‌ی 3.14: ساخت کلاس‌هایی که فراکلاس آن‌ها tp_new را بازنویسی می‌کند، دیگر مجاز نیست.

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.15: Prefer PyType_FromSlots() in new code.

type PyType_Spec¶

قسمتی از ABI پایدار شامل تمام اعضا.

Structure defining a type's behavior, used for soft-deprecated functions like PyType_FromMetaclass().

This structure contains several members that can instead be specified as slots for PyType_FromSlots(), and an array of slot entries with a simpler structure.

const char *name¶: Corresponds to Py_tp_name.

int basicsize¶

If positive, corresponds to Py_tp_basicsize.

If negative, corresponds to Py_tp_extra_basicsize set to the absolute value.

تغییر یافته در نسخه‌ی 3.12: پیش‌تر، این فیلد نمی‌توانست منفی باشد.

int itemsize¶: Corresponds to Py_tp_itemsize.

unsigned int flags¶: Corresponds to Py_tp_flags.

PyType_Slot *slots¶

Array of PyType_Slot (not PySlot) structures.

Terminated by the special slot value {0, NULL}. Each slot ID should be specified at most once.

type PyType_Slot¶

قسمتی از ABI پایدار شامل تمام اعضا.

Structure defining optional functionality of a type, used for soft-deprecated functions like PyType_FromMetaclass().

Note that a PyType_Slot array may be included in a PySlot array using Py_tp_slots, and vice versa using Py_slot_subslots.

Each PyType_Slot structure tpslot is interpreted as the following PySlot structure:

(PySlot){
   .sl_id=tpslot.slot,
   .sl_flags=PySlot_INTPTR | sub_static,
   .sl_ptr=tpslot.func
}

where sub_static is PySlot_STATIC if the slot requires the flag (such as for Py_tp_methods), or if this flag is present on the "parent" Py_tp_slots slot (if any).

int slot¶: Corresponds to PySlot.sl_id.

void *pfunc¶: Corresponds to PySlot.sl_ptr.

اشیاء نوع¶

ایجاد نوع‌های تخصیص‌یافته از هیپ¶

Type slot IDs¶

Soft-deprecated API¶

فهرست مطالب

موضوع قبلی

موضوع بعدی

این صفحه