اشیاء نوع

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

این کال‌بک همچنین زمانی که یک نوع هیپ تحت نظارت تخصیص‌زدایی می‌شود، فراخوانی می‌شود.

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

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

تغییر یافته در نسخه‌ی 3.15: اکنون این کال‌بک همچنین زمانی که یک نوع هیپ تحت نظارت تخصیص‌زدایی می‌شود، فراخوانی می‌شود.

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.

تغییر یافته در نسخه‌ی 3.15: اکنون ممکن است این کال‌بک در طول تخصیص‌زدایی یک نوع هیپ تحت نظارت فراخوانی شود.

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_GetModuleByToken() را ببیند.

اضافه شده در نسخه‌ی 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.

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

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

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

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

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

نخستین ابرکلاسی را که ماژول آن از def (یک PyModuleDef داده‌شده) ایجاد شده است، یا توسعه‌ی توکن ماژول آن برابر با def است پیدا کنید، و آن ماژول را برگردانید.

توجه داشته باشید که ماژول‌های ایجادشده از یک PyModuleDef همیشه توکن خود را روی آدرس PyModuleDef تنظیم می‌کنند. به عبارت دیگر، این تابع معادل PyType_GetModuleByToken() است، با این تفاوت که:

  • یک ارجاع امانتی برمی‌گرداند، و

  • دارای نوع آرگومانی غیر از void* است (که یک تفاوت ظاهری در C است).

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

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

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

نخستین ابرکلاس را در ترتیب حل متد متعلق به type پیدا کنید که توکن Py_tp_token آن برابر با tp_token باشد.

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

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

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

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

آرگومان tp_token نمی‌تواند NULL باشد.

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

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

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

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

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

int PyType_SUPPORTS_WEAKREFS(PyTypeObject *type)

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

همچنین ببینید

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

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

PyObject *PyType_FromSlots(const PySlot *slots)
قسمتی از ABI پایدار از نسخه‌ی 3.15.

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

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

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

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

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

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

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

جایگاه‌ها معمولاً به عنوان آرایه‌های ثابتِ ایستا و سراسری تعریف می‌شوند. با این حال، گاهی اوقات مقادیر جایگاه در زمان کامپایل به طور ایستا شناخته نمی‌شوند. برای مثال، جایگاه‌هایی مانند Py_tp_bases، Py_tp_metaclass و Py_tp_module به شیء‌های زنده‌ی پایتون نیاز دارند. در این صورت، توصیه می‌شود چنین جایگاه‌هایی را روی پشته قرار دهید و از Py_slot_subslots برای ارجاع به آرایه‌ای از جایگاه‌های ایستا استفاده کنید. برای مثال:

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) ایجادشده بدون پرچم Py_TPFLAGS_IMMUTABLETYPE ممکن است تغییر داده شوند؛ برای نمونه با تعیین ویژگی‌ها روی آن‌ها، درست مانند کلاس‌های تعریف‌شده در کد پایتون. گاهی اوقات، چنین تغییراتی برای مقداردهی اولیه کامل یک نوع ضروری هستند، اما ممکن است بخواهید پس از اتمام مقداردهی اولیه، از تغییر نوع توسط کاربران جلوگیری کنید:

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

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

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

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

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

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

شناسه‌های جایگاه نوع

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

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

جایگاه‌های اضافی مستقیماً با یک فیلد ساختار PyTypeObject مطابقت ندارند:

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

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

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

جایگاه Py_tp_base معادل Py_tp_bases است؛ هر دو را می‌توان روی یک نوع یا یک تاپل از نوع‌ها تنظیم کرد. اگر هر دو مشخص شوند، مقدار Py_tp_bases به کار گرفته می‌شود.

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

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

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

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

تغییر یافته در نسخه‌ی 3.15: جایگاه Py_tp_bases را می‌توان روی یک شیء نوع منفرد تنظیم کرد که آن را با جایگاه Py_tp_base معادل می‌سازد. پیش‌تر، یک تاپل از نوع‌ها مورد نیاز بود.

جایگاه‌های زیر با فیلدهای موجود در ساختار نوع زیرین مطابقت دارند، اما برای استفاده به عنوان جایگاه به نکات اضافه‌تری نیاز دارند:

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

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

این جایگاه (یا PyType_Spec.name) برای ایجاد یک نوع الزامی است.

