ساختارهای مشترک اشیاء

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

نوع‌های شیء پایه و ماکروها

همه‌ی اشیاء پایتون در نهایت تعداد اندکی فیلد را در ابتدای بازنمایی شیء در حافظه به اشتراک می‌گذارند. این فیلدها با نوع‌های PyObject و PyVarObject بازنمایی می‌شوند که آن نوع‌ها نیز به نوبه‌ی خود توسط بسط برخی ماکروها تعریف می‌شوند؛ ماکروهایی که چه به‌طور مستقیم و چه به‌طور غیرمستقیم، در تعریف همه‌ی اشیاء دیگر پایتون نیز به کار رفته‌اند. ماکروهای دیگر را می‌توانید در شمارش ارجاع بیابید.

type PyObject
قسمتی از API محدود. (تنها برخی از اعضا قسمتی از ABI پایدار هستند.)

همه‌ی نوع‌های شیء توسعه‌هایی از این نوع هستند. این نوعی است که اطلاعات مورد نیاز پایتون برای در نظر گرفتن یک اشاره‌گر به یک شیء به‌عنوان یک شیء را در بر می‌گیرد. در یک ساختِ «انتشار» معمولی، این نوع تنها شمارش ارجاع شیء و یک اشاره‌گر به شیء نوع متناظر را در بر دارد. در واقع هیچ‌چیز به‌عنوان یک PyObject اعلام نمی‌شود، اما هر اشاره‌گر به یک شیء پایتون را می‌توان به PyObject* قالب‌ریزی کرد.

اعضا نباید به‌طور مستقیم مورد دسترسی قرار گیرند؛ در عوض از ماکروهایی مانند Py_REFCNT و Py_TYPE استفاده کنید.

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

شمارش ارجاع شیء، همان‌طور که توسط Py_REFCNT برگردانده می‌شود. از این فیلد مستقیماً استفاده نکنید؛ در عوض از توابع و ماکروهایی مانند Py_REFCNT، Py_INCREF() و Py_DecRef() استفاده کنید.

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

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

نوع شیء. از این فیلد مستقیماً استفاده نکنید؛ به‌جای آن از Py_TYPE و Py_SET_TYPE() استفاده کنید.

type PyVarObject
قسمتی از API محدود. (تنها برخی از اعضا قسمتی از ABI پایدار هستند.)

توسعه‌ای از PyObject که فیلد ob_size را به آن می‌افزاید. این برای شیءهایی در نظر گرفته شده است که نوعی مفهوم از طول دارند.

همان‌طور که در مورد PyObject صادق است، نباید به اعضا مستقیماً دسترسی داشته باشید؛ در عوض از ماکروهایی مانند Py_SIZE، Py_REFCNT و Py_TYPE استفاده کنید.

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

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

از این فیلد به‌طور مستقیم استفاده نکنید؛ در عوض از Py_SIZE استفاده کنید.

توابع ایجاد شیء مانند PyObject_NewVar() به‌طور کلی این فیلد را به اندازه‌ی درخواستی (تعداد آیتم‌ها) تنظیم می‌کنند. پس از ایجاد، می‌توان مقادیر دلخواه را در ob_size با استفاده از Py_SET_SIZE ذخیره کرد.

برای به‌دست‌آوردن طولِ عمومیِ در دسترسِ یک شیء، که تابع پایتونی len() بازمی‌گرداند، به‌جای آن از PyObject_Length() استفاده کنید.

PyObject_HEAD

این ماکرو هنگام اعلان نوع‌های جدیدی که اشیاء بدون طول متغیر را بازنمایی می‌کنند، به کار می‌رود. ماکرو PyObject_HEAD به شکل زیر بسط می‌یابد:

PyObject ob_base;

به مستندات PyObject در بالا مراجعه کنید.

PyObject_VAR_HEAD

این ماکرو هنگام اعلان نوع‌های جدیدی به کار می‌رود که شیءهایی را نمایندگی می‌کنند که طولشان از نمونه‌ای به نمونه‌ای دیگر تغییر می‌کند. ماکرو PyObject_VAR_HEAD به شکل زیر بسط می‌یابد:

