پروتکل شیء¶

PyObject *Py_GetConstant(unsigned int constant_id)¶

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

گرفتن یک strong reference به یک ثابت.

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

constant_id باید یکی از این شناسه‌های ثابت باشد:

شناسه‌ی ثابت	مقدار	شیء بازگردانده‌شده
Py_CONSTANT_NONE¶	`0`	`None`
Py_CONSTANT_FALSE¶	`1`	`False`
Py_CONSTANT_TRUE¶	`2`	`True`
Py_CONSTANT_ELLIPSIS¶	`3`	`Ellipsis`
Py_CONSTANT_NOT_IMPLEMENTED¶	`4`	`NotImplemented`
Py_CONSTANT_ZERO¶	`5`	`0`
Py_CONSTANT_ONE¶	`6`	`1`
Py_CONSTANT_EMPTY_STR¶	`7`	`''`
Py_CONSTANT_EMPTY_BYTES¶	`8`	`b''`
Py_CONSTANT_EMPTY_TUPLE¶	`9`	`()`

مقادیر عددی فقط برای پروژه‌هایی ارائه شده‌اند که نمی‌توانند از شناسه‌های ثابت استفاده کنند.

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

در سی‌پایتون، همه‌ی این ثابت‌ها نامیرا هستند.

PyObject *Py_GetConstantBorrowed(unsigned int constant_id)¶

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

مشابه Py_GetConstant()، اما یک ارجاع امانتی برمی‌گرداند.

این تابع عمدتاً برای سازگاری با نسخه‌های قبلی در نظر گرفته شده است: استفاده از Py_GetConstant() برای کد جدید توصیه می‌شود.

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

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

PyObject *Py_NotImplemented¶: تک‌نمونه‌ی NotImplemented، که برای اعلام اینکه عملیاتی برای ترکیب مشخصی از نوع‌ها پیاده‌سازی نشده است، استفاده می‌شود.

Py_RETURN_NOTIMPLEMENTED¶: بازگرداندن Py_NotImplemented از درون یک تابع C را به‌درستی مدیریت کنید (یعنی، یک strong reference جدید به NotImplemented ایجاد کنید و آن را بازگردانید).

Py_PRINT_RAW¶: پرچمی که همراه چندین تابعِ چاپ‌کننده‌ی شیء استفاده می‌شود (مانند PyObject_Print() و PyFile_WriteObject()). اگر پاس داده شود، این توابع به جای repr() از str() شیء استفاده می‌کنند.

int PyObject_Print(PyObject *o, FILE *fp, int flags)¶: شیء o را در پرونده fp چاپ می‌کند. در صورت خطا -1 را برمی‌گرداند. از آرگومان پرچم‌ها برای فعال‌سازی برخی گزینه‌های چاپ استفاده می‌شود. تنها گزینه‌ای که در حال حاضر پشتیبانی می‌شود Py_PRINT_RAW است؛ در صورت ارائه این گزینه، str() شیء به‌جای repr() آن نوشته می‌شود.

int PyObject_HasAttrWithError(PyObject *o, PyObject *attr_name)¶: قسمتی از ABI پایدار از نسخه‌ی 3.13.
اگر o ویژگی attr_name را داشته باشد، 1 و در غیر این صورت 0 برمی‌گرداند. این معادل عبارت پایتونی hasattr(o, attr_name) است. در صورت شکست، -1 برمی‌گرداند.

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

int PyObject_HasAttrStringWithError(PyObject *o, const char *attr_name)¶: قسمتی از ABI پایدار از نسخه‌ی 3.13.
این همان PyObject_HasAttrWithError() است، اما attr_name به‌جای PyObject* به‌صورت یک رشته‌ی بایتی کدگذاری‌شده با UTF-8 از نوع const char* مشخص می‌شود.

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

int PyObject_HasAttr(PyObject *o, PyObject *attr_name)¶: قسمتی از ABI پایدار.
اگر o ویژگی attr_name را داشته باشد، 1 و در غیر این صورت 0 برمی‌گرداند. این تابع همیشه با موفقیت انجام می‌شود.

توجه

استثناهایی که هنگام فراخوانی متدهای __getattr__() و __getattribute__() توسط این تابع رخ می‌دهند، منتشر نمی‌شوند، بلکه به sys.unraisablehook() داده می‌شوند. برای مدیریت صحیح خطا، به جای آن از PyObject_HasAttrWithError()، PyObject_GetOptionalAttr() یا PyObject_GetAttr() استفاده کنید.

