اشیای فریم

type PyFrameObject

قسمتی از API محدود (به‌عنوان یک ساختار مبهم).

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

هیچ عضو عمومی در این ساختار وجود ندارد.

تغییر یافته در نسخه‌ی 3.11: اعضای این ساختار از API عمومی C حذف شدند. برای جزئیات، به مدخل «What's New» مراجعه کنید.

از توابع PyEval_GetFrame() و PyThreadState_GetFrame() می‌توان برای به‌دست‌آوردن یک شیء فریم استفاده کرد.

همچنین ببینید بازتاب.

PyTypeObject PyFrame_Type

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

تغییر یافته در نسخه‌ی 3.11: پیش‌تر، این نوع تنها پس از گنجاندن <frameobject.h> در دسترس بود.

PyFrameObject *PyFrame_New(PyThreadState *tstate, PyCodeObject *code, PyObject *globals, PyObject *locals)

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

int PyFrame_Check(PyObject *obj)

اگر obj یک شیء فریم باشد، مقدار غیر صفر برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.11: پیش‌تر، این تابع تنها پس از گنجاندن <frameobject.h> در دسترس بود.

PyFrameObject *PyFrame_GetBack(PyFrameObject *frame)

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

گرفتن فریم بیرونی بعدیِ frame.

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

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

PyObject *PyFrame_GetBuiltins(PyFrameObject *frame)

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

ویژگی f_builtins فریم را دریافت می‌کند.

یک strong reference برمی‌گرداند. نتیجه نمی‌تواند NULL باشد.

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

PyCodeObject *PyFrame_GetCode(PyFrameObject *frame)

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

دریافت کد فریم .

یک strong reference را برمی‌گرداند.

نتیجه (کد فریم) نمی‌تواند NULL باشد.

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

PyObject *PyFrame_GetGenerator(PyFrameObject *frame)

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

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

یک ارجاع قوی یا NULL برمی‌گرداند.

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

PyObject *PyFrame_GetGlobals(PyFrameObject *frame)

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

گرفتن ویژگی f_globals از فریم.

یک strong reference برمی‌گرداند. نتیجه نمی‌تواند NULL باشد.

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

int PyFrame_GetLasti(PyFrameObject *frame)

ویژگی f_lasti فریم را دریافت کنید.

اگر frame.f_lasti برابر با None باشد، مقدار -1 را برمی‌گرداند.

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

PyObject *PyFrame_GetVar(PyFrameObject *frame, PyObject *name)

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

متغیر name را از frame می‌گیرد.

• در صورت موفقیت، یک ارجاع قوی به مقدار متغیر برمی‌گرداند.

• اگر متغیر وجود نداشته باشد، NameError را پرتاب کرده و NULL را برمی‌گرداند.

• در صورت خطا، یک استثنا ایجاد کرده و NULL را برمی‌گرداند.

نوع name باید str باشد.

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

PyObject *PyFrame_GetVarString(PyFrameObject *frame, const char *name)

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

مشابه PyFrame_GetVar()، اما نام متغیر یک رشته C کدگذاری‌شده با UTF-8 است.

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

PyObject *PyFrame_GetLocals(PyFrameObject *frame)

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

ویژگی f_locals فریم را دریافت می‌کند. اگر فریم به یک محدوده بهینه‌شده اشاره کند، یک شیء پراکسی نوشتن‌همزمان برمی‌گرداند که امکان تغییر متغیرهای محلی را فراهم می‌کند. در تمام موارد دیگر (کلاس‌ها، ماژول‌ها، exec()، eval()) نگاشتی را برمی‌گرداند که متغیرهای محلی فریم را به‌طور مستقیم نمایش می‌دهد (همان‌طور که برای locals() توضیح داده شده است).

یک strong reference را برمی‌گرداند.

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

تغییر یافته در نسخه‌ی 3.13: به عنوان بخشی از PEP 667، یک نمونه از PyFrameLocalsProxy_Type را برمی‌گرداند.

int PyFrame_GetLineNumber(PyFrameObject *frame)

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

شماره سطری که frame هم‌اکنون در حال اجرای آن است را بازمی‌گرداند.

پراکسی‌های متغیرهای محلی فریم

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