PyVarObject ob_base;

به مستندات PyVarObject در بالا مراجعه کنید.

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

کلاس پایه‌ی همه‌ی اشیاء دیگر، همانند object در پایتون.

int Py_Is(PyObject *x, PyObject *y)
قسمتی از ABI پایدار از نسخه‌ی 3.10.

بررسی می‌کند که آیا شیء x همان شیء y است، همانند x is y در پایتون.

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

int Py_IsNone(PyObject *x)
قسمتی از ABI پایدار از نسخه‌ی 3.10.

بررسی می‌کند که آیا یک شیء، تک‌نمونه‌ی None است یا نه؛ همانند x is None در پایتون.

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

int Py_IsTrue(PyObject *x)
قسمتی از ABI پایدار از نسخه‌ی 3.10.

بررسی می‌کند که آیا یک شیء تک‌نمونه‌ی True است یا نه؛ همانند x is True در پایتون.

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

int Py_IsFalse(PyObject *x)
قسمتی از ABI پایدار از نسخه‌ی 3.10.

بررسی می‌کند که آیا یک شیء، تک‌نمونه‌ی False است، همانند x is False در پایتون.

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

PyTypeObject *Py_TYPE(PyObject *o)
مقدار بازگشتی: مرجع امانتی. قسمتی از ABI پایدار از نسخه‌ی 3.14.

نوع شیء پایتون o را به دست می‌آورد.

ارجاع بازگردانده‌شده از o امانی است. آن را با Py_DECREF() یا مشابه آن آزاد نکنید.

تغییر یافته در نسخه‌ی 3.11: Py_TYPE() به یک تابع ایستای درون‌خطی تغییر کرده است. نوع پارامتر دیگر const PyObject* نیست.

int Py_IS_TYPE(PyObject *o, PyTypeObject *type)

اگر نوع شیء o برابر با type باشد، مقدار غیرصفر برمی‌گرداند. در غیر این صورت صفر برمی‌گرداند. معادل با: Py_TYPE(o) == type.

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

void Py_SET_TYPE(PyObject *o, PyTypeObject *type)

نوع شیء o را بدون هیچ بررسی یا شمارش ارجاع، به type تنظیم می‌کند.

این یک عملیات بسیار سطح‌پایین است. به‌جای این کار، تنظیم ویژگی پایتونی __class__ با استفاده از PyObject_SetAttrString() یا مشابه آن را در نظر بگیرید.

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

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

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

Py_ssize_t Py_SIZE(PyVarObject *o)

گرفتن فیلد ob_size از o.

تغییر یافته در نسخه‌ی 3.11: Py_SIZE() به یک تابع ایستای درون‌خطی تغییر یافته است. نوع پارامتر دیگر const PyVarObject* نیست.

void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)

فیلد ob_size از o را برابر size قرار می‌دهد.

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

PyObject_HEAD_INIT(type)

این یک ماکرو است که به مقادیر مقداردهی اولیه برای یک نوع جدید PyObject بسط می‌یابد. این ماکرو به صورت زیر بسط می‌یابد:

_PyObject_EXTRA_INIT
1, type,
PyVarObject_HEAD_INIT(type, size)

این یک ماکرو است که به مقادیر مقداردهی اولیه برای یک نوع جدید PyVarObject بسط می‌یابد و فیلد ob_size را نیز در بر می‌گیرد. این ماکرو به این صورت بسط می‌یابد:

_PyObject_EXTRA_INIT
1, type, size,

پیاده‌سازی توابع و متدها

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

نوع توابعی که برای پیاده‌سازی بیشتر فراخوانی‌پذیرهای پایتون در C به کار می‌روند. توابع از این نوع دو پارامتر PyObject* می‌گیرند و یک مقدار از این نوع برمی‌گردانند. اگر مقدار بازگشتی NULL باشد، یک استثنا باید تنظیم شده باشد. اگر NULL نباشد، مقدار بازگشتی به‌عنوان مقدار بازگشتی تابع از دید پایتون تفسیر می‌شود. تابع باید یک ارجاع جدید برگرداند.

