اشیاء نوع

type PyTypeObject
قسمتی از API محدود (به‌عنوان یک ساختار مبهم).

ساختار 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 فراخوانی نشود؛ این یک جزئیات پیاده‌سازی است و ممکن است تغییر کند.)

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

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

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) آن شود؛ نقض این قاعده می‌تواند منجر به بازگشت بی‌نهایت شود.

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

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 را برمی‌گرداند.

این تابع معمولاً برای به‌دست‌آوردن ماژولی که متدی در آن تعریف شده است استفاده می‌شود. توجه داشته باشید که در چنین متدی، PyType_GetModule(Py_TYPE(self)) ممکن است نتیجه‌ی مورد نظر را برنگرداند. Py_TYPE(self) ممکن است یک زیرکلاس از کلاس مورد نظر باشد و زیرکلاس‌ها لزوماً در همان ماژولی که ابرکلاس‌شان در آن تعریف شده است، تعریف نمی‌شوند. برای به‌دست‌آوردن کلاسی که متد را تعریف می‌کند، به PyCMethod مراجعه کنید. برای مواردی که نمی‌توان از PyCMethod استفاده کرد، به PyType_GetModuleByDef() مراجعه کنید.

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

void *PyType_GetModuleState(PyTypeObject *type)
قسمتی از ABI پایدار از نسخه‌ی 3.10.

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

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

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

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

PyObject *PyType_GetModuleByDef(PyTypeObject *type, struct PyModuleDef *def)
مقدار بازگشتی: مرجع امانتی. قسمتی از ABI پایدار از نسخه‌ی 3.13.

اولین ابرکلاسی را بیابید که ماژول آن از PyModuleDef def داده‌شده ساخته‌شده است و آن ماژول را برگردانید.

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

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

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

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

int PyType_GetBaseByToken(PyTypeObject *type, void *token, PyTypeObject **result)
قسمتی از ABI پایدار از نسخه‌ی 3.14.

اولین ابرکلاسی را در ترتیب حل متد type می‌یابد که توکن Py_tp_token آن با توکن داده‌شده برابر است.

  • اگر یافت شود، *result را برابر با یک ارجاع قوی جدید به آن قرار می‌دهد و 1 را برمی‌گرداند.

  • اگر یافت نشد، *result را برابر NULL قرار دهید و 0 را برگردانید.

  • در صورت خطا، *result را برابر NULL قرار دهید و -1 را همراه با استثنای تنظیم‌شده برگردانید.

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

آرگومان token نباید NULL باشد.

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

int PyUnstable_Type_AssignVersionTag(PyTypeObject *type)
این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.

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

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

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

int PyType_SUPPORTS_WEAKREFS(PyTypeObject *type)

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

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

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

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

PyObject *PyType_FromMetaclass(PyTypeObject *metaclass, PyObject *module, PyType_Spec *spec, PyObject *bases)
قسمتی از ABI پایدار از نسخه‌ی 3.12.

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

فراکلاس metaclass برای ساخت شیء نوع حاصل استفاده می‌شود. وقتی metaclass برابر NULL باشد، فراکلاس از bases به دست می‌آید (یا از جایگاه‌های Py_tp_base[s] اگر bases برابر NULL باشد؛ در ادامه ببینید).

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

می‌توان از آرگومان bases برای تعیین کلاس‌های پایه استفاده کرد؛ این آرگومان می‌تواند تنها یک کلاس یا یک تاپل از کلاس‌ها باشد. اگر bases برابر NULL باشد، در عوض از جایگاه Py_tp_bases استفاده می‌شود. اگر آن نیز NULL باشد، در عوض از جایگاه Py_tp_base استفاده می‌شود. اگر آن نیز NULL باشد، نوع جدید از object مشتق می‌شود.

می‌توان از آرگومان module برای ثبت ماژولی که کلاس جدید در آن تعریف می‌شود، استفاده کرد. این آرگومان باید یک شیء ماژول یا NULL باشد. اگر NULL نباشد، ماژول با نوع جدید مرتبط می‌شود و بعداً می‌توان آن را با PyType_GetModule() بازیابی کرد. ماژول مرتبط به زیرکلاس‌ها به ارث نمی‌رسد؛ باید برای هر کلاس به‌طور جداگانه مشخص شود.

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

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

  • __new__() روی کلاس جدید فراخوانی نمی‌شود (و باید روی type.__new__ تنظیم شود).

  • __init__() روی کلاس جدید فراخوانی نمی‌شود.

  • __init_subclass__() روی هیچ‌یک از کلاس‌های پایه فراخوانی نمی‌شود.

  • __set_name__() روی توصیف‌گرهای جدید فراخوانی نمی‌شود.

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

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 را بازنویسی می‌کند، دیگر مجاز نیست.

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 را بازنویسی می‌کند، دیگر مجاز نیست.

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 را بازنویسی می‌کند، دیگر مجاز نیست.

