Объекты кода

Объекты кода — это низкоуровневая деталь реализации 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.

PyObject *PyCode_Optimize(PyObject *code, PyObject *consts, PyObject *names, PyObject *lnotab_obj)

Эта функция ничего не делает.

До Python 3.10 эта функция выполняла базовые оптимизации объекта кода.

Изменено в версии 3.10: Теперь эта функция ничего не делает.

Мягко объявлена устаревшей начиная с версии 3.13.