شیءهای تابع

چند تابع وجود دارند که مختص توابع پایتون هستند.

type PyFunctionObject

ساختار C استفاده‌شده برای توابع.

PyTypeObject PyFunction_Type

این نمونه‌ای از PyTypeObject است و نوع تابع پایتون را نمایندگی می‌کند. این نوع به برنامه‌نویسان پایتون به صورت types.FunctionType در دسترس قرار گرفته است.

int PyFunction_Check(PyObject *o)

اگر o یک شیء تابع باشد (نوع PyFunction_Type را داشته باشد)، true را برمی‌گرداند. پارامتر نباید NULL باشد. این تابع همیشه با موفقیت انجام می‌شود.

PyObject *PyFunction_New(PyObject *code, PyObject *globals)

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

شیء تابع جدیدی مرتبط با شیء کد code را برمی‌گرداند. globals باید دیکشنری‌ای شامل متغیرهای سراسری قابل دسترس برای تابع باشد.

رشته مستند و نام تابع از شیء کد بازیابی می‌شوند. __module__ از globals بازیابی می‌شود. مقادیر پیش‌فرض آرگومان‌ها، حاشیه‌نویسی‌ها و بستار به NULL تنظیم می‌شوند. __qualname__ به همان مقدار فیلد co_qualname شیء کد تنظیم می‌شود.

PyObject *PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)

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

مانند PyFunction_New() است، اما به‌علاوه امکان تنظیم ویژگی __qualname__ شیء تابع را نیز فراهم می‌کند. qualname باید یک شیء یونیکد یا NULL باشد؛ اگر NULL باشد، ویژگی __qualname__ به همان مقدار فیلد co_qualname شیء کد تنظیم می‌شود.

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

PyObject *PyFunction_GetCode(PyObject *op)

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

شیء کدِ مرتبط با شیء تابع op را برمی‌گرداند.

PyObject *PyFunction_GetGlobals(PyObject *op)

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

دیکشنری سراسری مرتبط با شیء تابع op را برمی‌گرداند.

PyObject *PyFunction_GetModule(PyObject *op)

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

یک ارجاع امانتی به ویژگی __module__ از شیء تابع op برمی‌گرداند. می‌تواند NULL باشد.

این به‌طور معمول یک رشته حاوی نام ماژول است، اما می‌تواند توسط کد پایتون به هر شیء دیگری تنظیم شود.

PyObject *PyFunction_GetDefaults(PyObject *op)

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

مقادیر پیش‌فرض آرگومان‌های شیء تابع op را برمی‌گرداند. این می‌تواند یک تاپل از آرگومان‌ها یا NULL باشد.

int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)

مقادیر پیش‌فرض آرگومان‌ها را برای شیء تابع op تنظیم می‌کند. defaults باید Py_None یا یک تاپل باشد.

در صورت شکست، SystemError ایجاد می‌کند و -1 را برمی‌گرداند.

void PyFunction_SetVectorcall(PyFunctionObject *func, vectorcallfunc vectorcall)

فیلد vectorcall از شیء تابع داده‌شده func را تنظیم می‌کند.

هشدار: ماژول‌های توسعه‌ای که از این API استفاده می‌کنند، باید رفتار تابع vectorcall دست‌نخورده (پیش‌فرض) را حفظ کنند!

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

PyObject *PyFunction_GetKwDefaults(PyObject *op)

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

مقادیر پیش‌فرض آرگومان‌های فقط‌کلیدواژه‌ای شیء تابع op را برمی‌گرداند. این می‌تواند یک دیکشنری از آرگومان‌ها یا NULL باشد.

int PyFunction_SetKwDefaults(PyObject *op, PyObject *defaults)

مقادیر پیش‌فرض آرگومان‌های فقط کلیدواژه‌ای شیء تابع op را تنظیم می‌کند. defaults باید یک دیکشنری از آرگومان‌های فقط کلیدواژه‌ای یا Py_None باشد.

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

PyObject *PyFunction_GetClosure(PyObject *op)

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

بستار مرتبط با شیء تابع op را برمی‌گرداند. این می‌تواند NULL یا تاپلی از شیءهای سلولی (cell objects) باشد.

int PyFunction_SetClosure(PyObject *op, PyObject *closure)

بستار مرتبط با شیء تابع op را تنظیم می‌کند. closure باید Py_None یا تاپلی از اشیاء سلول باشد.

در صورت شکست، SystemError ایجاد می‌کند و -1 را برمی‌گرداند.

PyObject *PyFunction_GetAnnotations(PyObject *op)

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

حاشیه‌نویسی‌های شیء تابع op را برمی‌گرداند. این می‌تواند یک دیکشنری تغییرپذیر یا NULL باشد.

int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)

حاشیه‌نویسی‌های شیء تابع op را تنظیم می‌کند. annotations باید یک دیکشنری یا Py_None باشد.