نمی‌توان از این مورد در PyType_Spec.slots استفاده کرد. به جای آن از PyType_Spec.name استفاده کنید.

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

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

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

Slot ID برای اندازه‌ی نمونه بر حسب بایت. از آن برای تنظیم PyTypeObject.tp_basicsize استفاده می‌شود.

مقدار باید مثبت باشد.

نمی‌توان از این مورد در PyType_Spec.slots استفاده کرد. به جای آن از PyType_Spec.basicsize استفاده کنید.

نمی‌توان از این جایگاه با PyType_GetSlot() استفاده کرد. در صورت نیاز به جای آن از PyTypeObject.tp_basicsize استفاده کنید، اما آگاه باشید که اندازه‌ی یک نوع اغلب جزئیات پیاده‌سازی در نظر گرفته می‌شود.

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

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

Slot ID برای اندازه‌ی داده‌ی نوع بر حسب بایت، یعنی این که نمونه‌های کلاس علاوه بر فضای مورد نیاز برای کلاس‌های والد، به چه مقدار فضا نیاز دارند.

این مقدار به همراه اندازه‌ی کلاس‌های والد، برای تنظیم PyTypeObject.tp_basicsize استفاده می‌شود. پایتون در صورت نیاز برای برآورده کردن الزامات تراز کردن tp_basicsize، پدینگ (padding) درج خواهد کرد.

از PyObject_GetTypeData() برای دریافت یک اشاره‌گر به حافظه‌ی مختص زیرکلاس که به این روش رزرو شده است استفاده کنید.

مقدار باید مثبت باشد. برای مشخص کردن اینکه نمونه‌ها به اندازه‌ی اضافی نیاز ندارند (یعنی اندازه باید به ارث برسد)، به جای تنظیم آن روی صفر، جایگاه Py_tp_extra_basicsize را حذف کنید.

مشخص کردن هم‌زمان Py_tp_basicsize و Py_tp_extra_basicsize یک خطا است.

نمی‌توان از این مورد در PyType_Spec.slots استفاده کرد. به جای آن از PyType_Spec.basicsize منفی استفاده کنید.

نمی‌توان از این جایگاه با PyType_GetSlot() استفاده کرد.

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

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

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

مقدار باید مثبت باشد.

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

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

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

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

  • با پرچم Py_TPFLAGS_ITEMS_AT_END.

این مورد را نمی‌توان در PyType_Spec.slots استفاده کرد. به‌جای آن از PyType_Spec.itemsize استفاده کنید.

نمی‌توان از این جایگاه با PyType_GetSlot() استفاده کرد.

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

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

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

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

نمی‌توان از این مورد در PyType_Spec.slots استفاده کرد. به جای آن از PyType_Spec.basicsize منفی استفاده کنید.

این جایگاه را نمی‌توان با PyType_GetSlot() استفاده کرد. به‌جای آن از PyType_GetFlags() استفاده کنید.

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

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

Slot ID برای پرچم‌های نوع، که برای تنظیم PyTypeObject.tp_bases استفاده می‌شود.

این جایگاه را می‌توان روی تاپلی از شیءهای نوع تنظیم کرد که نوع تازه ایجادشده باید از آن‌ها ارث‌بری کند، مانند «آرگومان‌های جایگاهی» در تعریف کلاس پایتون.

به‌عنوان جایگزین، این جایگاه را می‌توان روی یک شیء نوع واحد تنظیم کرد تا یک پایه (base) منفرد مشخص شود. اثر آن همانند مشخص کردن یک تاپل تک‌عنصری است.

تغییر یافته در نسخه‌ی 3.15: پیش‌تر، Py_tp_bases به یک تاپل از نوع‌ها نیاز داشت.

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

معادل Py_tp_bases (با یک s در انتها). اگر هر دو مشخص شوند، Py_tp_bases اولویت دارد و این جایگاه نادیده گرفته می‌شود.

تغییر یافته در نسخه‌ی 3.15: پیش‌تر، Py_tp_base به یک نوع منفرد نیاز داشت، نه یک تاپل.

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.15: هنگامی که نسخه‌های قدیمی‌تر پایتون را هدف قرار نمی‌دهید، Py_tp_bases را ترجیح دهید.

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

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

Slot ID برای فراکلاسی که برای ساخت شیء نوع حاصل استفاده می‌شود. هنگامی که حذف شود، فراکلاس از پایه‌ها (Py_tp_bases یا آرگومان bases در PyType_FromMetaclass()) مشتق می‌شود.

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