int PyType_Freeze(PyTypeObject *type)
قسمتی از ABI پایدار از نسخه‌ی 3.14.

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

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

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

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

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

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

ساختاری که رفتار یک نوع را تعریف می‌کند.

const char *name

نام نوع، که برای تنظیم PyTypeObject.tp_name استفاده می‌شود.

int basicsize

اگر مثبت باشد، اندازه‌ی نمونه را بر حسب بایت مشخص می‌کند. از آن برای تنظیم PyTypeObject.tp_basicsize استفاده می‌شود.

اگر صفر باشد، مشخص می‌کند که tp_basicsize باید به ارث برده شود.

اگر منفی باشد، قدر مطلق آن مشخص می‌کند که نمونه‌های کلاس علاوه بر ابرکلاس به چه مقدار فضا نیاز دارند. برای دریافت اشاره‌گر به حافظه‌ی اختصاصی زیرکلاس که به این شیوه رزرو شده است، از PyObject_GetTypeData() استفاده کنید. برای basicsize منفی، پایتون در صورت نیاز پدینگ اضافه خواهد کرد تا نیازمندی‌های ترازبندیِ tp_basicsize را برآورده کند.

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

int itemsize

اندازه‌ی یک المان از یک نوع با اندازه‌ی متغیر، بر حسب بایت. برای تنظیم PyTypeObject.tp_itemsize استفاده می‌شود. برای هشدارها به مستندات tp_itemsize مراجعه کنید.

اگر صفر باشد، tp_itemsize به ارث برده می‌شود. گسترش کلاس‌های اندازه‌متغیرِ دلخواه خطرناک است، زیرا برخی نوع‌ها برای حافظه‌ی اندازه‌متغیر از آفست ثابت استفاده می‌کنند که در نتیجه می‌تواند با حافظه‌ی اندازه‌ثابتِ استفاده‌شده توسط یک زیرکلاس هم‌پوشانی پیدا کند. برای کمک به جلوگیری از اشتباهات، ارث‌بری itemsize تنها در شرایط زیر ممکن است:

  • پایه اندازه‌متغیر نیست (tp_itemsize آن صفر است).

  • مقدار درخواستی PyType_Spec.basicsize مثبت است، که نشان می‌دهد چیدمان حافظه‌ی کلاس پایه معلوم است.

  • PyType_Spec.basicsize درخواست‌شده صفر است، که نشان می‌دهد زیرکلاس مستقیماً به حافظه‌ی نمونه دسترسی ندارد.

  • با پرچم Py_TPFLAGS_ITEMS_AT_END.

unsigned int flags

پرچم‌های نوع، که برای تنظیم PyTypeObject.tp_flags به کار می‌روند.

اگر پرچم Py_TPFLAGS_HEAPTYPE تنظیم‌نشده باشد، تابع PyType_FromSpecWithBases() آن را به‌طور خودکار تنظیم می‌کند.

PyType_Slot *slots

آرایه‌ای از ساختارهای PyType_Slot. با مقدار جایگاه ویژه‌ی {0, NULL} پایان می‌یابد.

هر شناسه‌ی جایگاه باید حداکثر یک‌بار مشخص شود.

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

ساختاری که کارکرد اختیاری یک نوع را تعریف می‌کند و شامل شناسه‌ی جایگاه و اشاره‌گر مقدار است.

int slot

شناسه‌ی جایگاه.

شناسه‌های جایگاه مانند نام فیلدهای ساختارهای PyTypeObject، PyNumberMethods، PySequenceMethods، PyMappingMethods و PyAsyncMethods با افزودن پیشوند Py_ نام‌گذاری می‌شوند. برای مثال، از این استفاده کنید:

یک جایگاه اضافی پشتیبانی می‌شود که با هیچ فیلدی از ساختار PyTypeObject مطابق نیست:

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

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

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

تنظیم Py_tp_bases یا Py_tp_base ممکن است روی برخی پلتفرم‌ها مشکل‌ساز باشد. برای پرهیز از مشکلات، به‌جای آن از آرگومان bases در PyType_FromSpecWithBases() استفاده کنید.

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

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

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

void *pfunc

مقدار موردنظر جایگاه. در بیشتر موارد، این یک اشاره‌گر به تابع است.

مقادیر pfunc نمی‌توانند NULL باشند، به‌جز جایگاه‌های زیر:

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

یک slot که شناسه‌ی چیدمان حافظه‌ی ایستا را برای یک کلاس ثبت می‌کند.

اگر PyType_Spec کلاس به‌صورت ایستا تخصیص یافته باشد، می‌توان توکن را با استفاده از مقدار ویژه‌ی 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.

به عنوان یک مقدار همراه با Py_tp_token برای تنظیم توکن به PyType_Spec کلاس استفاده می‌شود. به NULL بسط می‌یابد.

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