`code.md`

221 строк · 23.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.15/c-api/code.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты кода89Объекты кода – это низкоуровневая деталь реализации CPython. Каждый из них представляет блок исполняемого кода, который ещё не привязан к функции.1011#### `type PyCodeObject`1213C-структура объектов, используемых для описания объектов кода. Поля этого типа могут быть изменены в любое время.1415#### `PyTypeObject PyCode_Type`1617Это экземпляр [`PyTypeObject`](https://python-all.ru/3.15/c-api/type.html#c.PyTypeObject), представляющий [объект кода](https://python-all.ru/3.15/reference/datamodel.html#code-objects) Python.1819#### `int PyCode_Check(PyObject *co)`2021Возвращает true, если *co* является [объектом кода](https://python-all.ru/3.15/reference/datamodel.html#code-objects). Эта функция всегда выполняется успешно.2223#### `Py_ssize_t PyCode_GetNumFree(PyCodeObject *co)`2425Возвращает количество [свободных (замыкающих) переменных](https://python-all.ru/3.15/glossary.html#term-closure-variable) в объекте кода.2627#### `int PyUnstable_Code_GetFirstFree(PyCodeObject *co)`2829> *Это [нестабильное API](https://python-all.ru/3.15/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*3031Возвращает позицию первой [свободной (замыкающей) переменной](https://python-all.ru/3.15/glossary.html#term-closure-variable) в объекте кода.3233Изменено в версии 3.13: Переименовано из `PyCode_GetFirstFree` в рамках [нестабильного C API](https://python-all.ru/3.15/c-api/stable.html#unstable-c-api). Старое имя устарело, но останется доступным до следующего изменения сигнатуры.3435#### `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)`3637> *Это [нестабильное API](https://python-all.ru/3.15/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*3839Возвращает новый объект кода. Если нужен фиктивный объект кода для создания фрейма, используйте [`PyCode_NewEmpty()`](https://python-all.ru/3.15/c-api/code.html#c.PyCode_NewEmpty).4041Поскольку определение байт-кода часто меняется, прямой вызов [`PyUnstable_Code_New()`](https://python-all.ru/3.15/c-api/code.html#c.PyUnstable_Code_New) может привязать к конкретной версии Python.4243Многочисленные аргументы этой функции сложным образом взаимозависимы, поэтому незначительные изменения значений могут привести к некорректному исполнению или сбою виртуальной машины. Используйте эту функцию с крайней осторожностью.4445Изменено в версии 3.11: Добавлены параметры `qualname` и `exceptiontable`.4647Изменено в версии 3.12: Переименовано из `PyCode_New` в рамках [нестабильного C API](https://python-all.ru/3.15/c-api/stable.html#unstable-c-api). Старое имя устарело, но останется доступным до следующего изменения сигнатуры.4849#### `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)`5051> *Это [нестабильное API](https://python-all.ru/3.15/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*5253Аналогично [`PyUnstable_Code_New()`](https://python-all.ru/3.15/c-api/code.html#c.PyUnstable_Code_New), но с дополнительным параметром “posonlyargcount” для позиционных аргументов. Те же предостережения, что и для `PyUnstable_Code_New`, применимы к этой функции.5455Добавлено в версии 3.8: как `PyCode_NewWithPosOnlyArgs`5657Изменено в версии 3.11: Добавлены параметры `qualname` и `exceptiontable`.5859Изменено в версии 3.12: Переименован в `PyUnstable_Code_NewWithPosOnlyArgs`. Старое имя устарело, но останется доступным до следующего изменения сигнатуры.6061#### `PyCodeObject *PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)`6263*Возвращаемое значение: новая ссылка.*6465Возвращает новый пустой объект кода с указанными именем файла, именем функции и номером первой строки. Полученный объект кода вызовет `Exception` при выполнении.6667#### `int PyCode_Addr2Line(PyCodeObject *co, int byte_offset)`6869Возвращает номер строки инструкции, которая начинается до или на `byte_offset` и заканчивается после него. Если нужен просто номер строки фрейма, используйте [`PyFrame_GetLineNumber()`](https://python-all.ru/3.15/c-api/frame.html#c.PyFrame_GetLineNumber).7071Для эффективного перебора номеров строк в объекте кода используйте [**API, описанный в PEP 626**](https://python-all.ru/3.15/c-api/code.html).7273#### `int PyCode_Addr2Location(PyObject *co, int byte_offset, int *start_line, int *start_column, int *end_line, int *end_column)`7475Устанавливает переданные указатели `int` на номера строки и столбца исходного кода для инструкции по адресу `byte_offset`. Устанавливает значение `0`, если информация для какого-либо элемента недоступна.7677Возвращает `1` при успехе функции и 0 в противном случае.7879Добавлено в версии 3.12.8081#### `PyObject *PyCode_GetCode(PyCodeObject *co)`8283Эквивалент кода Python `getattr(co, 'co_code')`. Возвращает сильную ссылку на [`PyBytesObject`](https://python-all.ru/3.15/c-api/bytes.html#c.PyBytesObject), представляющий байт-код в объекте кода. В случае ошибки возвращается `NULL` и возбуждается исключение.8485Этот `PyBytesObject` может быть создан интерпретатором по требованию и не обязательно представляет байт-код, который действительно выполняется CPython. Основное назначение этой функции – отладчики и профилировщики.8687Добавлено в версии 3.12.8889#### `PyObject *PyCode_GetVarnames(PyCodeObject *co)`9091Эквивалент кода Python `getattr(co, 'co_varnames')`. Возвращает новую ссылку на [`PyTupleObject`](https://python-all.ru/3.15/c-api/tuple.html#c.PyTupleObject), содержащий имена локальных переменных. В случае ошибки возвращается `NULL` и возбуждается исключение.9293Добавлено в версии 3.12.9495#### `PyObject *PyCode_GetCellvars(PyCodeObject *co)`9697Эквивалент кода Python `getattr(co, 'co_cellvars')`. Возвращает новую ссылку на [`PyTupleObject`](https://python-all.ru/3.15/c-api/tuple.html#c.PyTupleObject), содержащий имена локальных переменных, на которые ссылаются вложенные функции. В случае ошибки возвращается `NULL` и возбуждается исключение.9899Добавлено в версии 3.12.100101#### `PyObject *PyCode_GetFreevars(PyCodeObject *co)`102103Эквивалент кода Python `getattr(co, 'co_freevars')`. Возвращает новую ссылку на [`PyTupleObject`](https://python-all.ru/3.15/c-api/tuple.html#c.PyTupleObject), содержащий имена [свободных (замыкающих) переменных](https://python-all.ru/3.15/glossary.html#term-closure-variable). В случае ошибки возвращается `NULL` и возбуждается исключение.104105Добавлено в версии 3.12.106107#### `int PyCode_AddWatcher(PyCode_WatchCallback callback)`108109Регистрирует *колбэк* как наблюдатель за объектами кода для текущего интерпретатора. Возвращает идентификатор, который можно передать в [`PyCode_ClearWatcher()`](https://python-all.ru/3.15/c-api/code.html#c.PyCode_ClearWatcher). В случае ошибки (например, нет свободных идентификаторов наблюдателей) возвращает `-1` и устанавливает исключение.110111Добавлено в версии 3.12.112113#### `int PyCode_ClearWatcher(int watcher_id)`114115Удаляет наблюдатель, заданный идентификатором *watcher\_id*, ранее полученным от [`PyCode_AddWatcher()`](https://python-all.ru/3.15/c-api/code.html#c.PyCode_AddWatcher) для текущего интерпретатора. Возвращает `0` при успехе или `-1` с установкой исключения при ошибке (например, если указанный *watcher\_id* никогда не был зарегистрирован).116117Добавлено в версии 3.12.118119#### `type PyCodeEvent`120121Перечисление возможных событий наблюдателя объекта кода: - `PY_CODE_EVENT_CREATE` - `PY_CODE_EVENT_DESTROY`122123Добавлено в версии 3.12.124125#### `typedef int (*PyCode_WatchCallback)(PyCodeEvent event, PyCodeObject *co)`126127Тип функции обратного вызова наблюдателя объекта кода.128129Если *event* равно `PY_CODE_EVENT_CREATE`, то обратный вызов вызывается после полной инициализации *co*. В противном случае обратный вызов вызывается до того, как произойдет уничтожение *co*, так что можно проверить предыдущее состояние *co*.130131Если *event* равно `PY_CODE_EVENT_DESTROY`, то получение ссылки в обратном вызове на объект кода, который должен быть уничтожен, воскресит его и предотвратит его освобождение в данный момент. Когда воскрешенный объект будет уничтожен позже, все активные на тот момент обратные вызовы наблюдателей будут вызваны снова.132133Пользователи этого API не должны полагаться на внутренние детали реализации среды выполнения. Такие детали могут включать, но не ограничиваясь, точный порядок и время создания и уничтожения объектов кода. Хотя изменения этих деталей могут привести к различиям, наблюдаемым наблюдателями (включая то, вызывается ли обратный вызов или нет), это не меняет семантику выполняемого кода Python.134135Если обратный вызов устанавливает исключение, он должен вернуть `-1`; это исключение будет выведено как неподнимаемое исключение с помощью [`PyErr_WriteUnraisable()`](https://python-all.ru/3.15/c-api/exceptions.html#c.PyErr_WriteUnraisable). В противном случае он должен вернуть `0`.136137На момент входа в обратный вызов уже может быть установлено отложенное исключение. В этом случае обратный вызов должен вернуть `0`, оставив то же исключение установленным. Это означает, что обратный вызов не может вызывать никакой другой API, который может установить исключение, если только он сначала не сохранит и не очистит состояние исключения, а затем не восстановит его перед возвратом.138139Добавлено в версии 3.12.140141#### `PyObject *PyCode_Optimize(PyObject *code, PyObject *consts, PyObject *names, PyObject *lnotab_obj)`142143Это функция, которая ничего не делает.144145До Python 3.10 эта функция выполняла базовые оптимизации объекта кода.146147Изменено в версии 3.10: Теперь эта функция ничего не делает.148149[Мягкое устаревание](https://python-all.ru/3.15/glossary.html#term-soft-deprecated) начиная с версии 3.13.150151# Флаги объекта кода152153Объекты кода содержат битовое поле флагов, которое можно получить как атрибут Python [`co_flags`](https://python-all.ru/3.15/reference/datamodel.html#codeobject.co_flags) (например, используя [`PyObject_GetAttrString()`](https://python-all.ru/3.15/c-api/object.html#c.PyObject_GetAttrString)), и установить с помощью аргумента *flags* в [`PyUnstable_Code_New()`](https://python-all.ru/3.15/c-api/code.html#c.PyUnstable_Code_New) и аналогичных функциях.154155Флаги, имена которых начинаются с `CO_FUTURE_`, соответствуют функциям, обычно выбираемым с помощью [операторов будущего](https://python-all.ru/3.15/reference/simple_stmts.html#future). Эти флаги можно использовать в [`PyCompilerFlags.cf_flags`](https://python-all.ru/3.15/c-api/veryhigh.html#c.PyCompilerFlags.cf_flags). Обратите внимание, что многие флаги `CO_FUTURE_` являются обязательными в текущих версиях Python, и их установка не имеет эффекта.156157Доступны следующие флаги. Об их значении см. в документации их аналогов из Python по ссылкам.158159| Флаг | Значение |160| --- | --- |161| CO\_OPTIMIZED | [`inspect.CO_OPTIMIZED`](https://python-all.ru/3.15/library/inspect.html#inspect.CO_OPTIMIZED) |162| CO\_NEWLOCALS | [`inspect.CO_NEWLOCALS`](https://python-all.ru/3.15/library/inspect.html#inspect.CO_NEWLOCALS) |163| CO\_VARARGS | [`inspect.CO_VARARGS`](https://python-all.ru/3.15/library/inspect.html#inspect.CO_VARARGS) |164| CO\_VARKEYWORDS | [`inspect.CO_VARKEYWORDS`](https://python-all.ru/3.15/library/inspect.html#inspect.CO_VARKEYWORDS) |165| CO\_NESTED | [`inspect.CO_NESTED`](https://python-all.ru/3.15/library/inspect.html#inspect.CO_NESTED) |166| CO\_GENERATOR | [`inspect.CO_GENERATOR`](https://python-all.ru/3.15/library/inspect.html#inspect.CO_GENERATOR) |167| CO\_COROUTINE | [`inspect.CO_COROUTINE`](https://python-all.ru/3.15/library/inspect.html#inspect.CO_COROUTINE) |168| CO\_ITERABLE\_COROUTINE | [`inspect.CO_ITERABLE_COROUTINE`](https://python-all.ru/3.15/library/inspect.html#inspect.CO_ITERABLE_COROUTINE) |169| CO\_ASYNC\_GENERATOR | [`inspect.CO_ASYNC_GENERATOR`](https://python-all.ru/3.15/library/inspect.html#inspect.CO_ASYNC_GENERATOR) |170| CO\_HAS\_DOCSTRING | [`inspect.CO_HAS_DOCSTRING`](https://python-all.ru/3.15/library/inspect.html#inspect.CO_HAS_DOCSTRING) |171| CO\_METHOD | [`inspect.CO_METHOD`](https://python-all.ru/3.15/library/inspect.html#inspect.CO_METHOD) |172| CO\_FUTURE\_DIVISION | не имеет эффекта ([`__future__.division`](https://python-all.ru/3.15/library/__future__.html#future__.division)) |173| CO\_FUTURE\_ABSOLUTE\_IMPORT | не имеет эффекта ([`__future__.absolute_import`](https://python-all.ru/3.15/library/__future__.html#future__.absolute_import)) |174| CO\_FUTURE\_WITH\_STATEMENT | не имеет эффекта ([`__future__.with_statement`](https://python-all.ru/3.15/library/__future__.html#future__.with_statement)) |175| CO\_FUTURE\_PRINT\_FUNCTION | не имеет эффекта ([`__future__.print_function`](https://python-all.ru/3.15/library/__future__.html#future__.print_function)) |176| CO\_FUTURE\_UNICODE\_LITERALS | не имеет эффекта ([`__future__.unicode_literals`](https://python-all.ru/3.15/library/__future__.html#future__.unicode_literals)) |177| CO\_FUTURE\_GENERATOR\_STOP | не имеет эффекта ([`__future__.generator_stop`](https://python-all.ru/3.15/library/__future__.html#future__.generator_stop)) |178| CO\_FUTURE\_ANNOTATIONS | [`__future__.annotations`](https://python-all.ru/3.15/library/__future__.html#future__.annotations) |179180# Дополнительная информация181182Для поддержки низкоуровневых расширений механизма вычисления кадров, таких как внешние JIT-компиляторы, к объектам кода можно прикреплять произвольные дополнительные данные.183184Эти функции относятся к нестабильному уровню C API: данная функциональность является деталью реализации CPython, и API может измениться без предупреждения об устаревании.185186#### `Py_ssize_t PyUnstable_Eval_RequestCodeExtraIndex(freefunc free)`187188> *Это [нестабильное API](https://python-all.ru/3.15/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*189190Возвращает новое непрозрачное значение индекса, используемое для добавления данных к объектам кода.191192Обычно эту функцию вызывают один раз (на каждый интерпретатор) и используют полученный результат с `PyCode_GetExtra` и `PyCode_SetExtra` для управления данными на отдельных объектах кода.193194Если *free* не равен `NULL`: при освобождении объекта кода будет вызван *free* для данных, не являющихся `NULL`, хранящихся под новым индексом. Используйте [`Py_DecRef()`](https://python-all.ru/3.15/c-api/refcounting.html#c.Py_DecRef) при хранении [`PyObject`](https://python-all.ru/3.15/c-api/structures.html#c.PyObject).195196Добавлено в версии 3.6: как `_PyEval_RequestCodeExtraIndex`197198Изменено в версии 3.12: Переименовано в `PyUnstable_Eval_RequestCodeExtraIndex`. Старое приватное имя устарело, но будет доступно до изменения API.199200#### `int PyUnstable_Code_GetExtra(PyObject *code, Py_ssize_t index, void **extra)`201202> *Это [нестабильное API](https://python-all.ru/3.15/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*203204Устанавливает *extra* в дополнительные данные, хранящиеся по указанному индексу. Возвращает 0 в случае успеха. В случае ошибки устанавливает исключение и возвращает -1.205206Если по индексу не было установлено никаких данных, устанавливает *extra* в `NULL` и возвращает 0 без установки исключения.207208Добавлено в версии 3.6: как `_PyCode_GetExtra`209210Изменено в версии 3.12: Переименовано в `PyUnstable_Code_GetExtra`. Старое приватное имя устарело, но будет доступно до изменения API.211212#### `int PyUnstable_Code_SetExtra(PyObject *code, Py_ssize_t index, void *extra)`213214> *Это [нестабильное API](https://python-all.ru/3.15/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*215216Устанавливает дополнительные данные, хранящиеся по указанному индексу, в *extra*. Возвращает 0 в случае успеха. В случае ошибки устанавливает исключение и возвращает -1.217218Добавлено в версии 3.6: как `_PyCode_SetExtra`219220Изменено в версии 3.12: Переименовано в `PyUnstable_Code_SetExtra`. Старое приватное имя устарело, но будет доступно до изменения API.221