Объекты кода

Объекты кода — это низкоуровневый элемент реализации 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 при успехе или -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, чтобы можно было проверить его предыдущее состояние.

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

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

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

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

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