امضای تابع به این صورت است:

PyObject *PyCFunction(PyObject *self,
                      PyObject *args);
type PyCFunctionWithKeywords
قسمتی از ABI پایدار.

نوع توابعی که برای پیاده‌سازی فراخوانی‌پذیرهای پایتون در C با امضای METH_VARARGS | METH_KEYWORDS استفاده می‌شوند. امضای تابع به این صورت است:

PyObject *PyCFunctionWithKeywords(PyObject *self,
                                  PyObject *args,
                                  PyObject *kwargs);
type PyCFunctionFast
قسمتی از ABI پایدار از نسخه‌ی 3.13.

نوع توابعی که برای پیاده‌سازی فراخوانی‌پذیرهای پایتون در C با امضای METH_FASTCALL استفاده می‌شوند. امضای تابع چنین است:

PyObject *PyCFunctionFast(PyObject *self,
                          PyObject *const *args,
                          Py_ssize_t nargs);
type PyCFunctionFastWithKeywords
قسمتی از ABI پایدار از نسخه‌ی 3.13.

نوع توابعی که برای پیاده‌سازی فراخوانی‌پذیرهای پایتون در C با امضای METH_FASTCALL | METH_KEYWORDS استفاده می‌شوند. امضای تابع به این صورت است:

PyObject *PyCFunctionFastWithKeywords(PyObject *self,
                                      PyObject *const *args,
                                      Py_ssize_t nargs,
                                      PyObject *kwnames);
type PyCMethod

نوع توابعی که برای پیاده‌سازی فراخوانی‌پذیرهای پایتون در C با امضای METH_METHOD | METH_FASTCALL | METH_KEYWORDS استفاده می‌شوند. امضای تابع چنین است:

PyObject *PyCMethod(PyObject *self,
                    PyTypeObject *defining_class,
                    PyObject *const *args,
                    Py_ssize_t nargs,
                    PyObject *kwnames)

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

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

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

const char *ml_name

نام متد.

PyCFunction ml_meth

اشاره‌گر به پیاده‌سازی C.

int ml_flags

بیت‌های پرچم که مشخص می‌کنند فراخوانی چگونه باید ساخته شود.

const char *ml_doc

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

ml_meth یک اشاره‌گر به تابع C است. توابع ممکن است از نوع‌های مختلفی باشند، اما همیشه PyObject* برمی‌گردانند. اگر تابع از نوع PyCFunction نباشد، کامپایلر در جدول متدها به قالب‌ریزی نیاز خواهد داشت. هرچند PyCFunction پارامتر اول را به‌صورت PyObject* تعریف می‌کند، رایج است که پیاده‌سازی متد از نوع مشخص C شیء self استفاده کند.

فیلد ml_flags یک میدان بیتی (bitfield) است که می‌تواند شامل پرچم‌های زیر باشد. هر یک از پرچم‌ها نشان‌دهنده‌ی یک قرارداد فراخوانی یا یک قرارداد مقیدسازی است.

قراردادهای فراخوانی عبارت‌اند از:

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

این قرارداد فراخوانی متداول است که در آن متدها از نوع PyCFunction هستند. این تابع دو مقدار PyObject* دریافت می‌کند. مقدار نخست، شیء self برای متدهاست؛ برای توابع ماژول، این مقدار شیء ماژول است. پارامتر دوم (که اغلب args نامیده می‌شود) یک شیء تاپل است که تمام آرگومان‌ها را نمایندگی می‌کند. این پارامتر معمولاً با استفاده از PyArg_ParseTuple() یا PyArg_UnpackTuple() پردازش می‌شود.

METH_KEYWORDS

فقط می‌تواند در ترکیب‌های خاصی با پرچم‌های دیگر استفاده شود: METH_VARARGS | METH_KEYWORDS، METH_FASTCALL | METH_KEYWORDS و METH_METHOD | METH_FASTCALL | METH_KEYWORDS.

METH_VARARGS | METH_KEYWORDS

