Объекты кода

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

type PyCodeObject

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

PyTypeObject PyCode_Type

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

int PyCode_Check(PyObject *co)

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

Py_ssize_t PyCode_GetNumFree(PyCodeObject *co)

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

int PyCode_GetFirstFree(PyCodeObject *co)

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

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.

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

Изменено в версии 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 при успехе или -1 и устанавливает исключение при ошибке (например, если данный watcher_id никогда не был зарегистрирован).

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

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

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

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

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

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