int PyObject_HasAttrString(PyObject *o, const char *attr_name)¶: قسمتی از ABI پایدار.
این همان PyObject_HasAttr() است، اما attr_name به‌صورت یک رشته‌ی بایت کدگذاری‌شده با UTF-8 از نوع const char* مشخص می‌شود، نه یک PyObject*.

توجه

استثناهایی که هنگام فراخوانی متدهای __getattr__() و __getattribute__() توسط این تابع، یا هنگام ایجاد شیء موقت str رخ می‌دهند، به‌صورت بی‌صدا نادیده گرفته می‌شوند. برای مدیریت صحیح خطاها، به‌جای آن از PyObject_HasAttrStringWithError()، PyObject_GetOptionalAttrString() یا PyObject_GetAttrString() استفاده کنید.

PyObject *PyObject_GetAttr(PyObject *o, PyObject *attr_name)¶

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

یک ویژگی با نام attr_name را از شیء o بازیابی می‌کند. در صورت موفقیت، مقدار ویژگی و در صورت شکست، NULL را برمی‌گرداند. این معادل عبارت پایتونی o.attr_name است.

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

PyObject *PyObject_GetAttrString(PyObject *o, const char *attr_name)¶

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

این همان PyObject_GetAttr() است، اما attr_name به‌جای PyObject* به‌صورت یک رشته‌ی بایتِ کدگذاری‌شده با UTF-8 از نوع const char* مشخص می‌شود.

اگر ویژگی مفقود نباید به‌عنوان شکست در نظر گرفته شود، می‌توانید به جای آن از PyObject_GetOptionalAttrString() استفاده کنید.

int PyObject_GetOptionalAttr(PyObject *obj, PyObject *attr_name, PyObject **result);¶

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

گونه‌ای از PyObject_GetAttr() که اگر ویژگی پیدا نشود، استثنای AttributeError را ایجاد نمی‌کند.

اگر ویژگی یافت شود، 1 برگردانده می‌شود و *result روی یک ارجاع قوی جدید به ویژگی تنظیم می‌شود. اگر ویژگی یافت نشود، 0 برگردانده می‌شود و *result روی NULL تنظیم می‌شود؛ استثنای AttributeError سرکوب می‌شود. اگر خطایی غیر از AttributeError مطرح شود، -1 برگردانده می‌شود و *result روی NULL تنظیم می‌شود.

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

int PyObject_GetOptionalAttrString(PyObject *obj, const char *attr_name, PyObject **result);¶: قسمتی از ABI پایدار از نسخه‌ی 3.13.
این همان PyObject_GetOptionalAttr() است، اما attr_name به‌عنوان یک رشته‌ی بایتی کدگذاری‌شده با UTF-8 از نوع const char* مشخص می‌شود، نه یک PyObject*.

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

PyObject *PyObject_GenericGetAttr(PyObject *o, PyObject *name)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
تابع عمومیِ getter ویژگی که قرار است در جایگاه tp_getattro شیء نوع قرار گیرد. این تابع به‌دنبال یک توصیف‌گر در فرهنگ‌لغت کلاس‌های موجود در MRO شیء، و همچنین یک ویژگی در __dict__ شیء (در صورت وجود) می‌گردد. همان‌طور که در پیاده‌سازی توصیف‌گرها توضیح داده شده است، توصیف‌گرهای داده‌ای نسبت به ویژگی‌های نمونه اولویت دارند، در حالی که توصیف‌گرهای غیر داده‌ای چنین اولویتی ندارند. در غیر این صورت، یک AttributeError ایجاد می‌شود.

int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)¶

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

مقدار ویژگی‌ای با نام attr_name را برای شیء o به مقدار v تنظیم می‌کند. در صورت شکست، یک استثنا ایجاد می‌کند و -1 را برمی‌گرداند؛ در صورت موفقیت 0 را برمی‌گرداند. این معادل دستور o.attr_name = v در پایتون است.

اگر v برابر NULL باشد، ویژگی حذف می‌شود. این رفتار به نفع استفاده از PyObject_DelAttr() منسوخ شده است، اما در حال حاضر هیچ برنامه‌ای برای حذف آن وجود ندارد.

int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)¶

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

این همان PyObject_SetAttr() است، اما attr_name به‌صورت یک رشته‌ی بایتِ کدگذاری‌شده با UTF-8 از نوع const char* مشخص می‌شود، نه PyObject*.

