Объекты фреймов

type PyFrameObject

Часть Ограниченного API (в виде непрозрачной структуры).

Структура C объектов, используемых для описания объектов фреймов.

В этой структуре нет общедоступных членов.

Изменено в версии 3.11: Члены этой структуры были удалены из общедоступного API C. Подробности см. в разделе Что нового.

Для получения объекта фрейма можно использовать функции PyEval_GetFrame() и PyThreadState_GetFrame().

См. также Рефлексия.

PyTypeObject PyFrame_Type: Тип объектов фреймов. Это тот же объект, что и types.FrameType на уровне Python.

Изменено в версии 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.

Возвращает сильную ссылку или NULL, если у frame нет внешнего фрейма. Исключения не возбуждаются.

Добавлено в версии 3.9.

PyObject *PyFrame_GetBuiltins(PyFrameObject *frame)

Возвращаемое значение: новая ссылка.

Получает атрибут f_builtins объекта frame.

Возвращает сильную ссылку. Результат не может быть NULL.

Добавлено в версии 3.11.

PyCodeObject *PyFrame_GetCode(PyFrameObject *frame)

Возвращаемое значение: новая ссылка. Часть Стабильного ABI начиная с версии 3.10.

Получает код объекта frame.

Возвращает сильную ссылку.

Результат (код фрейма) не может быть NULL.

Добавлено в версии 3.9.

PyObject *PyFrame_GetGenerator(PyFrameObject *frame)

Возвращаемое значение: новая ссылка.

Получает генератор, сопрограмму или асинхронный генератор, которому принадлежит этот фрейм, либо NULL, если фрейм не принадлежит генератору. Исключение не возбуждается, даже если возвращаемое значение равно NULL.

Возвращает сильную ссылку или NULL.

Добавлено в версии 3.11.

PyObject *PyFrame_GetGlobals(PyFrameObject *frame)

Возвращаемое значение: новая ссылка.

Получает атрибут f_globals объекта frame.

Возвращает сильную ссылку. Результат не может быть NULL.

Добавлено в версии 3.11.

int PyFrame_GetLasti(PyFrameObject *frame)

Получает атрибут f_lasti объекта frame.

Возвращает -1, если frame.f_lasti равно None.

Добавлено в версии 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 объекта frame. Если фрейм относится к оптимизированной области видимости, возвращается прокси-объект со сквозной записью, позволяющий изменять локальные переменные. Во всех остальных случаях (классы, модули, exec(), eval()) возвращается непосредственно отображение, представляющее локальные переменные фрейма (как описано для locals()).

Возвращает сильную ссылку.

Добавлено в версии 3.11.

Изменено в версии 3.13: В соответствии с PEP 667 возвращает экземпляр PyFrameLocalsProxy_Type.

int PyFrame_GetLineNumber(PyFrameObject *frame): Часть Стабильного ABI начиная с версии 3.10.
Возвращает номер строки, выполняемой в данный момент во фрейме frame.

Прокси локальных переменных фрейма

Добавлено в версии 3.13.

Атрибут f_locals объекта фрейма представляет собой экземпляр «прокси локальных переменных фрейма». Прокси-объект предоставляет представление базового словаря локальных переменных фрейма со сквозной записью. Благодаря этому переменные, доступные через f_locals, всегда соответствуют актуальным локальным переменным самого фрейма.

Дополнительные сведения см. в PEP 667.

PyTypeObject PyFrameLocalsProxy_Type: Тип прокси-объектов locals() фрейма.

int PyFrameLocalsProxy_Check(PyObject *obj): Возвращает ненулевое значение, если obj является прокси-объектом locals() фрейма.

Устаревшие API локальных переменных

Эти API мягко объявлены устаревшими. Начиная с Python 3.13 они ничего не делают и существуют исключительно для обратной совместимости.

void PyFrame_LocalsToFast(PyFrameObject *f, int clear): До Python 3.13 эта функция копировала атрибут f_locals объекта f во внутренний «быстрый» массив локальных переменных, позволяя интерпретатору видеть изменения объектов фреймов. Если значение clear было истинным, функция обрабатывала переменные, отсутствовавшие в словаре локальных переменных.

Мягко объявлена устаревшей с версии 3.13: Теперь эта функция ничего не делает.

void PyFrame_FastToLocals(PyFrameObject *f): До Python 3.13 эта функция копировала внутренний «быстрый» массив локальных переменных (используемый интерпретатором) в атрибут f_locals объекта f, позволяя объектам фреймов видеть изменения локальных переменных.

Мягко объявлена устаревшей с версии 3.13: Теперь эта функция ничего не делает.

int PyFrame_FastToLocalsWithError(PyFrameObject *f): До Python 3.13 эта функция была аналогична PyFrame_FastToLocals(), но в случае успеха возвращала 0, а в случае сбоя — -1 с установленным исключением.

Мягко объявлена устаревшей с версии 3.13: Теперь эта функция ничего не делает.

См. также

PEP 667

Внутренние фреймы

Если вы не используете PEP 523, это вам не понадобится.

struct _PyInterpreterFrame: Внутреннее представление фрейма интерпретатора.

Добавлено в версии 3.11.

PyObject *PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame);: Это Нестабильный API. Он может измениться без предупреждения в минорных выпусках.

Возвращает сильную ссылку на объект кода фрейма.

Добавлено в версии 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. Он может измениться без предупреждения в минорных выпусках.

Массив видов исполняемого кода (типов исполнителей) фреймов, используемый для внутренней отладки и трассировки.

Такие инструменты, как отладчики и профилировщики, могут использовать его для определения типа контекста выполнения, связанного с фреймом (например, чтобы отфильтровывать внутренние фреймы). Элементы индексируются следующими константами:

Константа	Описание
`PyUnstable_EXECUTABLE_KIND_SKIP` Это Нестабильный API. Он может измениться без предупреждения в минорных выпусках.	Фрейм является внутренним (например, встроенным) и должен пропускаться инструментами.
`PyUnstable_EXECUTABLE_KIND_PY_FUNCTION` Это Нестабильный API. Он может измениться без предупреждения в минорных выпусках.	Фрейм соответствует стандартной функции Python.
`PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION` Это Нестабильный API. Он может измениться без предупреждения в минорных выпусках.	Фрейм соответствует функции, определённой в машинном коде.
`PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR` Это Нестабильный API. Он может измениться без предупреждения в минорных выпусках.	Фрейм соответствует методу экземпляра класса.

Обратите внимание: в настоящее время получить вид исполняемого кода из фрейма можно только с помощью недокументированных внутренних API.

Добавлено в версии 3.13.

PyUnstable_EXECUTABLE_KINDS: Это Нестабильный API. Он может измениться без предупреждения в минорных выпусках.

Количество элементов в PyUnstable_ExecutableKinds.

Добавлено в версии 3.13.