متدهای دارای این پرچم‌ها باید از نوع PyCFunctionWithKeywords باشند. این تابع سه پارامتر می‌پذیرد: self، args و kwargs که در آن kwargs دیکشنری‌ای از تمام آرگومان‌های کلیدواژه‌ای است یا در صورت نبود آرگومان‌های کلیدواژه‌ای ممکن است NULL باشد. این پارامترها معمولاً با استفاده از PyArg_ParseTupleAndKeywords() پردازش می‌شوند.

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

قرارداد فراخوانی سریع که فقط از آرگومان‌های جایگاهی پشتیبانی می‌کند. متدها از نوع PyCFunctionFast هستند. پارامتر اول self است، پارامتر دوم یک آرایه C از مقادیر PyObject* است که آرگومان‌ها را نشان می‌دهد و پارامتر سوم تعداد آرگومان‌ها است (طول آرایه).

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

تغییر یافته در نسخه‌ی 3.10: METH_FASTCALL اکنون بخشی از رابط دودویی پایدار است.

METH_FASTCALL | METH_KEYWORDS

توسعه‌ای از METH_FASTCALL که از آرگومان‌های کلیدواژه‌ای نیز پشتیبانی می‌کند، با متدهایی از نوع PyCFunctionFastWithKeywords. آرگومان‌های کلیدواژه‌ای به همان شیوه‌ی پروتکل vectorcall منتقل می‌شوند: یک پارامتر چهارم اضافی از نوع PyObject* وجود دارد که یک تاپل است و نام‌های آرگومان‌های کلیدواژه‌ای را نشان می‌دهد (که تضمین می‌شود رشته باشند) یا در صورت نبود کلیدواژه‌ها ممکن است NULL باشد. مقادیر آرگومان‌های کلیدواژه‌ای در آرایه‌ی args، پس از آرگومان‌های جایگاهی، ذخیره می‌شوند.

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

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

تنها می‌تواند در ترکیب با سایر پرچم‌ها استفاده شود: METH_METHOD | METH_FASTCALL | METH_KEYWORDS.

METH_METHOD | METH_FASTCALL | METH_KEYWORDS

توسعه‌ای از METH_FASTCALL | METH_KEYWORDS است که از کلاس تعریف‌کننده پشتیبانی می‌کند؛ یعنی کلاسی که متد مورد نظر در آن قرار دارد. کلاس تعریف‌کننده ممکن است ابرکلاس Py_TYPE(self) باشد.

متد باید از نوع PyCMethod باشد، همان‌طور که برای METH_FASTCALL | METH_KEYWORDS است، با آرگومان defining_class که پس از self اضافه می‌شود.

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

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

متدهای بدون پارامتر، در صورتی که با پرچم METH_NOARGS فهرست شده باشند، لازم نیست بررسی کنند که آیا آرگومانی داده شده است یا خیر. آن‌ها باید از نوع PyCFunction باشند. پارامتر اول معمولاً self نام دارد و ارجاعی به ماژول یا نمونه‌ی شیء را نگه می‌دارد. در همه‌ی موارد، پارامتر دوم NULL خواهد بود.

تابع باید ۲ پارامتر داشته باشد. از آنجا که پارامتر دوم استفاده نمی‌شود، می‌توان از Py_UNUSED برای جلوگیری از هشدار کامپایلر استفاده کرد.

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

می‌توان متدهایی که تنها یک آرگومان شیء دارند، با پرچم METH_O فهرست کرد، به‌جای فراخوانی PyArg_ParseTuple() با آرگومان "O". این متدها از نوع PyCFunction هستند و پارامتر self و پارامتری از نوع PyObject* دارند که نمایانگر تنها آرگومان است.

این دو ثابت هنگامی که با متدهای کلاس‌ها استفاده می‌شوند، برای نشان دادن قرارداد فراخوانی (calling convention) به کار نمی‌روند، بلکه مقید‌سازی را نشان می‌دهند. از این ثابت‌ها نمی‌توان برای توابع تعریف‌شده برای ماژول‌ها استفاده کرد. برای هر متد معین، حداکثر یکی از این پرچم‌ها می‌تواند تنظیم شود.

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