اگر v برابر NULL باشد، ویژگی حذف می‌شود، اما این قابلیت به نفع استفاده از PyObject_DelAttrString() منسوخ شده است.

تعداد نام‌های ویژگی متفاوتی که به این تابع ارسال می‌شوند باید کم نگه داشته شود؛ این کار معمولاً با استفاده از یک رشته با تخصیص ایستا به‌عنوان attr_name انجام می‌شود. برای نام‌های ویژگی که در زمان کامپایل مشخص نیستند، ترجیح دهید PyUnicode_FromString() و PyObject_SetAttr() را مستقیماً فراخوانی کنید. برای جزئیات بیشتر، PyUnicode_InternFromString() را ببینید که ممکن است به‌صورت داخلی برای ایجاد یک شیء کلید استفاده شود.

int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)¶: قسمتی از ABI پایدار.
تابع عمومی setter و deleter ویژگی که برای قرار گرفتن در جایگاه tp_setattro از یک شیء نوع در نظر گرفته شده است. این تابع به دنبال یک توصیف‌گر داده در دیکشنری کلاس‌های موجود در MRO شیء می‌گردد و در صورت یافته شدن، آن نسبت به تنظیم یا حذف ویژگی در دیکشنری نمونه اولویت دارد. در غیر این صورت، ویژگی در __dict__ شیء (در صورت وجود) تنظیم یا حذف می‌شود. در صورت موفقیت، 0 برگردانده می‌شود؛ در غیر این صورت، AttributeError مطرح می‌شود و -1 برگردانده می‌شود.

int PyObject_DelAttr(PyObject *o, PyObject *attr_name)¶: قسمتی از ABI پایدار از نسخه‌ی 3.13.
ویژگی به نام attr_name را از شیء o حذف می‌کند. در صورت شکست -1 برمی‌گرداند. این معادل دستور del o.attr_name در پایتون است.

int PyObject_DelAttrString(PyObject *o, const char *attr_name)¶

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

این همان PyObject_DelAttr() است، اما attr_name به‌صورت یک رشته بایتی کدگذاری‌شده با UTF-8 از نوع const char* مشخص می‌شود، نه به‌صورت یک PyObject*.

تعداد نام‌های ویژگی متفاوتی که به این تابع پاس داده می‌شوند باید کم نگه داشته شود؛ این کار معمولاً با استفاده از یک رشته تخصیص‌یافته به‌صورت ایستا به‌عنوان attr_name انجام می‌شود. برای نام‌های ویژگی که در زمان کامپایل شناخته نمی‌شوند، ترجیح دهید PyUnicode_FromString() و PyObject_DelAttr() را مستقیماً فراخوانی کنید. برای جزئیات بیشتر، PyUnicode_InternFromString() را ببینید که ممکن است به‌صورت داخلی برای ایجاد یک شیء کلید جهت جستجو استفاده شود.

PyObject *PyObject_GenericGetDict(PyObject *o, void *context)¶

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

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

برای گرفتن __dict__ شیء o نیز می‌توان این تابع را فراخوانی کرد. هنگام فراخوانی آن، مقدار NULL را برای context ارسال کنید. از آنجا که این تابع ممکن است برای دیکشنری به تخصیص حافظه نیاز داشته باشد، هنگام دسترسی به یک ویژگی بر روی شیء، ممکن است فراخوانی PyObject_GetAttr() کارآمدتر باشد.

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

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

int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context)¶: قسمتی از ABI پایدار از نسخه‌ی 3.7.
پیاده‌سازی عام برای setter یک توصیف‌گر __dict__. این پیاده‌سازی اجازه حذف دیکشنری را نمی‌دهد.

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

PyObject **_PyObject_GetDictPtr(PyObject *obj)¶

اشاره‌گر به __dict__ شیء obj را بازمی‌گرداند. اگر __dict__ وجود نداشته باشد، NULL را بدون تنظیم استثنا بازمی‌گرداند.

این تابع ممکن است نیاز به تخصیص حافظه برای دیکشنری داشته باشد، بنابراین ممکن است هنگام دسترسی به یک ویژگی بر روی شیء، فراخوانی PyObject_GetAttr() کارآمدتر باشد.

PyObject *PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
مقادیر o1 و o2 را با استفاده از عملیات مشخص‌شده توسط opid مقایسه می‌کند، که باید یکی از Py_LT، Py_LE، Py_EQ، Py_NE، Py_GT یا Py_GE باشد که به‌ترتیب متناظر با <، <=، ==، !=، > یا >= هستند. این معادل عبارت پایتونی o1 op o2 است، که در آن op عملگر متناظر با opid است. در صورت موفقیت مقدار مقایسه و در صورت شکست NULL را برمی‌گرداند.

