شیءهای توصیف‌گر

«توصیف‌گرها» اشیایی هستند که ویژگی‌ای از یک شیء را توصیف می‌کنند. آن‌ها در دیکشنری اشیاء نوع یافت می‌شوند.

PyObject *PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)

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

یک توصیف‌گر دریافت-تنظیم (get-set) جدید برای نوع توسعه‌ای type از ساختار PyGetSetDef با نام getset می‌سازد.

توصیف‌گرهای دریافت-تنظیم (get-set) ویژگی‌هایی را در دسترس قرار می‌دهند که به‌جای ذخیره‌شدن مستقیم در نمونه، توسط توابع getter و setter زبان C پیاده‌سازی شده‌اند. این همان نوع توصیف‌گری است که برای ورودی‌های tp_getset ایجاد می‌شود و در پایتون به‌صورت یک شیء types.GetSetDescriptorType ظاهر می‌شود.

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

PyObject *PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *member)

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

یک توصیف‌گر عضو جدید برای نوع توسعه‌ای type از ساختار PyMemberDef به نام member ایجاد می‌کند.

توصیف‌گرهای عضو، فیلدهای موجود در ساختار C نوع را به‌عنوان ویژگی‌های پایتون در دسترس قرار می‌دهند. این همان نوع توصیف‌گری است که برای ورودی‌های tp_members ایجاد می‌شود و در پایتون به‌صورت شیء types.MemberDescriptorType ظاهر می‌شود.

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

PyTypeObject PyMemberDescr_Type

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

شیء نوع برای اشیاء توصیف‌گر عضو که از ساختارهای PyMemberDef ایجاد می‌شوند. این توصیف‌گرها فیلدهای یک ساختار C را به‌عنوان ویژگی‌هایی روی یک نوع در دسترس قرار می‌دهند و متناظر با اشیاء types.MemberDescriptorType در پایتون هستند.

PyTypeObject PyGetSetDescr_Type

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

شیء نوع برای اشیای توصیف‌گر get/set که از ساختارهای PyGetSetDef ایجاد می‌شوند. این توصیف‌گرها ویژگی‌هایی را پیاده‌سازی می‌کنند که مقدار آن‌ها توسط توابع getter و setter زبان C محاسبه می‌شود و برای بسیاری از ویژگی‌های انواع توکار به کار می‌روند. آن‌ها معادل اشیای types.GetSetDescriptorType در پایتون هستند.

PyObject *PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)

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

یک توصیف‌گر متد جدید برای نوع توسعه‌ای type از ساختار PyMethodDef به نام meth ایجاد کنید.

توصیف‌گرهای متد، توابع C را به‌صورت متدهایی روی یک نوع در دسترس قرار می‌دهند. این همان نوع توصیف‌گری است که برای ورودی‌های tp_methods ایجاد می‌شود و در پایتون به‌صورت شیء types.MethodDescriptorType ظاهر می‌شود.

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

PyTypeObject PyMethodDescr_Type

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

شیء نوع برای اشیاء توصیف‌گر متد که از ساختارهای PyMethodDef ایجاد شده‌اند. این توصیف‌گرها توابع C را به‌عنوان متدهایی روی یک نوع در دسترس قرار می‌دهند و معادل اشیاء types.MethodDescriptorType در پایتون هستند.

PyTypeObject PyWrapperDescr_Type

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

شیء نوع داده برای اشیای توصیف‌گر پوششی ایجادشده توسط PyDescr_NewWrapper() و PyWrapper_New().

توصیف‌گرهای پوششی به صورت داخلی برای نمایش متدهای ویژه‌ای مانند __repr__ یا __add__ استفاده می‌شوند که توسط جایگاه‌های نوع پیاده‌سازی شده‌اند. این نوع در پایتون به صورت types.WrapperDescriptorType نمایش داده می‌شود.

PyObject *PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *base, void *wrapped)

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

یک توصیف‌گر پوششی جدید از نوع PyWrapperDescr_Type ایجاد کنید.

این تابع فقط برای استفاده‌ی داخلی در نظر گرفته شده است؛ آن و APIهای مرتبط (struct wrapperbase و پرچم PyWrapperFlag_KEYWORDS) به دلایل سازگاری با نسخه‌های پیشین به صورت عمومی ارائه شده‌اند.

برای بسته‌بندی یک تابع C به PyCMethod_New() مراجعه کنید.

PyObject *PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)

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

یک توصیف‌گر متد کلاس جدید برای نوع توسعه‌ای type از ساختار PyMethodDef به نام method ایجاد می‌کند.