به این متد، به جای نمونه‌ای از نوع، شیء نوع به عنوان اولین پارامتر پاس داده خواهد شد. از این برای ایجاد متدهای کلاس استفاده می‌شود، مشابه آنچه هنگام استفاده از دکوراتور توکار @classmethod ایجاد می‌شود.

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

به این متد، NULL به‌عنوان پارامتر اول ارسال می‌شود، نه نمونه‌ای از آن نوع. این برای ایجاد متدهای ایستا استفاده می‌شود، مشابه آنچه هنگام استفاده از دکوراتور توکار @staticmethod ایجاد می‌شود.

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

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

این متد به جای تعریف‌های موجود بارگذاری خواهد شد. بدون METH_COEXIST، حالت پیش‌فرض، صرف‌نظر کردن از تعریف‌های تکراری است. از آنجا که پوشش‌های جایگاه (slot wrapper) پیش از جدول متد بارگذاری می‌شوند، مثلاً وجود یک جایگاه sq_contains متدی پوششی به نام __contains__() تولید می‌کند و مانع از بارگذاری یک PyCFunction متناظر با همان نام می‌شود. با تعریف این پرچم، PyCFunction به جای شیء پوششی بارگذاری خواهد شد و در کنار جایگاه هم‌زیستی خواهد کرد. این مفید است زیرا فراخوانی‌های PyCFunction نسبت به فراخوانی‌های شیء پوششی بهینه‌سازی بیشتری دارند.

PyTypeObject PyCMethod_Type

شیء نوع متناظر با اشیاء متد C در پایتون. این به‌صورت types.BuiltinMethodType در لایه پایتون در دسترس است.

int PyCMethod_Check(PyObject *op)

اگر op نمونه‌ای از نوع PyCMethod_Type یا زیرنوعی از آن باشد، مقدار true را برمی‌گرداند. این تابع همیشه موفق می‌شود.

int PyCMethod_CheckExact(PyObject *op)

این همان PyCMethod_Check() است، اما زیرنوع‌ها را در نظر نمی‌گیرد.

PyObject *PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls)
مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار از نسخه‌ی 3.9.

ml را به یک شیء callable پایتون تبدیل می‌کند. فراخواننده باید اطمینان حاصل کند که ml بیشتر از callable زنده می‌ماند. معمولاً ml به‌صورت یک متغیر ایستا تعریف می‌شود.

پارامتر self هنگام فراخوانی، به عنوان آرگومان self به تابع C در ml->ml_meth منتقل می‌شود. self می‌تواند NULL باشد.

ویژگی __module__ شیء فراخوانی‌پذیر را می‌توان از آرگومان module داده‌شده تنظیم کرد. module باید یک رشته پایتونی باشد که به‌عنوان نام ماژولی که تابع در آن تعریف شده است استفاده می‌شود. اگر در دسترس نباشد، می‌توان آن را روی None یا NULL تنظیم کرد.

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

function.__module__

پارامتر cls به‌عنوان آرگومان defining_class به تابع C ارسال می‌شود. اگر METH_METHOD روی ml->ml_flags تنظیم شده باشد، باید مقداردهی شود.

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

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

شیء نوع متناظر با شیءهای تابع C پایتون. این شیء در لایه پایتون به‌صورت types.BuiltinFunctionType در دسترس است.

int PyCFunction_Check(PyObject *op)

اگر op نمونه‌ای از نوع PyCFunction_Type یا زیرنوعی از آن باشد، مقدار درست را برمی‌گرداند. این تابع همیشه موفق می‌شود.

int PyCFunction_CheckExact(PyObject *op)

این همان PyCFunction_Check() است، اما زیرنوع‌ها را در نظر نمی‌گیرد.

PyObject *PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module)
مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

معادل PyCMethod_New(ml, self, module, NULL) است.

PyObject *PyCFunction_New(PyMethodDef *ml, PyObject *self)
مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار از نسخه‌ی 3.4.

معادل PyCMethod_New(ml, self, NULL, NULL) است.