int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)¶: قسمتی از ABI پایدار.
مقادیر o1 و o2 را با استفاده از عملیات مشخص‌شده توسط opid مقایسه می‌کند، مانند PyObject_RichCompare()، اما در صورت خطا -1، اگر نتیجه نادرست باشد 0 و در غیر این صورت 1 برمی‌گرداند.

توجه

اگر o1 و o2 یک شیء واحد باشند، PyObject_RichCompareBool() همیشه برای Py_EQ مقدار 1 و برای Py_NE مقدار 0 را برمی‌گرداند.

PyObject *PyObject_Format(PyObject *obj, PyObject *format_spec)¶

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

obj را با استفاده از format_spec قالب‌بندی می‌کند. این معادل عبارت پایتونی format(obj, format_spec) است.

format_spec ممکن است NULL باشد. در این حالت، این فراخوانی معادل format(obj) است. در صورت موفقیت، رشته قالب‌بندی‌شده و در صورت شکست NULL را برمی‌گرداند.

PyObject *PyObject_Repr(PyObject *o)¶

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

نمایش رشته‌ای شیء o را محاسبه می‌کند. در صورت موفقیت نمایش رشته‌ای و در صورت شکست NULL برمی‌گرداند. این معادل عبارت پایتونی repr(o) است. توسط تابع توکار repr() فراخوانی می‌شود.

اگر آرگومان NULL باشد، رشته‌ی '<NULL>' را برمی‌گرداند.

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

PyObject *PyObject_ASCII(PyObject *o)¶

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

مانند PyObject_Repr()، بازنمایی رشته‌ای از شیء o را محاسبه می‌کند، اما نویسه‌های غیراسکی در رشته‌ای که PyObject_Repr() برمی‌گرداند را با گریزهای \x، \u یا \U خنثی می‌کند. این کار رشته‌ای مشابه آنچه PyObject_Repr() در پایتون 2 برمی‌گرداند تولید می‌کند. توسط تابع توکار ascii() فراخوانی می‌شود.

اگر آرگومان NULL باشد، رشته‌ی '<NULL>' را برمی‌گرداند.

PyObject *PyObject_Str(PyObject *o)¶

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

نمایش رشته‌ای شیء o را محاسبه می‌کند. در صورت موفقیت، نمایش رشته‌ای را برمی‌گرداند و در صورت شکست، NULL را. این معادل عبارت پایتونی str(o) است. این تابع توسط تابع توکار str() و در نتیجه توسط تابع print() فراخوانی می‌شود.

اگر آرگومان NULL باشد، رشته‌ی '<NULL>' را برمی‌گرداند.

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

PyObject *PyObject_Bytes(PyObject *o)¶

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

یک نمایش بایتی از شیء o را محاسبه می‌کند. در صورت شکست NULL و در صورت موفقیت یک شیء بایت بازگردانده می‌شود. این کار معادل عبارت پایتونی bytes(o) است، هنگامی که o عدد صحیح نباشد. برخلاف bytes(o)، هنگامی که o عدد صحیح باشد، به‌جای یک شیء بایتِ مقداردهی‌شده با صفر، استثنای TypeError ایجاد می‌شود.

اگر آرگومان NULL باشد، شیء bytes یعنی b'<NULL>' را بازمی‌گرداند.

int PyObject_IsSubclass(PyObject *derived, PyObject *cls)¶

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

اگر کلاس derived با کلاس cls یکسان باشد یا از آن مشتق‌شده باشد، 1 را برمی‌گرداند؛ در غیر این صورت 0 را برمی‌گرداند. در صورت خطا، -1 را برمی‌گرداند.

اگر cls یک تاپل باشد، بررسی نسبت به هر یک از ورودی‌های cls انجام می‌شود. نتیجه 1 خواهد بود اگر حداقل یکی از بررسی‌ها 1 برگرداند، در غیر این صورت 0 خواهد بود.

اگر cls دارای متد __subclasscheck__() باشد، این متد برای تعیین وضعیت زیرکلاس بودن، همان‌گونه که در PEP 3119 توصیف شده است، فراخوانی می‌شود. در غیر این صورت، derived در صورتی زیرکلاس cls است که زیرکلاس مستقیم یا غیرمستقیم آن باشد؛ یعنی در cls.__mro__ قرار داشته باشد.

