Объекты кода

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

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

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