توصیف‌گرهای متد کلاس، متدهای C را نمایان می‌کنند که هنگام دسترسی، کلاس را به جای نمونه دریافت می‌کنند. این همان نوع توصیف‌گری است که برای ورودی‌های METH_CLASS در tp_methods ایجاد می‌شود و در پایتون به صورت شیء types.ClassMethodDescriptorType ظاهر می‌شود.

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

int PyDescr_IsData(PyObject *descr)

اگر شیء توصیف‌گر descr یک ویژگی داده‌ای را توصیف کند، مقدار نا‌صفر را برمی‌گرداند و اگر متدی را توصیف کند، 0 را برمی‌گرداند. descr باید یک شیء توصیف‌گر باشد؛ هیچ بررسی خطایی انجام نمی‌شود.

PyObject *PyWrapper_New(PyObject *d, PyObject *self)

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

یک شیء پوششی مقید جدید از توصیف‌گر پوششی d و نمونه self ایجاد کنید.

این، شکل مقیدِ یک توصیف‌گر پوششی (wrapper descriptor) است که توسط PyDescr_NewWrapper() ایجاد شده است. سی‌پایتون این اشیاء را زمانی ایجاد می‌کند که از طریق یک نمونه به یک پوشش‌دهنده جایگاه (slot wrapper) دسترسی پیدا شود، و آن‌ها در پایتون به‌صورت اشیاء types.MethodWrapperType ظاهر می‌شوند.

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

PyDescr_TYPE(descr)

یک ارجاع امانتی به نوعی که توصیف‌گر descr به آن تعلق دارد، برگردانید. این مقدار در پایتون به عنوان __objclass__ قابل دسترسی است.

descr باید یک شیء توصیف‌گر باشد که توسط یکی از توابع PyDescr_New* ایجاد شده است (یک نمونه از PyMethodDescr_Type، PyClassMethodDescr_Type، PyMemberDescr_Type، PyGetSetDescr_Type یا PyWrapperDescr_Type). اگر توصیف‌گر ارسال‌شده نمونه‌ای از یکی از این نوع‌ها نباشد، رفتار نامشخص خواهد بود.

PyDescr_NAME(descr)

نام توصیف‌گر descr را به عنوان یک ارجاع امانتی به یک شیء str برگردانید. این مقدار در پایتون به عنوان __name__ در دسترس است.

descr باید یک شیء توصیف‌گر باشد که توسط یکی از توابع PyDescr_New* ایجاد شده است. در غیر این صورت، رفتار نامشخص خواهد بود.

PyDescr_COMMON

این یک کلان‌دستور است که شامل فیلدهای مشترک برای یک شیء توصیف‌گر است.

این مورد به اشتباه در API سی پایتون قرار داده شده است؛ از آن در افزونه‌ها استفاده نکنید. برای ایجاد شیء‌های توصیف‌گر سفارشی، کلاسی ایجاد کنید که پروتکل توصیف‌گر را پیاده‌سازی کند (tp_descr_get و tp_descr_set).

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.15.

توصیف‌گرهای توکار

PyTypeObject PyProperty_Type

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

شیء نوع برای اشیاء ویژگی. این شیء همان شیء property در لایه‌ی پایتون است.

PyTypeObject PySuper_Type

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

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

PyTypeObject PyClassMethod_Type

نوع اشیای متد کلاس. این همان شیء classmethod در لایه پایتون است.

PyTypeObject PyClassMethodDescr_Type

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

شیء نوع برای اشیاء توصیف‌گر متد کلاس در سطح C. این همان نوع توصیف‌گرهایی است که برای classmethod() تعریف‌شده در نوع‌های توسعه‌ای C ایجاد می‌شوند و با اشیاء types.ClassMethodDescriptorType در پایتون مطابقت دارد.

PyObject *PyClassMethod_New(PyObject *callable)

یک شیء جدید classmethod می‌سازد که callable را در بر می‌گیرد. callable باید یک شیء فراخوانی‌پذیر باشد و نباید NULL باشد.

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

PyTypeObject PyStaticMethod_Type

نوع اشیاء متد ایستا. این همان شیء staticmethod در لایه‌ی پایتون است.

PyObject *PyStaticMethod_New(PyObject *callable)

یک شیء staticmethod جدید ایجاد می‌کند که callable را دربر می‌گیرد. callable باید یک شیء فراخوانی‌پذیر باشد و نباید NULL باشد.

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