معمولاً فقط اشیاء کلاس، یعنی نمونه‌های type یا یک کلاس مشتق‌شده، به عنوان کلاس در نظر گرفته می‌شوند. اما اشیاء می‌توانند با داشتن ویژگی __bases__ (که باید تاپلی از کلاس‌های پایه باشد) این موضوع را لغو کنند.

int PyObject_IsInstance(PyObject *inst, PyObject *cls)¶

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

اگر inst نمونه‌ای از کلاس cls یا زیرکلاسی از cls باشد، 1 را برمی‌گرداند و در غیر این صورت 0 را برمی‌گرداند. در صورت خطا، -1 را برمی‌گرداند و یک استثنا تنظیم می‌کند.

اگر cls یک تاپل باشد، بررسی نسبت به هر یک از ورودی‌های cls انجام می‌شود. نتیجه 1 خواهد بود اگر حداقل یکی از بررسی‌ها 1 برگرداند، در غیر این صورت 0 خواهد بود.

اگر cls متد __instancecheck__() را داشته باشد، این متد برای تعیین وضعیت زیرکلاس بودن، همان‌طور که در PEP 3119 توضیح داده شده است، فراخوانی می‌شود. در غیر این صورت، inst در صورتی نمونه‌ای از cls است که کلاس آن زیرکلاسی از cls باشد.

یک نمونه inst می‌تواند با داشتن ویژگی __class__، آنچه را که به‌عنوان کلاس آن در نظر گرفته می‌شود بازنویسی کند.

یک شیء cls می‌تواند با داشتن ویژگی __bases__ (که باید تاپلی از کلاس‌های پایه باشد) بازنویسی کند که آیا به‌عنوان کلاس در نظر گرفته می‌شود، و کلاس‌های پایه‌اش چه هستند.

Py_hash_t PyObject_Hash(PyObject *o)¶: قسمتی از ABI پایدار.
مقدار هش یک شیء o را محاسبه کرده و برمی‌گرداند. در صورت شکست، -1 برمی‌گرداند. این معادل عبارت پایتونی hash(o) است.

تغییر یافته در نسخه‌ی 3.2: نوع بازگشتی اکنون Py_hash_t است. این یک عدد صحیح علامت‌دار هم‌اندازه با Py_ssize_t است.

Py_hash_t PyObject_HashNotImplemented(PyObject *o)¶: قسمتی از ABI پایدار.
یک TypeError تنظیم می‌کند که نشان می‌دهد type(o) hashable نیست و -1 را برمی‌گرداند. این تابع هنگامی که در جایگاه tp_hash ذخیره شود، مورد رفتار ویژه‌ای قرار می‌گیرد و به یک نوع اجازه می‌دهد به‌طور صریح به مفسر نشان دهد که هش‌پذیر نیست.

int PyObject_IsTrue(PyObject *o)¶: قسمتی از ABI پایدار.
اگر شیء o درست در نظر گرفته شود، 1 و در غیر این صورت 0 را برمی‌گرداند. این معادل عبارت not not o در پایتون است. در صورت شکست، -1 را برمی‌گرداند.

int PyObject_Not(PyObject *o)¶: قسمتی از ABI پایدار.
اگر شیء o درست در نظر گرفته شود، 0 و در غیر این صورت 1 را برمی‌گرداند. این معادل عبارت پایتونی not o است. در صورت شکست، -1 برمی‌گرداند.

PyObject *PyObject_Type(PyObject *o)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
وقتی o برابر NULL نباشد، شیء نوعی متناظر با نوع شیءِ o برمی‌گرداند. در صورت شکست، استثنای SystemError را ایجاد می‌کند و NULL را برمی‌گرداند. این معادل عبارت پایتونی type(o) است. این تابع یک ارجاع قوی جدید به مقدار بازگشتی ایجاد می‌کند. واقعاً هیچ دلیلی برای استفاده از این تابع به‌جای تابع Py_TYPE() که اشاره‌گری از نوع PyTypeObject* برمی‌گرداند وجود ندارد، مگر زمانی که به یک ارجاع قوی جدید نیاز باشد.

int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)¶: اگر شیء o از نوع type یا زیرنوعی از type باشد، مقدار ناصفر و در غیر این صورت 0 برمی‌گرداند. هر دو پارامتر باید غیر NULL باشند.