در صورت شکست، SystemError ایجاد می‌کند و -1 را برمی‌گرداند.

PyObject *PyFunction_GET_CODE(PyObject *op)

PyObject *PyFunction_GET_GLOBALS(PyObject *op)

PyObject *PyFunction_GET_MODULE(PyObject *op)

PyObject *PyFunction_GET_DEFAULTS(PyObject *op)

PyObject *PyFunction_GET_KW_DEFAULTS(PyObject *op)

PyObject *PyFunction_GET_CLOSURE(PyObject *op)

PyObject *PyFunction_GET_ANNOTATIONS(PyObject *op)

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

این توابع مشابه همتایان PyFunction_Get* خود هستند، اما بررسی نوع انجام نمی‌دهند. ارسال هر چیزی غیر از نمونه‌ای از PyFunction_Type رفتار تعریف‌نشده است.

int PyFunction_AddWatcher(PyFunction_WatchCallback callback)

callback را به‌عنوان ناظر تابع برای مفسر جاری ثبت می‌کند. شناسه‌ای برمی‌گرداند که می‌توان آن را به PyFunction_ClearWatcher() پاس داد. در صورت بروز خطا (مثلاً وقتی دیگر شناسه ناظری در دسترس نباشد)، مقدار -1 را برمی‌گرداند و یک استثنا تنظیم می‌کند.

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

int PyFunction_ClearWatcher(int watcher_id)

دیده‌بان (watcher) شناسایی‌شده توسط watcher_id که پیش‌تر از PyFunction_AddWatcher() برای مفسر فعلی برگردانده شده است را حذف می‌کند. در صورت موفقیت 0 را برمی‌گرداند، یا در صورت خطا -1 را برمی‌گرداند و یک استثنا تنظیم می‌کند (مثلاً اگر watcher_id داده‌شده هرگز ثبت نشده باشد.)

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

type PyFunction_WatchEvent

فهرست رویداد‌های ممکن ناظر تابع (function watcher):

• PyFunction_EVENT_CREATE

• PyFunction_EVENT_DESTROY

• PyFunction_EVENT_MODIFY_CODE

• PyFunction_EVENT_MODIFY_DEFAULTS

• PyFunction_EVENT_MODIFY_KWDEFAULTS

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

typedef int (*PyFunction_WatchCallback)(PyFunction_WatchEvent event, PyFunctionObject *func, PyObject *new_value)

نوع تابع کال‌بک دیده‌بان (watcher) تابع.

اگر event برابر PyFunction_EVENT_CREATE یا PyFunction_EVENT_DESTROY باشد، new_value برابر NULL خواهد بود. در غیر این صورت، new_value حاوی یک borrowed reference به مقدار جدیدی خواهد بود که قرار است در func برای ویژگی‌ای که در حال تغییر است ذخیره شود.

کال‌بک می‌تواند func را بررسی کند اما نباید آن را تغییر دهد؛ انجام این کار می‌تواند پیامدهای غیرقابل پیش‌بینی، از جمله بازگشتی بی‌نهایت، داشته باشد.

اگر event برابر PyFunction_EVENT_CREATE باشد، کال‌بک پس از آنکه func به‌طور کامل مقداردهی اولیه‌شده باشد فراخوانی می‌شود. در غیر این صورت، کال‌بک پیش از اعمال تغییر روی func فراخوانی می‌شود، به‌طوری‌که بتوان وضعیت پیشین func را بررسی کرد. ران‌تایم مجاز است در صورت امکان، ایجاد اشیاء تابع را با بهینه‌سازی حذف کند. در چنین مواردی هیچ رویدادی منتشر نخواهد شد. اگرچه این امر امکان بروز تفاوت قابل مشاهده در رفتار ران‌تایم بسته به تصمیمات بهینه‌سازی را ایجاد می‌کند، اما معناشناسی کد پایتون در حال اجرا را تغییر نمی‌دهد.

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

اگر کال‌بک استثنایی تنظیم کند، باید -1 را بازگرداند؛ این استثنا با استفاده از PyErr_WriteUnraisable() به‌عنوان یک استثنای غیرقابل برافراشتن (unraisable) چاپ خواهد شد. در غیر این صورت باید 0 را بازگرداند.

ممکن است هنگام ورود به کال‌بک، از قبل یک استثنای معلق تنظیم‌شده باشد. در این حالت، کال‌بک باید 0 را برگرداند در حالی که همان استثنا همچنان تنظیم‌شده است. این بدان معناست که کال‌بک نباید هیچ API دیگری را که می‌تواند استثنا تنظیم کند فراخوانی کند، مگر آنکه ابتدا وضعیت استثنا را ذخیره و پاک کند و پیش از بازگشت، آن را بازگردانی کند.

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