`veryhigh.md`

228 строк · 26.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.6/c-api/veryhigh.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Слой очень высокого уровня89Функции этой главы позволяют выполнять исходный код Python, переданный в файле или буфере, но не дают возможности взаимодействовать с интерпретатором на более детальном уровне.1011Некоторые из этих функций принимают начальный символ из грамматики в качестве параметра. Доступные начальные символы: `Py_eval_input`, `Py_file_input` и `Py_single_input`. Они описаны после функций, которые принимают их в качестве параметров.1213Обратите также внимание, что некоторые из этих функций принимают параметры `FILE*`. Одна из проблем, требующих особой осторожности, заключается в том, что структура `FILE` для разных C-библиотек может быть разной и несовместимой. В Windows (по крайней мере) динамически связанные расширения могут использовать разные библиотеки, поэтому следует быть внимательным и передавать параметры `FILE*` этим функциям только в том случае, если есть уверенность, что они созданы той же библиотекой, которую использует среда выполнения Python.1415#### `int Py_Main(int argc, wchar_t **argv)`1617Главная программа стандартного интерпретатора. Она доступна для программ, встраивающих Python. Параметры *argc* и *argv* следует подготовить так же, как они передаются функции `main()` программы на C (с преобразованием в wchar\_t в соответствии с локалью пользователя). Важно отметить, что список аргументов может быть изменён (но содержимое строк, на которые он указывает, не изменяется). Возвращаемое значение будет `0` при нормальном завершении интерпретатора (то есть без исключения), `1` при завершении из-за исключения или `2`, если список параметров не представляет собой допустимую командную строку Python.1819Обратите внимание: если возникло необрабатываемое иначе исключение [`SystemExit`](https://python-all.ru/3.6/library/exceptions.html#SystemExit), эта функция не возвращает `1`, а завершает процесс, при условии, что `Py_InspectFlag` не установлен.2021#### `int PyRun_AnyFile(FILE *fp, const char *filename)`2223Это упрощённый интерфейс к [`PyRun_AnyFileExFlags()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyRun_AnyFileExFlags) ниже; *closeit* устанавливается в `0`, а *flags* – в *NULL*.2425#### `int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)`2627Это упрощённый интерфейс к [`PyRun_AnyFileExFlags()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyRun_AnyFileExFlags) (см. ниже); аргумент *closeit* оставлен равным `0`.2829#### `int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)`3031Это упрощённый интерфейс к [`PyRun_AnyFileExFlags()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyRun_AnyFileExFlags) ниже; аргумент *flags* устанавливается в *NULL*.3233#### `int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)`3435Если *fp* ссылается на файл, связанный с интерактивным устройством (консоль, терминальный ввод или псевдотерминал Unix), возвращается значение [`PyRun_InteractiveLoop()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyRun_InteractiveLoop); в противном случае возвращается результат [`PyRun_SimpleFile()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyRun_SimpleFile). *filename* декодируется из кодировки файловой системы ([`sys.getfilesystemencoding()`](https://python-all.ru/3.6/library/sys.html#sys.getfilesystemencoding)). Если *filename* равно *NULL*, эта функция использует `"???"` в качестве имени файла.3637#### `int PyRun_SimpleString(const char *command)`3839Это упрощённый интерфейс к [`PyRun_SimpleStringFlags()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyRun_SimpleStringFlags) ниже; аргумент *PyCompilerFlags\** устанавливается в NULL.4041#### `int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)`4243Выполняет исходный код Python из *command* в модуле [`__main__`](https://python-all.ru/3.6/library/__main__.html#module-__main__) в соответствии с аргументом *flags*. Если [`__main__`](https://python-all.ru/3.6/library/__main__.html#module-__main__) не существует, он создаётся. Возвращает `0` при успехе или `-1`, если было возбуждено исключение. В случае ошибки получить информацию об исключении невозможно. Значение *flags* описано ниже.4445Обратите внимание: если возникло необрабатываемое иначе исключение [`SystemExit`](https://python-all.ru/3.6/library/exceptions.html#SystemExit), эта функция не возвращает `-1`, а завершает процесс, при условии, что `Py_InspectFlag` не установлен.4647#### `int PyRun_SimpleFile(FILE *fp, const char *filename)`4849Это упрощённый интерфейс к [`PyRun_SimpleFileExFlags()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyRun_SimpleFileExFlags) ниже; *closeit* устанавливается в `0`, а *flags* – в *NULL*.5051#### `int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)`5253Это упрощённый интерфейс к [`PyRun_SimpleFileExFlags()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyRun_SimpleFileExFlags) ниже; *flags* устанавливается в *NULL*.5455#### `int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)`5657Похоже на [`PyRun_SimpleStringFlags()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyRun_SimpleStringFlags), но исходный код Python читается из *fp* вместо строки в памяти. *filename* должно быть именем файла, оно декодируется из кодировки файловой системы ([`sys.getfilesystemencoding()`](https://python-all.ru/3.6/library/sys.html#sys.getfilesystemencoding)). Если *closeit* истинно, файл закрывается до возврата PyRun\_SimpleFileExFlags.5859#### `int PyRun_InteractiveOne(FILE *fp, const char *filename)`6061Это упрощённый интерфейс к [`PyRun_InteractiveOneFlags()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyRun_InteractiveOneFlags) ниже; *flags* устанавливается в *NULL*.6263#### `int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)`6465Читает и выполняет одну инструкцию из файла, связанного с интерактивным устройством, в соответствии с аргументом *flags*. Пользователю будет предложено с помощью `sys.ps1` и `sys.ps2`. *filename* декодируется из кодировки файловой системы ([`sys.getfilesystemencoding()`](https://python-all.ru/3.6/library/sys.html#sys.getfilesystemencoding)).6667Возвращает `0` при успешном выполнении ввода, `-1` при возникновении исключения или код ошибки из заголовочного файла `errcode.h`, распространяемого в составе Python, в случае ошибки синтаксического анализа. (Обратите внимание, что `errcode.h` не включается `Python.h`, поэтому при необходимости его нужно включать отдельно.)6869#### `int PyRun_InteractiveLoop(FILE *fp, const char *filename)`7071Это упрощённый интерфейс к [`PyRun_InteractiveLoopFlags()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyRun_InteractiveLoopFlags) ниже; *flags* устанавливается в *NULL*.7273#### `int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)`7475Читает и выполняет инструкции из файла, связанного с интерактивным устройством, до достижения EOF. Пользователю будет предложено с помощью `sys.ps1` и `sys.ps2`. *filename* декодируется из кодировки файловой системы ([`sys.getfilesystemencoding()`](https://python-all.ru/3.6/library/sys.html#sys.getfilesystemencoding)). Возвращает `0` при EOF или отрицательное число в случае ошибки.7677**int `(*PyOS_InputHook)`(void)**7879Можно установить так, чтобы указывать на функцию с прототипом `int func(void)`. Эта функция будет вызываться, когда приглашение интерпретатора Python готовится перейти в состояние ожидания и ждёт ввода пользователя с терминала. Возвращаемое значение игнорируется. Переопределение этого хука можно использовать для интеграции приглашения интерпретатора с другими циклами событий, как это сделано в `Modules/_tkinter.c` в исходном коде Python.8081**char\* `(*PyOS_ReadlineFunctionPointer)`(FILE *\**, FILE *\**, const char *\**)**8283Может быть установлен для указания на функцию с прототипом `char *func(FILE *stdin, FILE *stdout, char *prompt)`, заменяя стандартную функцию, используемую для чтения одной строки ввода в приглашении интерпретатора. Функция должна вывести строку *prompt*, если она не равна *NULL*, а затем прочитать строку ввода из предоставленного стандартного входного файла и вернуть полученную строку. Например, модуль [`readline`](https://python-all.ru/3.6/library/readline.html#module-readline) устанавливает этот хук для обеспечения функций редактирования строки и автодополнения по табуляции.8485Результат должен быть строкой, выделенной с помощью [`PyMem_RawMalloc()`](https://python-all.ru/3.6/c-api/memory.html#c.PyMem_RawMalloc) или [`PyMem_RawRealloc()`](https://python-all.ru/3.6/c-api/memory.html#c.PyMem_RawRealloc), или *NULL* в случае ошибки.8687Изменено в версии 3.4: Результат должен выделяться с помощью [`PyMem_RawMalloc()`](https://python-all.ru/3.6/c-api/memory.html#c.PyMem_RawMalloc) или [`PyMem_RawRealloc()`](https://python-all.ru/3.6/c-api/memory.html#c.PyMem_RawRealloc), а не с помощью [`PyMem_Malloc()`](https://python-all.ru/3.6/c-api/memory.html#c.PyMem_Malloc) или [`PyMem_Realloc()`](https://python-all.ru/3.6/c-api/memory.html#c.PyMem_Realloc).8889#### `struct _node* PyParser_SimpleParseString(const char *str, int start)`9091Это упрощённый интерфейс к [`PyParser_SimpleParseStringFlagsFilename()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyParser_SimpleParseStringFlagsFilename) ниже; *filename* устанавливается в *NULL*, а *flags* – в `0`.9293#### `struct _node* PyParser_SimpleParseStringFlags(const char *str, int start, int flags)`9495Это упрощённый интерфейс к [`PyParser_SimpleParseStringFlagsFilename()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyParser_SimpleParseStringFlagsFilename) ниже; *filename* устанавливается в *NULL*.9697#### `struct _node* PyParser_SimpleParseStringFlagsFilename(const char *str, const char *filename, int start, int flags)`9899Разбирает исходный код Python из *str*, используя начальный токен *start*, в соответствии с аргументом *flags*. Результат можно использовать для создания объекта кода, который можно эффективно выполнять. Это полезно, если фрагмент кода нужно выполнить много раз. *filename* декодируется из кодировки файловой системы ([`sys.getfilesystemencoding()`](https://python-all.ru/3.6/library/sys.html#sys.getfilesystemencoding)).100101#### `struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)`102103Это упрощённый интерфейс к [`PyParser_SimpleParseFileFlags()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyParser_SimpleParseFileFlags) (см. ниже), в котором параметр *flags* установлен в `0`.104105#### `struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)`106107Похоже на [`PyParser_SimpleParseStringFlagsFilename()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyParser_SimpleParseStringFlagsFilename), но исходный код Python читается из *fp* вместо строки в памяти.108109#### `PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)`110111*Возвращаемое значение: новая ссылка.*112113Это упрощённый интерфейс к [`PyRun_StringFlags()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyRun_StringFlags) ниже; *flags* устанавливается в *NULL*.114115#### `PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)`116117*Возвращаемое значение: новая ссылка.*118119Выполняет исходный код Python из *str* в контексте, заданном объектами *globals* и *locals*, с флагами компилятора, указанными в *flags*. *globals* должен быть словарём; *locals* может быть любым объектом, реализующим протокол отображения. Параметр *start* задаёт начальный токен, который следует использовать для разбора исходного кода.120121Возвращает результат выполнения кода в виде объекта Python или *NULL*, если возникло исключение.122123#### `PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)`124125*Возвращаемое значение: новая ссылка.*126127Это упрощённый интерфейс к [`PyRun_FileExFlags()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyRun_FileExFlags) (см. ниже), который оставляет *closeit* установленным в `0`, а *flags* – в *NULL*.128129#### `PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)`130131*Возвращаемое значение: новая ссылка.*132133Это упрощённый интерфейс к [`PyRun_FileExFlags()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyRun_FileExFlags) (см. ниже), оставляющий *flags* установленным в *NULL*.134135#### `PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)`136137*Возвращаемое значение: новая ссылка.*138139Это упрощённый интерфейс к [`PyRun_FileExFlags()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyRun_FileExFlags) (см. ниже), в котором параметр *closeit* установлен в `0`.140141#### `PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)`142143*Возвращаемое значение: новая ссылка.*144145Подобна [`PyRun_StringFlags()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyRun_StringFlags), но исходный код Python читается из *fp*, а не из строки в памяти. *filename* должно быть именем файла; оно декодируется из кодировки файловой системы ([`sys.getfilesystemencoding()`](https://python-all.ru/3.6/library/sys.html#sys.getfilesystemencoding)). Если *closeit* истинно, файл закрывается до того, как [`PyRun_FileExFlags()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyRun_FileExFlags) вернет результат.146147#### `PyObject* Py_CompileString(const char *str, const char *filename, int start)`148149*Возвращаемое значение: новая ссылка.*150151Это упрощённый интерфейс к [`Py_CompileStringFlags()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.Py_CompileStringFlags) (см. ниже), оставляющий *flags* установленным в *NULL*.152153#### `PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)`154155*Возвращаемое значение: новая ссылка.*156157Это упрощённый интерфейс к [`Py_CompileStringExFlags()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.Py_CompileStringExFlags) (см. ниже), в котором параметр *optimize* установлен в `-1`.158159#### `PyObject* Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)`160161Разбирает и компилирует исходный код Python из *str*, возвращая результирующий объект кода. Токен начала задаётся параметром *start*; его можно использовать для ограничения компилируемого кода; он должен быть `Py_eval_input`, `Py_file_input` или `Py_single_input`. Имя файла, указанное в *filename*, используется для создания объекта кода и может появляться в трассировках или сообщениях об исключениях [`SyntaxError`](https://python-all.ru/3.6/library/exceptions.html#SyntaxError). Возвращает *NULL*, если код не удаётся разобрать или скомпилировать.162163Целое число *optimize* задаёт уровень оптимизации компилятора; значение `-1` выбирает уровень оптимизации интерпретатора, заданный опциями [`-O`](https://python-all.ru/3.6/using/cmdline.html#cmdoption-o). Явные уровни: `0` (без оптимизации; `__debug__` истинно), `1` (утверждения удалены, `__debug__` ложно) или `2` (докстринги также удалены).164165Новое в версии 3.4.166167#### `PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)`168169Как и [`Py_CompileStringObject()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.Py_CompileStringObject), но *filename* – это байтовая строка, декодированная из файловой системной кодировки ([`os.fsdecode()`](https://python-all.ru/3.6/library/os.html#os.fsdecode)).170171Новое в версии 3.2.172173#### `PyObject* PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)`174175*Возвращаемое значение: новая ссылка.*176177Это упрощённый интерфейс к [`PyEval_EvalCodeEx()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyEval_EvalCodeEx), принимающий только объект кода, глобальные и локальные переменные. Остальные аргументы устанавливаются в *NULL*.178179#### `PyObject* PyEval_EvalCodeEx(PyObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *kwdefs, PyObject *closure)`180181Выполняет предварительно скомпилированный объект кода в заданном окружении для его вычисления. Это окружение состоит из словаря глобальных переменных, объекта отображения локальных переменных, массивов аргументов, ключевых слов и значений по умолчанию, словаря значений по умолчанию для [только ключевых](https://python-all.ru/3.6/glossary.html#keyword-only-parameter) аргументов и кортежа замыкания с ячейками.182183**`PyFrameObject`**184185C-структура объектов, используемых для описания объектов фреймов. Поля этого типа могут быть изменены в любой момент.186187#### `PyObject* PyEval_EvalFrame(PyFrameObject *f)`188189Выполняет фрейм исполнения. Это упрощённый интерфейс к [`PyEval_EvalFrameEx()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.PyEval_EvalFrameEx), обеспечивающий обратную совместимость.190191#### `PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)`192193Это основная, неприукрашенная функция интерпретации Python. Она буквально насчитывает 2000 строк. Код объекта *f*, связанный с фреймом выполнения, выполняется: интерпретируются байткод и по мере необходимости выполняются вызовы. Дополнительный параметр *throwflag* в основном можно игнорировать – если он истинный, то немедленно выбрасывается исключение; это используется для методов [`throw()`](https://python-all.ru/3.6/reference/expressions.html#generator.throw) объектов-генераторов.194195Изменено в версии 3.4: Эта функция теперь включает отладочное утверждение, помогающее гарантировать, что она не игнорирует активное исключение без уведомления.196197#### `int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)`198199Эта функция изменяет флаги текущего фрейма вычислений и возвращает true в случае успеха, false в случае ошибки.200201**int `Py_eval_input`**202203Стартовый символ из грамматики Python для изолированных выражений; используется с [`Py_CompileString()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.Py_CompileString).204205**int `Py_file_input`**206207Стартовый символ из грамматики Python для последовательностей операторов, читаемых из файла или другого источника; используется с [`Py_CompileString()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.Py_CompileString). Это символ, который следует использовать при компиляции произвольно длинного исходного кода Python.208209**int `Py_single_input`**210211Начальный символ грамматики Python для одного оператора; используется с [`Py_CompileString()`](https://python-all.ru/3.6/c-api/veryhigh.html#c.Py_CompileString). Этот символ используется в интерактивном цикле интерпретатора.212213**struct `PyCompilerFlags`**214215Это структура, используемая для хранения флагов компилятора. Если код только компилируется, она передаётся как `int flags`, а если код выполняется, она передаётся как `PyCompilerFlags *flags`. В этом случае `from __future__ import` может изменять *flags*.216217Если `PyCompilerFlags *flags` равно *NULL*, то `cf_flags` считается равным `0`, а все изменения, связанные с `from __future__ import`, отбрасываются.218219```c220struct PyCompilerFlags {221    int cf_flags;222}223```224225**int `CO_FUTURE_DIVISION`**226227Этот бит можно установить в *flags*, чтобы оператор деления `/` интерпретировался как «истинное деление» в соответствии с [**PEP 238**](https://python-all.ru/3.6/c-api/veryhigh.html).228