Py_ssize_t PyObject_Size(PyObject *o)¶
Py_ssize_t PyObject_Length(PyObject *o)¶: قسمتی از ABI پایدار.
طول شیء o را برمی‌گرداند. اگر شیء o هر یک از پروتکل‌های دنباله و نگاشت را فراهم کند، طول دنباله برگردانده می‌شود. در صورت خطا، -1 برگردانده می‌شود. این معادل عبارت پایتونی len(o) است.

Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t defaultvalue)¶: طول تخمینی شیء o را برمی‌گرداند. ابتدا تلاش می‌کند طول واقعی آن را برگرداند، سپس تخمینی با استفاده از __length_hint__() و در نهایت مقدار پیش‌فرض را برمی‌گرداند. در صورت خطا -1 را برمی‌گرداند. این معادل عبارت پایتون operator.length_hint(o, defaultvalue) است.

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

PyObject *PyObject_GetItem(PyObject *o, PyObject *key)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
عنصر o متناظر با شیء key را برمی‌گرداند، یا در صورت شکست NULL برمی‌گرداند. این معادل عبارت پایتون o[key] است.

int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)¶: قسمتی از ABI پایدار.
شیء key را به مقدار v نگاشت می‌کند. در صورت شکست، یک استثنا ایجاد می‌کند و -1 را برمی‌گرداند؛ در صورت موفقیت 0 را برمی‌گرداند. این کار معادل دستور پایتونی o[key] = v است. این تابع ارجاعی به v را نمی‌دزدد.

int PyObject_DelItem(PyObject *o, PyObject *key)¶: قسمتی از ABI پایدار.
نگاشت مربوط به شیء key را از شیء o حذف می‌کند. در صورت شکست -1 برمی‌گرداند. این کار معادل دستور del o[key] در پایتون است.

int PyObject_DelItemString(PyObject *o, const char *key)¶: قسمتی از ABI پایدار.
این همان PyObject_DelItem() است، اما key به‌جای یک PyObject*، به‌صورت یک رشته بایتی کدگذاری‌شده با UTF-8 از نوع const char* مشخص می‌شود.

PyObject *PyObject_Dir(PyObject *o)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
این معادل عبارت پایتونی dir(o) است که فهرستی (احتمالاً خالی) از رشته‌های مناسب برای آرگومان شیء برمی‌گرداند، یا اگر خطایی رخ داده باشد، NULL برمی‌گرداند. اگر آرگومان NULL باشد، این مانند dir() پایتون عمل می‌کند و نام‌های متغیرهای محلی فعلی را برمی‌گرداند؛ در این حالت، اگر هیچ فریم اجرا (execution frame) فعالی وجود نداشته باشد، NULL برگردانده می‌شود، اما PyErr_Occurred() مقدار false را برمی‌گرداند.

PyObject *PyObject_GetIter(PyObject *o)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
این معادل عبارت پایتونی iter(o) است. یک پیمایش‌گر جدید برای آرگومان شیء برمی‌گرداند، یا اگر شیء از قبل یک پیمایش‌گر باشد، خودِ شیء را برمی‌گرداند. اگر شیء پیمایش‌پذیر نباشد، استثنای TypeError را مطرح می‌کند و NULL برمی‌گرداند.

PyObject *PyObject_SelfIter(PyObject *obj)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
این معادل متد __iter__(self): return self در پایتون است. این برای نوع‌های iterator در نظر گرفته شده است تا در جایگاه PyTypeObject.tp_iter استفاده شود.

PyObject *PyObject_GetAIter(PyObject *o)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار از نسخه‌ی 3.10.
این معادل عبارت پایتونی aiter(o) است. یک شیء AsyncIterable می‌گیرد و یک AsyncIterator برای آن برمی‌گرداند. این معمولاً یک پیمایش‌گر جدید است، اما اگر آرگومان یک AsyncIterator باشد، خودِ آن بازگردانده می‌شود. اگر شیء قابل پیمایش نباشد، خطای TypeError ایجاد می‌کند و NULL را برمی‌گرداند.

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

void *PyObject_GetTypeData(PyObject *o, PyTypeObject *cls)¶

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

یک اشاره‌گر به داده‌های اختصاصی زیرکلاس که برای cls رزرو شده‌اند را دریافت کنید.

شیء o باید نمونه‌ای از cls باشد و cls باید با استفاده از PyType_Spec.basicsize منفی ایجاد شده باشد. پایتون این موضوع را بررسی نمی‌کند.

در صورت خطا، یک استثنا تنظیم کنید و NULL را برگردانید.

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

Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)¶

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