int PyCFunction_GetFlags(PyObject *func)
قسمتی از ABI پایدار.

پرچم‌های تابع روی func را، همان‌طور که به ml_flags پاس داده‌شده‌اند، دریافت می‌کند.

اگر func یک شیء تابع C نباشد، این کار با یک استثنا شکست می‌خورد. func نباید NULL باشد.

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

int PyCFunction_GET_FLAGS(PyObject *func)

این همان PyCFunction_GetFlags() است، اما بدون بررسی خطا یا بررسی نوع.

PyCFunction PyCFunction_GetFunction(PyObject *func)
قسمتی از ABI پایدار.

گرفتن اشاره‌گر تابع روی func، همان‌طور که به ml_meth پاس داده شده است.

اگر func یک شیء تابع C نباشد، این کار با یک استثنا شکست می‌خورد. func نباید NULL باشد.

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

int PyCFunction_GET_FUNCTION(PyObject *func)

این همان PyCFunction_GetFunction() است، اما بدون بررسی خطا یا بررسی نوع.

PyObject *PyCFunction_GetSelf(PyObject *func)
قسمتی از ABI پایدار.

گرفتن شیء "self" روی func. این همان شیئی است که به آرگومان اول یک PyCFunction پاس داده می‌شود. برای اشیاء تابع C که از طریق یک PyMethodDef روی یک PyModuleDef ایجاد شده‌اند، این همان شیء ماژول حاصل است.

اگر func یک شیء تابع C نباشد، این کار با یک استثنا شکست می‌خورد. func نباید NULL باشد.

این تابع در صورت موفقیت، یک ارجاع امانتی به شیء "self" برمی‌گرداند و در صورت شکست، NULL را همراه با استثنای تنظیم‌شده برمی‌گرداند.

PyObject *PyCFunction_GET_SELF(PyObject *func)

این همان PyCFunction_GetSelf() است، اما بدون بررسی خطا و نوع.

دسترسی به ویژگی‌های نوع‌های توسعه‌ای

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

ساختاری که ویژگی‌ای از یک نوع را توصیف می‌کند که متناظر با عضوی از ساختار C است. هنگام تعریف یک کلاس، آرایه‌ای خاتمه‌یافته با NULL از این ساختارها را در جایگاه tp_members قرار دهید.

فیلدهای آن به ترتیب عبارت‌اند از:

const char *name

نام عضو. مقدار NULL پایان یک آرایه PyMemberDef[] را مشخص می‌کند.

رشته باید ایستا باشد، هیچ کپی‌ای از آن ساخته نمی‌شود.

int type

نوع عضو در ساختار C. برای مقادیر ممکن، نوع‌های عضو را ببینید.

Py_ssize_t offset

آفست بر حسب بایتی که عضو در ساختار شیء نوع در آن قرار دارد.

int flags

صفر یا بیشتر از پرچم‌های عضو، که با استفاده از OR بیتی ترکیب شده‌اند.

const char *doc

رشته مستند، یا NULL. این رشته باید ایستا باشد؛ هیچ کپی‌ای از آن تهیه نمی‌شود. معمولاً این رشته با استفاده از PyDoc_STR تعریف می‌شود.

به‌طور پیش‌فرض (زمانی که flags برابر 0 باشد)، اعضا هم اجازه‌ی خواندن و هم اجازه‌ی نوشتن را می‌دهند. برای دسترسی فقط‌خواندنی از پرچم Py_READONLY استفاده کنید. برخی نوع‌ها، مانند Py_T_STRING، مستلزم Py_READONLY هستند. فقط اعضای Py_T_OBJECT_EX (و T_OBJECT قدیمی) قابل حذف هستند.

برای نوع‌های تخصیص‌یافته در هیپ (که با استفاده از PyType_FromSpec() یا مشابه آن ایجاد می‌شوند)، PyMemberDef می‌تواند تعریفی برای عضو ویژه‌ی "__vectorcalloffset__" داشته باشد که متناظر با tp_vectorcall_offset در شیءهای نوع است. این عضو باید با Py_T_PYSSIZET و یکی از Py_READONLY یا Py_READONLY | Py_RELATIVE_OFFSET تعریف شود. برای مثال:

