Объекты кода

Объекты кода — это низкоуровневая деталь реализации CPython. Каждый из них представляет собой фрагмент исполняемого кода, который ещё не был связан с функцией.

type PyCodeObject

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

PyTypeObject PyCode_Type

Это экземпляр PyTypeObject, представляющий объект кода Python.

int PyCode_Check(PyObject *co)

Возвращает true, если co — объект кода. Эта функция всегда завершается успешно.

Py_ssize_t PyCode_GetNumFree(PyCodeObject *co)

Возвращает число свободных переменных (переменных замыкания) в объекте кода.

int PyUnstable_Code_GetFirstFree(PyCodeObject *co)

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

Возвращает позицию первой свободной переменной (переменной замыкания) в объекте кода.

Изменено в версии 3.13: Переименована из PyCode_GetFirstFree в рамках нестабильного C API. Старое имя объявлено устаревшим, но останется доступным до следующего изменения сигнатуры.

PyCodeObject *PyUnstable_Code_New(int argcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable)

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

Возвращает новый объект кода. Если вам нужен фиктивный объект кода для создания кадра, используйте вместо этого PyCode_NewEmpty().

Поскольку определение байт-кода часто меняется, прямой вызов PyUnstable_Code_New() может привязать вас к конкретной версии Python.

Многочисленные аргументы этой функции сложным образом зависят друг от друга, поэтому даже незначительные изменения значений могут привести к неправильному выполнению кода или сбоям виртуальной машины. Используйте эту функцию с особой осторожностью.

Изменено в версии 3.11: Добавлены параметры qualname и exceptiontable.

Изменено в версии 3.12: Переименована из PyCode_New в рамках нестабильного C API. Старое имя объявлено устаревшим, но останется доступным до следующего изменения сигнатуры.

PyCodeObject *PyUnstable_Code_NewWithPosOnlyArgs(int argcount, int posonlyargcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable)

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

Аналогична PyUnstable_Code_New(), но принимает дополнительный аргумент «posonlyargcount» для позиционных аргументов, передаваемых только по позиции. К этой функции применимы те же предостережения, что и к PyUnstable_Code_New.

Добавлено в версии 3.8: как PyCode_NewWithPosOnlyArgs

Изменено в версии 3.11: Добавлены параметры qualname и exceptiontable.

Изменено в версии 3.12: Переименована в PyUnstable_Code_NewWithPosOnlyArgs. Старое имя объявлено устаревшим, но останется доступным до следующего изменения сигнатуры.

PyCodeObject *PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)

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

Возвращает новый пустой объект кода с указанными именем файла, именем функции и номером первой строки. При выполнении полученный объект кода вызовет Exception.

int PyCode_Addr2Line(PyCodeObject *co, int byte_offset)

Возвращает номер строки инструкции, которая начинается на позиции byte_offset или до неё и заканчивается после этой позиции. Если вам нужен только номер строки кадра, используйте вместо этого PyFrame_GetLineNumber().

Для эффективного перебора номеров строк в объекте кода используйте API, описанный в PEP 626.

int PyCode_Addr2Location(PyObject *co, int byte_offset, int *start_line, int *start_column, int *end_line, int *end_column)

Записывает в переданные указатели int номера строки и столбца исходного кода для инструкции по адресу byte_offset. Если информация для какого-либо элемента недоступна, устанавливает значение 0.

Возвращает 1 в случае успеха и 0 в противном случае.

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

PyObject *PyCode_GetCode(PyCodeObject *co)

Эквивалентна коду Python getattr(co, 'co_code'). Возвращает сильную ссылку на PyBytesObject, представляющий байт-код в объекте кода. В случае ошибки возвращается NULL и возбуждается исключение.

Этот PyBytesObject может создаваться интерпретатором по запросу и не обязательно представляет байт-код, фактически выполняемый CPython. Основное применение этой функции — отладчики и профилировщики.

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

PyObject *PyCode_GetVarnames(PyCodeObject *co)

Эквивалентна коду Python getattr(co, 'co_varnames'). Возвращает новую ссылку на PyTupleObject, содержащий имена локальных переменных. В случае ошибки возвращается NULL и возбуждается исключение.

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

PyObject *PyCode_GetCellvars(PyCodeObject *co)

Эквивалентна коду Python getattr(co, 'co_cellvars'). Возвращает новую ссылку на PyTupleObject, содержащий имена локальных переменных, на которые ссылаются вложенные функции. В случае ошибки возвращается NULL и возбуждается исключение.

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

PyObject *PyCode_GetFreevars(PyCodeObject *co)

Эквивалентна коду Python getattr(co, 'co_freevars'). Возвращает новую ссылку на PyTupleObject, содержащий имена свободных переменных (переменных замыкания). В случае ошибки возвращается NULL и возбуждается исключение.

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

int PyCode_AddWatcher(PyCode_WatchCallback callback)

Регистрирует callback как наблюдатель за объектами кода для текущего интерпретатора. Возвращает идентификатор, который можно передать в PyCode_ClearWatcher(). В случае ошибки (например, если больше нет доступных идентификаторов наблюдателей) возвращает -1 и устанавливает исключение.

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

int PyCode_ClearWatcher(int watcher_id)

Удаляет наблюдателя с идентификатором watcher_id, ранее возвращённым функцией PyCode_AddWatcher() для текущего интерпретатора. В случае успеха возвращает 0, а в случае ошибки (например, если указанный watcher_id не был зарегистрирован) возвращает -1 и устанавливает исключение.

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

type PyCodeEvent

Перечисление возможных событий наблюдателя за объектами кода: - PY_CODE_EVENT_CREATE - PY_CODE_EVENT_DESTROY

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

typedef int (*PyCode_WatchCallback)(PyCodeEvent event, PyCodeObject *co)

Тип функции обратного вызова наблюдателя за объектами кода.

Если event имеет значение PY_CODE_EVENT_CREATE, обратный вызов вызывается после полной инициализации co. В противном случае обратный вызов вызывается до уничтожения co, чтобы можно было проверить его предыдущее состояние.

Если event имеет значение PY_CODE_EVENT_DESTROY, получение ссылки на объект кода, который готовится к уничтожению, в функции обратного вызова воскресит его и предотвратит его освобождение в этот момент. Когда воскресший объект будет уничтожен позднее, все активные на тот момент функции обратного вызова наблюдателей будут вызваны снова.

Пользователям этого API не следует полагаться на внутренние детали реализации среды выполнения. К таким деталям могут относиться, помимо прочего, точный порядок и время создания и уничтожения объектов кода. Хотя изменения этих деталей могут приводить к различиям, наблюдаемым наблюдателями (включая вызов или отсутствие вызова функции обратного вызова), семантика выполняемого кода Python при этом не меняется.

Если функция обратного вызова устанавливает исключение, она должна вернуть -1; это исключение будет выведено как необрабатываемое с помощью PyErr_WriteUnraisable(). В противном случае она должна вернуть 0.

При входе в функцию обратного вызова уже может быть установлено ожидающее исключение. В этом случае функция должна вернуть 0, оставив то же исключение установленным. Это означает, что функция обратного вызова не может вызывать другие API, которые могут установить исключение, если предварительно не сохранит и не очистит состояние исключения, а затем не восстановит его перед возвратом.

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