اندازه‌ی فضای حافظه‌ی نمونه‌ی رزرو‌شده برای cls را بازمی‌گرداند، یعنی اندازه‌ی حافظه‌ای که PyObject_GetTypeData() بازمی‌گرداند.

این اندازه ممکن است بزرگ‌تر از مقدار درخواست‌شده با استفاده از -PyType_Spec.basicsize باشد؛ استفاده از این اندازه‌ی بزرگ‌تر ایمن است (مثلاً با memset()).

نوع cls باید با استفاده از PyType_Spec.basicsize منفی ایجاد شده باشد. پایتون این را بررسی نمی‌کند.

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

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

void *PyObject_GetItemData(PyObject *o)¶

گرفتن اشاره‌گر به داده‌های هر آیتم برای کلاسی با Py_TPFLAGS_ITEMS_AT_END.

در صورت خطا، یک استثنا تنظیم کرده و NULL را برگردانید. استثنای TypeError در صورتی ایجاد می‌شود که پرچم Py_TPFLAGS_ITEMS_AT_END روی o تنظیم نشده باشد.

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

int PyObject_VisitManagedDict(PyObject *obj, visitproc visit, void *arg)¶

دیکشنری مدیریت‌شده‌ی obj را بازدید می‌کند.

این تابع باید فقط در تابع پیمایش نوعی فراخوانی شود که پرچم Py_TPFLAGS_MANAGED_DICT روی آن تنظیم شده باشد.

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

void PyObject_ClearManagedDict(PyObject *obj)¶

دیکشنری مدیریت‌شده‌ی obj را پاک کنید.

این تابع باید فقط در تابع پاک‌سازی (clear function) نوعی که پرچم Py_TPFLAGS_MANAGED_DICT روی آن تنظیم شده است، فراخوانی شود.

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

int PyUnstable_Object_EnableDeferredRefcount(PyObject *obj)¶

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

شمارش ارجاعِ معوق را روی obj فعال می‌کند، اگر ران‌تایم از آن پشتیبانی کند. در ساخت‌ِ نخ‌آزاد، این به مفسر اجازه می‌دهد تا از تعدیل شمارش ارجاعِ obj اجتناب کند، که ممکن است کارایی چندنخی را بهبود بخشد. بهای آن این است که obj فقط توسط زباله‌روبِ ردیابی (tracing garbage collector) آزادسازی خواهد شد، و نه زمانی که مفسر دیگر هیچ ارجاعی به آن ندارد.

این تابع در صورتی که شمارش ارجاعِ معوق روی obj فعال باشد، مقدار 1 را برمی‌گرداند و در صورتی که شمارش ارجاعِ معوق پشتیبانی نشده باشد یا مفسر راهنما را نادیده گرفته باشد (مانند زمانی که شمارش ارجاعِ معوق از قبل روی obj فعال باشد)، مقدار 0 را برمی‌گرداند. این تابع نخ‌ایمن است و نمی‌تواند شکست بخورد.

این تابع در نسخه‌های ساخته‌شده‌ای که GIL در آن‌ها فعال است و از شمارش ارجاعِ معوق پشتیبانی نمی‌کنند، هیچ کاری انجام نمی‌دهد. همچنین اگر obj شیئی نباشد که توسط زباله‌روب پیگیری می‌شود، این تابع هیچ کاری انجام نمی‌دهد (به gc.is_tracked() و PyObject_GC_IsTracked() مراجعه کنید).

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

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

int PyUnstable_Object_IsUniqueReferencedTemporary(PyObject *obj)¶

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

بررسی می‌کند که آیا obj یک شیء موقت یکتا است یا نه. اگر مشخص باشد که obj یک شیء موقت یکتا است، 1 و در غیر این صورت 0 را برمی‌گرداند. این تابع نمی‌تواند شکست بخورد، اما بررسی محافظه‌کارانه است و ممکن است در برخی موارد حتی اگر obj یک شیء موقت یکتا باشد، 0 برگرداند.

اگر شیئی موقتِ یکتا (unique temporary) باشد، تضمین می‌شود که کد فعلی تنها ارجاع به آن شیء را دارد. برای آرگومان‌های توابع C، باید از این به‌جای بررسی اینکه آیا شمارش ارجاع 1 است استفاده کرد. از پایتون 3.14 به بعد، مفسر به‌صورت داخلی هنگام بارگذاری اشیاء روی پشته عملوندها، در صورت امکان با امانت گرفتن ارجاع‌ها، از برخی از تغییرات شمارش ارجاع اجتناب می‌کند؛ این بدان معناست که شمارش ارجاع 1 به‌تنهایی تضمین نمی‌کند که آرگومان تابع به‌طور یکتا ارجاع شده باشد.