static PyMemberDef spam_type_members[] = {
    {"__vectorcalloffset__", Py_T_PYSSIZET,
     offsetof(Spam_object, vectorcall), Py_READONLY},
    {NULL}  /* Sentinel */
};

(ممکن است برای offsetof() به #include <stddef.h> نیاز داشته باشید.)

آفست‌های قدیمی tp_dictoffset و tp_weaklistoffset را می‌توان به‌طور مشابه با استفاده از اعضای "__dictoffset__" و "__weaklistoffset__" تعریف کرد، اما به ماژول‌های توسعه‌ای به‌شدت توصیه می‌شود که به‌جای آن‌ها از Py_TPFLAGS_MANAGED_DICT و Py_TPFLAGS_MANAGED_WEAKREF استفاده کنند.

تغییر یافته در نسخه‌ی 3.12: PyMemberDef همیشه در دسترس است. پیش از این، نیازمند درج "structmember.h" بود.

تغییر یافته در نسخه‌ی 3.14: Py_RELATIVE_OFFSET اکنون برای "__vectorcalloffset__"، "__dictoffset__" و "__weaklistoffset__" مجاز است.

PyObject *PyMember_GetOne(const char *obj_addr, struct PyMemberDef *m)
قسمتی از ABI پایدار.

یک ویژگی متعلق به شیء موجود در نشانی obj_addr را بازیابی می‌کند. این ویژگی توسط PyMemberDef m توصیف می‌شود. در صورت خطا NULL را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.12: PyMember_GetOne همیشه دسترس‌پذیر است. پیش‌تر، نیازمند گنجاندن "structmember.h" بود.

int PyMember_SetOne(char *obj_addr, struct PyMemberDef *m, PyObject *o)
قسمتی از ABI پایدار.

یک ویژگی متعلق به شیءِ واقع در نشانی obj_addr را برابر شیء o قرار می‌دهد. ویژگیِ تنظیم‌شونده توسط PyMemberDef m توصیف می‌شود. در صورت موفقیت 0 و در صورت شکست مقدار منفی برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.12: PyMember_SetOne همیشه در دسترس است. پیش‌تر، نیازمند گنجاندن "structmember.h" بود.

پرچم‌های عضو

از پرچم‌های زیر می‌توان با PyMemberDef.flags استفاده کرد:

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

قابل نوشتن نیست.

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

پیش از خواندن، یک رویداد حسابرسی object.__getattr__ منتشر می‌کند.

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

نشان می‌دهد که offset این ورودی PyMemberDef آفستی از داده‌های خاص زیرکلاس را مشخص می‌کند، نه از PyObject.

هنگام ایجاد کلاس با استفاده از basicsize منفی، تنها می‌تواند به‌عنوان بخشی از جایگاه Py_tp_members استفاده شود. استفاده از آن در چنین حالتی الزامی است. هنگام تنظیم tp_members از جایگاه در طول ایجاد کلاس، پایتون پرچم را پاک می‌کند و PyMemberDef.offset را برابر با آفست نسبت به ساختار PyObject قرار می‌دهد.

تغییر یافته در نسخه‌ی 3.10: ماکروهای RESTRICTED، READ_RESTRICTED و WRITE_RESTRICTED که با #include "structmember.h" در دسترس هستند، منسوخ شده‌اند. READ_RESTRICTED و RESTRICTED معادل Py_AUDIT_READ هستند؛ WRITE_RESTRICTED هیچ کاری انجام نمی‌دهد.

تغییر یافته در نسخه‌ی 3.12: ماکروی READONLY به Py_READONLY تغییر نام یافت. ماکروی PY_AUDIT_READ با پیشوند Py_ تغییر نام یافت. نام‌های جدید اکنون همیشه در دسترس هستند. پیش‌تر، این موارد نیازمند #include "structmember.h" بودند. سرآیند هنوز در دسترس است و نام‌های قدیمی را فراهم می‌کند.

نوع‌های عضو

PyMemberDef.type می‌تواند یکی از ماکروهای زیر باشد که متناظر با نوع‌های مختلف C هستند. هنگامی که در پایتون به این عضو دسترسی پیدا شود، به نوع معادل پایتونی تبدیل می‌شود. هنگامی که از پایتون مقداردهی شود، دوباره به نوع C تبدیل می‌شود. اگر این کار ممکن نباشد، استثنایی مانند TypeError یا ValueError ایجاد می‌شود.

ویژگی‌های تعریف‌شده به این روش را نمی‌توان با استفاده از مثلاً del یا delattr() حذف کرد، مگر آنکه با (D) علامت‌گذاری شده باشند.

نام ماکرو

نوع C

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

char

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

short

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

int

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

long

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

long long

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

unsigned char

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

unsigned int

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

unsigned short

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

unsigned long

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

unsigned long long

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

Py_ssize_t

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

float

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

double

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

char (به‌صورت ۰ یا ۱ نوشته می‌شود)

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

const char* (*)

str (RO)
Py_T_STRING_INPLACE
قسمتی از ABI پایدار از نسخه‌ی 3.12.

const char[] (*)

str (RO)
Py_T_CHAR
قسمتی از ABI پایدار از نسخه‌ی 3.12.

char (0-127)

str (**)
Py_T_OBJECT_EX
قسمتی از ABI پایدار از نسخه‌ی 3.12.

PyObject*

object (D)

(*): رشته‌ی C پایان‌یافته با صفر و کدگذاری‌شده با UTF8. با Py_T_STRING نمایش C یک اشاره‌گر است؛ با Py_T_STRING_INPLACE رشته مستقیماً در ساختار ذخیره می‌شود.

(**): رشته‌ای به طول ۱. فقط اسکی پذیرفته می‌شود.

(RO): مستلزم Py_READONLY است.

(D): قابل حذف است؛ در این صورت اشاره‌گر به NULL تنظیم می‌شود. خواندن اشاره‌گر NULL استثنای AttributeError را ایجاد می‌کند.

اضافه شده در نسخه‌ی 3.12: در نسخه‌های پیشین، ماکروها تنها با #include "structmember.h" در دسترس بودند و بدون پیشوند Py_ نام‌گذاری می‌شدند (مثلاً به‌صورت T_INT). این سرآیند همچنان در دسترس است و شامل نام‌های قدیمی، به‌همراه نوع‌های منسوخ زیر است:

T_OBJECT

مانند Py_T_OBJECT_EX است، اما NULL به None تبدیل می‌شود. این امر در پایتون به رفتاری غافلگیرکننده منجر می‌شود: حذف ویژگی عملاً آن را به None تنظیم می‌کند.

T_NONE

همیشه None است. باید همراه با Py_READONLY استفاده شود.

تعریف getterها و setterها

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

ساختاری برای تعریف دسترسی شبیه به پراپرتی برای یک نوع. همچنین توضیحات جایگاه PyTypeObject.tp_getset را ببینید.

const char *name

نام ویژگی

getter get

تابع C برای دریافت ویژگی.

setter set

تابع C اختیاری برای تنظیم یا حذف ویژگی. اگر NULL باشد، ویژگی فقط‌خواندنی است.

const char *doc

رشته مستند اختیاری

void *closure

اشاره‌گر اختیاری داده‌های کاربر، که داده‌های اضافی را برای getter و setter فراهم می‌کند.

typedef PyObject *(*getter)(PyObject*, void*)
قسمتی از ABI پایدار.

تابع get یک پارامتر PyObject* (نمونه) و یک اشاره‌گر داده‌ی کاربر (closure مرتبط) را می‌پذیرد:

باید در صورت موفقیت یک ارجاع جدید و در صورت شکست NULL همراه با یک استثنای تنظیم‌شده بازگرداند.

typedef int (*setter)(PyObject*, PyObject*, void*)
قسمتی از ABI پایدار.

توابع set دو پارامتر PyObject* (نمونه و مقداری که باید تنظیم شود) و یک اشاره‌گر داده کاربر (closure مرتبط) را دریافت می‌کنند:

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