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

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

type PyObject¶

قسمتی از ABI پایدار (see below).

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

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

در ABI پایدار برای ساخت‌های نخ‌آزاد (abi3t)، این struct کدر است؛ اندازه و چیدمان آن ممکن است بین نسخه‌های پایتون تغییر کند. در ABI پایدار برای ساخت‌های غیرنخ‌آزاد (abi3)، فیلدهای ob_refcnt و ob_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() استفاده کنید.

PyMutex ob_mutex¶

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

این فیلد برای استفاده توسط API بخش بحرانی (Py_BEGIN_CRITICAL_SECTION / Py_END_CRITICAL_SECTION) رزرو شده است. آن را مستقیماً با PyMutex_Lock قفل نکنید؛ انجام این کار می‌تواند باعث بن‌بست شود. اگر به قفل خودتان نیاز دارید، یک فیلد جداگانه‌ی PyMutex به struct شیء خود اضافه کنید.

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

type PyVarObject¶

قسمتی از ABI پایدار (see below).

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

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

در ABI پایدار برای ساخت‌های نخ‌آزاد (abi3t)، این struct کدر است؛ اندازه و چیدمان آن ممکن است بین نسخه‌های پایتون تغییر کند. در ABI پایدار برای ساخت‌های غیرنخ‌آزاد (abi3)، فیلدهای ob_base و ob_size در دسترس هستند، اما استفاده‌ی مستقیم از آن‌ها توصیه نمی‌شود.

PyObject ob_base¶

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

سرآیند مشترک شیء. معمولاً این فیلد مستقیماً فراخوانی نمی‌شود؛ در عوض می‌توانید PyVarObject را به PyObject تبدیل نوع کنید.

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)¶

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

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

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

void Py_SET_TYPE(PyObject *o, PyTypeObject *type)¶

This macro is available when compiling for the ABI پایدار از نسخه‌ی 3.9.

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

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

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

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

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

Py_ssize_t Py_SIZE(PyVarObject *o)¶

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

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

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

void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)¶

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

فیلد 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¶

نام متد.

یک مقدار NULL در ml_name پایان یک آرایه‌ی PyMethodDef را مشخص می‌کند.

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() است، اما بدون بررسی خطا و نوع.

PyTypeObject *PyCFunction_GET_CLASS(PyObject *func)¶

اگر ml_flags تابع func شامل METH_METHOD باشد، یک ارجاع امانتی به کلاس تعریف‌کننده‌ی آن برگردانید. در غیر این صورت، بدون تنظیم یک استثنا، NULL را برگردانید.

func باید یک شیء تابع C باشد و نباید NULL باشد. این تابع بررسی خطا یا بررسی نوع را انجام نمی‌دهد.

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

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

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" بود.