`veryhigh.md`

208 строк · 23.2 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.2/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.2/library/exceptions.html#SystemExit), эта функция не вернёт `1`, а завершит процесс, при условии, что флаг `Py_InspectFlag` не установлен.2021#### `int PyRun_AnyFile(FILE *fp, const char *filename)`2223Это упрощённый интерфейс к [`PyRun_AnyFileExFlags()`](https://python-all.ru/3.2/c-api/veryhigh.html#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.2/c-api/veryhigh.html#PyRun_AnyFileExFlags) (см. ниже), в котором аргумент *closeit* установлен в `0`.2829#### `int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)`3031Это упрощённый интерфейс к [`PyRun_AnyFileExFlags()`](https://python-all.ru/3.2/c-api/veryhigh.html#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.2/c-api/veryhigh.html#PyRun_InteractiveLoop); в противном случае возвращает результат [`PyRun_SimpleFile()`](https://python-all.ru/3.2/c-api/veryhigh.html#PyRun_SimpleFile). *filename* декодируется из кодировки файловой системы ([`sys.getfilesystemencoding()`](https://python-all.ru/3.2/library/sys.html#sys.getfilesystemencoding)). Если *filename* равно *NULL*, эта функция использует `"???"` в качестве имени файла.3637#### `int PyRun_SimpleString(const char *command)`3839Это упрощённый интерфейс к [`PyRun_SimpleStringFlags()`](https://python-all.ru/3.2/c-api/veryhigh.html#PyRun_SimpleStringFlags) (см. ниже), в котором аргумент *PyCompilerFlags\** установлен в NULL.4041#### `int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)`4243Выполняет исходный код Python из *command* в модуле [`__main__`](https://python-all.ru/3.2/library/__main__.html#module-__main__) в соответствии с аргументом *flags*. Если модуль [`__main__`](https://python-all.ru/3.2/library/__main__.html#module-__main__) ещё не существует, он создаётся. Возвращает `0` при успехе или `-1`, если было возбуждено исключение. В случае ошибки получить информацию об исключении невозможно. О значении *flags* см. ниже.4445Обратите внимание, что если возникнет неперехваченное исключение [`SystemExit`](https://python-all.ru/3.2/library/exceptions.html#SystemExit), эта функция не вернёт `-1`, а завершит процесс, при условии, что флаг `Py_InspectFlag` не установлен.4647#### `int PyRun_SimpleFile(FILE *fp, const char *filename)`4849Это упрощённый интерфейс к [`PyRun_SimpleFileExFlags()`](https://python-all.ru/3.2/c-api/veryhigh.html#PyRun_SimpleFileExFlags) (см. ниже), в котором *closeit* установлен в `0`, а *flags* – в *NULL*.5051#### `int PyRun_SimpleFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)`5253Это упрощённый интерфейс к [`PyRun_SimpleFileExFlags()`](https://python-all.ru/3.2/c-api/veryhigh.html#PyRun_SimpleFileExFlags) ниже, оставляя *closeit* равным `0`.5455#### `int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)`5657Это упрощённый интерфейс к [`PyRun_SimpleFileExFlags()`](https://python-all.ru/3.2/c-api/veryhigh.html#PyRun_SimpleFileExFlags) (см. ниже), в котором *flags* установлен в *NULL*.5859#### `int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)`6061Аналогично [`PyRun_SimpleStringFlags()`](https://python-all.ru/3.2/c-api/veryhigh.html#PyRun_SimpleStringFlags), но исходный код Python читается из *fp*, а не из строки в памяти. *filename* должно быть именем файла; оно декодируется из кодировки файловой системы ([`sys.getfilesystemencoding()`](https://python-all.ru/3.2/library/sys.html#sys.getfilesystemencoding)). Если *closeit* истинно, файл закрывается до возврата из PyRun\_SimpleFileExFlags.6263#### `int PyRun_InteractiveOne(FILE *fp, const char *filename)`6465Это упрощённый интерфейс к [`PyRun_InteractiveOneFlags()`](https://python-all.ru/3.2/c-api/veryhigh.html#PyRun_InteractiveOneFlags) (см. ниже), в котором *flags* установлен в *NULL*.6667#### `int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)`6869Читает и выполняет один оператор из файла, связанного с интерактивным устройством, в соответствии с аргументом *flags*. Пользователю будет выведено приглашение с помощью `sys.ps1` и `sys.ps2`. *filename* декодируется из кодировки файловой системы ([`sys.getfilesystemencoding()`](https://python-all.ru/3.2/library/sys.html#sys.getfilesystemencoding)).7071Возвращает `0` при успешном выполнении ввода, `-1` при возникновении исключения или код ошибки из заголовочного файла `errcode.h`, распространяемого в составе Python, в случае синтаксической ошибки. (Обратите внимание, что `errcode.h` не включается в `Python.h`, поэтому при необходимости его нужно включать отдельно.)7273#### `int PyRun_InteractiveLoop(FILE *fp, const char *filename)`7475Это упрощённый интерфейс к [`PyRun_InteractiveLoopFlags()`](https://python-all.ru/3.2/c-api/veryhigh.html#PyRun_InteractiveLoopFlags) (см. ниже), в котором *flags* установлен в *NULL*.7677#### `int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)`7879Читает и выполняет инструкции из файла, связанного с интерактивным устройством, до достижения EOF. Пользователю будет выводиться приглашение с помощью `sys.ps1` и `sys.ps2`. *filename* декодируется из кодировки файловой системы ([`sys.getfilesystemencoding()`](https://python-all.ru/3.2/library/sys.html#sys.getfilesystemencoding)). Возвращает `0` при EOF.8081#### `struct _node* PyParser_SimpleParseString(const char *str, int start)`8283Это упрощённый интерфейс к [`PyParser_SimpleParseStringFlagsFilename()`](https://python-all.ru/3.2/c-api/veryhigh.html#PyParser_SimpleParseStringFlagsFilename) ниже, оставляя *filename* установленным в *NULL*, а *flags* – в `0`.8485#### `struct _node* PyParser_SimpleParseStringFlags(const char *str, int start, int flags)`8687Это упрощённый интерфейс к [`PyParser_SimpleParseStringFlagsFilename()`](https://python-all.ru/3.2/c-api/veryhigh.html#PyParser_SimpleParseStringFlagsFilename) ниже, оставляя *filename* установленным в *NULL*.8889#### `struct _node* PyParser_SimpleParseStringFlagsFilename(const char *str, const char *filename, int start, int flags)`9091Разбирает исходный код Python из *str*, используя начальный токен *start* в соответствии с аргументом *flags*. Результат можно использовать для создания объекта кода, который может вычисляться эффективно. Это полезно, если фрагмент кода должен вычисляться много раз. *filename* декодируется из кодировки файловой системы ([`sys.getfilesystemencoding()`](https://python-all.ru/3.2/library/sys.html#sys.getfilesystemencoding)).9293#### `struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)`9495Это упрощённый интерфейс к [`PyParser_SimpleParseFileFlags()`](https://python-all.ru/3.2/c-api/veryhigh.html#PyParser_SimpleParseFileFlags) ниже, оставляя *flags* равным `0`9697#### `struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)`9899Аналогично [`PyParser_SimpleParseStringFlagsFilename()`](https://python-all.ru/3.2/c-api/veryhigh.html#PyParser_SimpleParseStringFlagsFilename), но исходный код Python читается из *fp* вместо строки в памяти.100101#### `PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)`102103*Возвращаемое значение: новая ссылка.*104105Это упрощённый интерфейс к [`PyRun_StringFlags()`](https://python-all.ru/3.2/c-api/veryhigh.html#PyRun_StringFlags) ниже, оставляя *flags* установленным в *NULL*.106107#### `PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)`108109*Возвращаемое значение: новая ссылка.*110111Выполняет исходный код Python из *str* в контексте, заданном словарями *globals* и *locals*, с флагами компилятора, указанными в *flags*. Параметр *start* задаёт начальный токен, который следует использовать для разбора исходного кода.112113Возвращает результат выполнения кода в виде объекта Python или *NULL*, если возникло исключение.114115#### `PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)`116117*Возвращаемое значение: новая ссылка.*118119Это упрощённый интерфейс к [`PyRun_FileExFlags()`](https://python-all.ru/3.2/c-api/veryhigh.html#PyRun_FileExFlags) ниже, оставляя *closeit* установленным в `0`, а *flags* – в *NULL*.120121#### `PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)`122123*Возвращаемое значение: новая ссылка.*124125Это упрощённый интерфейс к [`PyRun_FileExFlags()`](https://python-all.ru/3.2/c-api/veryhigh.html#PyRun_FileExFlags) ниже, оставляя *flags* установленным в *NULL*.126127#### `PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)`128129*Возвращаемое значение: новая ссылка.*130131Это упрощённый интерфейс к [`PyRun_FileExFlags()`](https://python-all.ru/3.2/c-api/veryhigh.html#PyRun_FileExFlags) ниже, оставляя *closeit* установленным в `0`.132133#### `PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)`134135*Возвращаемое значение: новая ссылка.*136137Аналогично [`PyRun_StringFlags()`](https://python-all.ru/3.2/c-api/veryhigh.html#PyRun_StringFlags), но исходный код Python читается из *fp* вместо строки в памяти. *filename* должен быть именем файла, он декодируется из кодировки файловой системы ([`sys.getfilesystemencoding()`](https://python-all.ru/3.2/library/sys.html#sys.getfilesystemencoding)). Если *closeit* истинно, файл закрывается до того, как [`PyRun_FileExFlags()`](https://python-all.ru/3.2/c-api/veryhigh.html#PyRun_FileExFlags) вернёт результат.138139#### `PyObject* Py_CompileString(const char *str, const char *filename, int start)`140141*Возвращаемое значение: новая ссылка.*142143Это упрощённый интерфейс к [`Py_CompileStringFlags()`](https://python-all.ru/3.2/c-api/veryhigh.html#Py_CompileStringFlags) ниже, оставляя *flags* установленным в *NULL*.144145#### `PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)`146147*Возвращаемое значение: новая ссылка.*148149Это упрощённый интерфейс к [`Py_CompileStringExFlags()`](https://python-all.ru/3.2/c-api/veryhigh.html#Py_CompileStringExFlags), приведённой ниже, с *optimize*, установленным в `-1`.150151#### `PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)`152153Разбирает и компилирует исходный код Python из *str*, возвращая результирующий объект кода. Начальный токен задаётся *start*; его можно использовать для ограничения компилируемого кода, и он должен быть `Py_eval_input`, `Py_file_input` или `Py_single_input`. Имя файла, указанное в *filename*, используется для создания объекта кода и может появляться в трассировках или сообщениях исключений [`SyntaxError`](https://python-all.ru/3.2/library/exceptions.html#SyntaxError), оно декодируется из кодировки файловой системы ([`sys.getfilesystemencoding()`](https://python-all.ru/3.2/library/sys.html#sys.getfilesystemencoding)). Возвращает *NULL*, если код не может быть разобран или скомпилирован.154155Целое число *optimize* задаёт уровень оптимизации компилятора; значение `-1` выбирает уровень оптимизации интерпретатора, заданный опциями [*-O*](https://python-all.ru/3.2/using/cmdline.html#cmdoption-O). Явные уровни: `0` (без оптимизации; `__debug__` равен true), `1` (утверждения удалены, `__debug__` равен false) или `2` (докстроки также удалены).156157Новое в версии 3.2.158159#### `PyObject* PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)`160161*Возвращаемое значение: новая ссылка.*162163Это упрощённый интерфейс к [`PyEval_EvalCodeEx()`](https://python-all.ru/3.2/c-api/veryhigh.html#PyEval_EvalCodeEx), принимающий только объект кода и словари глобальных и локальных переменных. Остальные аргументы устанавливаются в *NULL*.164165#### `PyObject* PyEval_EvalCodeEx(PyObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *closure)`166167Выполняет предварительно скомпилированный объект кода в заданном окружении. Это окружение состоит из словарей глобальных и локальных переменных, массивов аргументов, ключевых слов и значений по умолчанию, а также кортежа замыкания с ячейками.168169#### `PyObject* PyEval_EvalFrame(PyFrameObject *f)`170171Выполняет фрейм исполнения. Это упрощённый интерфейс к PyEval\_EvalFrameEx для обратной совместимости.172173#### `PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)`174175Это основная, неприукрашенная функция интерпретации Python. Она буквально состоит из 2000 строк. Кодовый объект, связанный с фреймом выполнения *f*, выполняется: байт-код интерпретируется, а вызовы выполняются по мере необходимости. Дополнительным параметром *throwflag* в основном можно пренебречь – если он истинен, то немедленно вызывается исключение; это используется для методов `throw()` объектов-генераторов.176177#### `int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)`178179Эта функция изменяет флаги текущего фрейма вычислений и возвращает true в случае успеха, false в случае ошибки.180181**int `Py_eval_input`**182183Начальный символ из грамматики Python для изолированных выражений; используется с [`Py_CompileString()`](https://python-all.ru/3.2/c-api/veryhigh.html#Py_CompileString).184185**int `Py_file_input`**186187Начальный символ из грамматики Python для последовательностей инструкций, читаемых из файла или другого источника; используется с [`Py_CompileString()`](https://python-all.ru/3.2/c-api/veryhigh.html#Py_CompileString). Это символ для компиляции произвольно длинного исходного кода Python.188189**int `Py_single_input`**190191Начальный символ из грамматики Python для одной инструкции; используется с [`Py_CompileString()`](https://python-all.ru/3.2/c-api/veryhigh.html#Py_CompileString). Это символ, используемый в цикле интерактивного интерпретатора.192193**struct `PyCompilerFlags`**194195Это структура, используемая для хранения флагов компилятора. Когда код только компилируется, она передаётся как `int flags`, а когда код выполняется – как `PyCompilerFlags *flags`. В последнем случае `from __future__ import` может изменять *flags*.196197Когда `PyCompilerFlags *flags` равен *NULL*, `cf_flags` считается равным `0`, и любые изменения, внесённые `from __future__ import`, отбрасываются.198199```c200struct PyCompilerFlags {201    int cf_flags;202}203```204205**int `CO_FUTURE_DIVISION`**206207Этот бит можно установить в *flags*, чтобы оператор деления `/` интерпретировался как «истинное деление» в соответствии с [**PEP 238**](https://python-all.ru/3.2/c-api/veryhigh.html).208