ویژگی f_locals روی یک شیء فریم، نمونه‌ای از «پراکسی متغیرهای محلی فریم» (frame-locals proxy) است. شیء پراکسی یک نمای نوشتن‌همزمان از دیکشنری متغیرهای محلی زیرین فریم ارائه می‌دهد. این تضمین می‌کند که متغیرهای ارائه‌شده توسط f_locals همیشه با متغیرهای محلی زنده در خودِ فریم به‌روز باشند.

برای اطلاعات بیشتر به PEP 667 مراجعه کنید.

PyTypeObject PyFrameLocalsProxy_Type

نوع شیءهای پراکسی locals() در فریم.

int PyFrameLocalsProxy_Check(PyObject *obj)

اگر obj یک پراکسی locals() فریم باشد، مقدار غیر صفر را برمی‌گرداند.

APIهای قدیمی متغیر محلی

این API‌ها soft deprecated هستند. از پایتون 3.13 به بعد، آن‌ها هیچ کاری انجام نمی‌دهند. آن‌ها صرفاً برای سازگاری با نسخه‌های قبلی وجود دارند.

void PyFrame_LocalsToFast(PyFrameObject *f, int clear)

پیش از پایتون 3.13، این تابع ویژگی f_locals از f را به آرایه‌ی داخلی «سریع» (fast) متغیرهای محلی کپی می‌کرد، به‌طوری‌که تغییرات در اشیاء فریم برای مفسر قابل مشاهده می‌شدند. اگر clear درست بود، این تابع متغیرهایی را که در دیکشنری متغیرهای محلی تنظیم نشده بودند پردازش می‌کرد.

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.13: این تابع اکنون کاری انجام نمی‌دهد.

void PyFrame_FastToLocals(PyFrameObject *f)

پیش از پایتون 3.13، این تابع آرایه داخلی «سریع» متغیرهای محلی (که توسط مفسر استفاده می‌شود) را به ویژگی f_locals از f کپی می‌کرد، به‌طوری که تغییرات در متغیرهای محلی برای اشیاء فریم قابل مشاهده باشند.

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.13: این تابع اکنون کاری انجام نمی‌دهد.

int PyFrame_FastToLocalsWithError(PyFrameObject *f)

پیش از پایتون 3.13، این تابع مشابه PyFrame_FastToLocals() بود، اما در صورت موفقیت 0 و در صورت شکست -1 به همراه استثنای تنظیم‌شده برمی‌گرداند.

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.13: این تابع اکنون کاری انجام نمی‌دهد.

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

PEP 667

فریم‌های داخلی

مگر اینکه از PEP 523 استفاده کنید، به این نیاز نخواهید داشت.

struct _PyInterpreterFrame

نمایش داخلی فریم در مفسر.

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

PyObject *PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame);

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

یک strong reference به شیء کدِ فریم را برمی‌گرداند.

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

int PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame);

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

آفست بایتیِ آخرین دستور اجرا‌شده را برمی‌گرداند.

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

int PyUnstable_InterpreterFrame_GetLine(struct _PyInterpreterFrame *frame);

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

شماره‌ی سطر در حال اجرا را برمی‌گرداند، یا -1 اگر شماره‌ی سطری وجود نداشته باشد.

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

const PyTypeObject *PyUnstable_ExecutableKinds

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

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

ابزارهایی مانند اشکال‌زداها و پروفایل‌گیرها می‌توانند از این برای شناسایی نوع زمینه اجرای مرتبط با یک فریم استفاده کنند (مانند پالایش فریم‌های داخلی). ورودی‌ها با ثابت‌های زیر اندیس‌گذاری می‌شوند:

ثابت	توضیحات
PyUnstable_EXECUTABLE_KIND_SKIP این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.	این فریم داخلی است (برای مثال: درون‌خطی‌شده (inlined)) و باید توسط ابزارها نادیده گرفته شود.
PyUnstable_EXECUTABLE_KIND_PY_FUNCTION این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.	این فریم متناظر با یک تابع استاندارد پایتون است.
PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.	این فریم مربوط به تابعی است که در کد بومی تعریف شده است.
PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.	فریم متناظر با متدی روی نمونه‌ای از یک کلاس است.

Note that reading the executable kind from a frame is currently only possible with undocumented internal APIs.

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

PyUnstable_EXECUTABLE_KINDS

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

تعداد ورودی‌های PyUnstable_ExecutableKinds.

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