این مورد را نمی‌توان در PyType_Spec.slots استفاده کرد. برای مشخص کردن یک فراکلاس با PyType_Spec از PyType_FromMetaclass() استفاده کنید.

این جایگاه را نمی‌توان با PyType_GetSlot() استفاده کرد. به‌جای آن از Py_TYPE() روی شیء نوع استفاده کنید.

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

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

شناسه‌ی جایگاه برای ثبت ماژولی که کلاس جدید در آن تعریف شده است.

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

این مورد را نمی‌توان در PyType_Spec.slots استفاده کرد. برای مشخص کردن یک ماژول با PyType_Spec از PyType_FromMetaclass() استفاده کنید.

این جایگاه را نمی‌توان با PyType_GetSlot() استفاده کرد. به‌جای آن از PyType_GetModule() استفاده کنید.

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

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

Slot ID برای ثبت یک شناسه‌ی طرح‌بندی حافظه‌ی ایستا برای یک کلاس.

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

به NULL گسترش می‌یابد.

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

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

شناسه‌ی جایگاه که مانند Py_slot_subslots کار می‌کند، با این تفاوت که آرایه‌ای از ساختارهای PyType_Slot را مشخص می‌کند.

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

API منسوخ‌سازی نرم

توابع زیر منسوخ‌شده‌ی نرم هستند. آن‌ها به کار خود ادامه خواهند داد، اما ویژگی‌های جدید به عنوان جایگاه‌ها برای PyType_FromSlots() اضافه خواهند شد، نه به عنوان آرگومان‌ها برای توابع جدید PyType_From*.

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

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

یک آرگومان metaclass غیر-NULL با جایگاه Py_tp_metaclass مطابقت دارد.

یک آرگومان bases غیر-NULL با جایگاه Py_tp_bases مطابقت دارد و بر جایگاه‌های Py_tp_bases و Py_tp_bases اولویت دارد.

یک آرگومان ماژول غیر NULL متناظر با جایگاه Py_tp_module است.

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

توجه داشته باشید که این تابع کاملاً با رفتار فراخوانی type() یا استفاده از دستور class مطابقت ندارد. برای جزئیات، یادداشت موجود در مستندات PyType_FromSlots() را ببینید.

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

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.15: در کد جدید، PyType_FromSlots() را ترجیح دهید.

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: در کد جدید، PyType_FromSlots() را ترجیح دهید.

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: در کد جدید، PyType_FromSlots() را ترجیح دهید.

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: در کد جدید، PyType_FromSlots() را ترجیح دهید.

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

ساختاری که رفتار یک نوع داده را تعریف می‌کند، و برای توابع منسوخ‌شده‌ی نرم مانند PyType_FromMetaclass() استفاده می‌شود.

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

const char *name

متناظر با Py_tp_name.

int basicsize

اگر مثبت باشد، متناظر با Py_tp_basicsize است.

اگر منفی باشد، متناظر با Py_tp_extra_basicsize است که روی مقدار مطلق تنظیم شده است.

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

int itemsize

متناظر با Py_tp_itemsize.

unsigned int flags

متناظر با Py_tp_flags.

PyType_Slot *slots

آرایه‌ای از ساختارهای PyType_Slot (نه PySlot).

با مقدار جایگاه خاص {0, NULL} پایان می‌یابد. هر شناسه‌ی جایگاه باید حداکثر یک بار مشخص شود.

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

ساختاری که قابلیت اختیاری یک نوع را تعریف می‌کند و برای توابع منسوخ‌شده‌ی ملایم مانند PyType_FromMetaclass() استفاده می‌شود.

توجه داشته باشید که ممکن است یک آرایه‌ی PyType_Slot با استفاده از Py_tp_slots در یک آرایه‌ی PySlot گنجانده شود، و بالعکس با استفاده از Py_slot_subslots.

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

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

که در آن sub_static برابر با PySlot_STATIC است اگر جایگاه به پرچم نیاز داشته باشد (مانند Py_tp_methods)، یا اگر این پرچم روی جایگاه «والد» Py_tp_slots (در صورت وجود) حضور داشته باشد.

int slot

متناظر با PySlot.sl_id.

void *pfunc

متناظر با PySlot.sl_ptr.