در مثال زیر، my_func با یک شیء موقت یکتا به‌عنوان آرگومان خود فراخوانی می‌شود:

my_func([1, 2, 3])

در مثال زیر، my_func با یک شیء موقت یکتا به‌عنوان آرگومان خود فراخوانی نمی‌شود، حتی اگر شمارش ارجاع آن 1 باشد:

my_list = [1, 2, 3]
my_func(my_list)

همچنین تابع Py_REFCNT() را ببینید.

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

int PyUnstable_IsImmortal(PyObject *obj)¶: این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.

این تابع در صورتی که obj نامیرا باشد، مقدار غیرصفر و در غیر این صورت صفر را برمی‌گرداند. این تابع نمی‌تواند شکست بخورد.

توجه

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

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

int PyUnstable_TryIncRef(PyObject *obj)¶

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

شمارش ارجاع obj را در صورتی که صفر نباشد افزایش می‌دهد. اگر شمارش ارجاع شیء با موفقیت افزایش یافته باشد، 1 را برمی‌گرداند. در غیر این صورت، این تابع 0 را برمی‌گرداند.

PyUnstable_EnableTryIncRef() باید پیش‌تر روی obj فراخوانی شده باشد؛ در غیر این صورت، این تابع ممکن است در ساخت‌ نخ‌آزاد به‌طور کاذب 0 را برگرداند.

این تابع از نظر منطقی معادل کد C زیر است، با این تفاوت که در free-threaded build به‌صورت اتمیک رفتار می‌کند:

if (Py_REFCNT(op) > 0) {
   Py_INCREF(op);
   return 1;
}
return 0;

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

معمولاً، استفاده‌ی صحیح از این تابع نیازمند پشتیبانی از سوی آزادساز حافظه مربوط به obj (tp_dealloc) است. برای مثال، می‌توان طرح زیر را برای پیاده‌سازی «weakmap»‌ای که مانند WeakValueDictionary برای یک نوع مشخص کار می‌کند، تطبیق داد:

PyMutex mutex;

PyObject *
add_entry(weakmap_key_type *key, PyObject *value)
{
    PyUnstable_EnableTryIncRef(value);
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    weakmap_add_entry(weakmap, key, value);
    PyMutex_Unlock(&mutex);
    Py_RETURN_NONE;
}

PyObject *
get_value(weakmap_key_type *key)
{
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    PyObject *result = weakmap_find(weakmap, key);
    if (PyUnstable_TryIncRef(result)) {
        // `result` is safe to use
        PyMutex_Unlock(&mutex);
        return result;
    }
    // if we get here, `result` is starting to be garbage-collected,
    // but has not been removed from the weakmap yet
    PyMutex_Unlock(&mutex);
    return NULL;
}

// tp_dealloc function for weakmap values
void
value_dealloc(PyObject *value)
{
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    weakmap_remove_value(weakmap, value);

    ...
    PyMutex_Unlock(&mutex);
}

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

void PyUnstable_EnableTryIncRef(PyObject *obj)¶: این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.

امکان استفاده‌های بعدی از PyUnstable_TryIncRef() روی obj را فراهم می‌کند. فراخواننده باید هنگام فراخوانی این تابع، یک ارجاع قوی به obj داشته باشد.

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

int PyUnstable_Object_IsUniquelyReferenced(PyObject *op)¶

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

تشخیص می‌دهد که آیا op فقط یک ارجاع دارد یا خیر.

در ساخت‌های دارای قفل مفسر سراسری، این تابع معادل Py_REFCNT(op) == 1 است.

در ساخت‌ نخ‌آزاد، این تابع بررسی می‌کند که شمارش ارجاع op برابر با یک باشد و به‌علاوه بررسی می‌کند که op تنها توسط این نخ استفاده می‌شود. Py_REFCNT(op) == 1 در ساخت‌های نخ‌آزاد نخ‌ایمن نیست؛ استفاده از این تابع را ترجیح دهید.

فراخوانی‌کننده باید یک attached thread state را در اختیار داشته باشد، با وجود اینکه این تابع مفسر پایتون را فراخوانی نمی‌کند. این تابع نمی‌تواند شکست بخورد.

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

پروتکل شیء¶

موضوع قبلی

موضوع بعدی

این صفحه