`veryhigh.md`

560 строк · 24.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.0/c-api/veryhigh.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Слой очень высокого уровня89Функции этой главы позволяют выполнять исходный код Python, переданный в файле или буфере, но не дают возможности взаимодействовать с интерпретатором на более детальном уровне.1011Некоторые из этих функций принимают в качестве параметра начальный символ из грамматики. Доступны следующие начальные символы: [`Py_eval_input`](https://python-all.ru/3.0/c-api/veryhigh.html#Py_eval_input), [`Py_file_input`](https://python-all.ru/3.0/c-api/veryhigh.html#Py_file_input) и [`Py_single_input`](https://python-all.ru/3.0/c-api/veryhigh.html#Py_single_input). Они описаны после функций, которые принимают их в качестве параметров.1213Отметим также, что некоторые из этих функций принимают параметры типа `FILE*`. Особая проблема, требующая внимания, заключается в том, что структура `FILE` может различаться и быть несовместимой в разных библиотеках C. По крайней мере в Windows динамически подключаемые расширения могут использовать разные библиотеки, поэтому следует быть осторожным: параметры `FILE*` следует передавать этим функциям только в том случае, если точно известно, что они созданы той же библиотекой, которую использует среда выполнения Python.1415**\[Py\_Main\]int `Py_Main`(int *argc*, wchar\_t *\*\*argv*)**1617Главная программа стандартного интерпретатора. Она доступна для программ, встраивающих Python. Параметры1819*argc*2021и2223*argv*2425должны быть подготовлены точно так же, как они передаются функции2627`main`2829программы на C (преобразованы в wchar\_t в соответствии с локалью пользователя). Список аргументов может изменяться (но содержимое строк, на которые указывает список аргументов, не изменяется). Возвращаемое значение – целое число, переданное функции3031[`sys.exit()`](https://python-all.ru/3.0/library/sys.html#sys.exit)3233,3435`1`3637если интерпретатор завершился из-за исключения, или3839`2`4041если список параметров не представляет допустимую командную строку Python.4243**\[PyRun\_AnyFile\]int `PyRun_AnyFile`(FILE *\*fp*, const char *\*filename*)**4445Это упрощённый интерфейс к4647[`PyRun_AnyFileExFlags`](https://python-all.ru/3.0/c-api/veryhigh.html#PyRun_AnyFileExFlags)4849(см. ниже), оставляющий5051*closeit*5253равным5455`0`5657, а5859*flags*6061– равным6263*NULL*6465.6667**\[PyRun\_AnyFileFlags\]int `PyRun_AnyFileFlags`(FILE *\*fp*, const char *\*filename*, [PyCompilerFlags](https://python-all.ru/3.0/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**6869Это упрощённый интерфейс к7071[`PyRun_AnyFileExFlags`](https://python-all.ru/3.0/c-api/veryhigh.html#PyRun_AnyFileExFlags)7273(см. ниже), оставляющий аргумент7475*closeit*7677равным7879`0`8081.8283**\[PyRun\_AnyFileEx\]int `PyRun_AnyFileEx`(FILE *\*fp*, const char *\*filename*, int *closeit*)**8485Это упрощённый интерфейс к8687[`PyRun_AnyFileExFlags`](https://python-all.ru/3.0/c-api/veryhigh.html#PyRun_AnyFileExFlags)8889(см. ниже), оставляющий аргумент9091*flags*9293равным9495*NULL*9697.9899**\[PyRun\_AnyFileExFlags\]int `PyRun_AnyFileExFlags`(FILE *\*fp*, const char *\*filename*, int *closeit*, [PyCompilerFlags](https://python-all.ru/3.0/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**100101Если102103*fp*104105указывает на файл, связанный с интерактивным устройством (консоль, терминальный ввод или псевдотерминал Unix), возвращается значение106107[`PyRun_InteractiveLoop`](https://python-all.ru/3.0/c-api/veryhigh.html#PyRun_InteractiveLoop)108109; в противном случае возвращается результат110111[`PyRun_SimpleFile`](https://python-all.ru/3.0/c-api/veryhigh.html#PyRun_SimpleFile)112113. Если114115*filename*116117равно118119*NULL*120121, эта функция использует122123`"???"`124125в качестве имени файла.126127**\[PyRun\_SimpleString\]int `PyRun_SimpleString`(const char *\*command*)**128129Это упрощённый интерфейс к130131[`PyRun_SimpleStringFlags`](https://python-all.ru/3.0/c-api/veryhigh.html#PyRun_SimpleStringFlags)132133(см. ниже), оставляющий аргумент134135*PyCompilerFlags\**136137равным NULL.138139**\[PyRun\_SimpleStringFlags\]int `PyRun_SimpleStringFlags`(const char *\*command*, [PyCompilerFlags](https://python-all.ru/3.0/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**140141Выполняет исходный код Python из142143*command*144145в модуле146147[`__main__`](https://python-all.ru/3.0/library/__main__.html#module-__main__)148149в соответствии с аргументом150151*flags*152153. Если модуль154155[`__main__`](https://python-all.ru/3.0/library/__main__.html#module-__main__)156157ещё не существует, он создаётся. Возвращает158159`0`160161при успехе или162163`-1`164165, если было возбуждено исключение. В случае ошибки получить информацию об исключении невозможно. О значении166167*flags*168169см. ниже.170171**\[PyRun\_SimpleFile\]int `PyRun_SimpleFile`(FILE *\*fp*, const char *\*filename*)**172173Это упрощённый интерфейс к174175[`PyRun_SimpleFileExFlags`](https://python-all.ru/3.0/c-api/veryhigh.html#PyRun_SimpleFileExFlags)176177(см. ниже), оставляющий178179*closeit*180181равным182183`0`184185, а186187*flags*188189– равным190191*NULL*192193.194195**\[PyRun\_SimpleFileFlags\]int `PyRun_SimpleFileFlags`(FILE *\*fp*, const char *\*filename*, [PyCompilerFlags](https://python-all.ru/3.0/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**196197Это упрощённый интерфейс к198199[`PyRun_SimpleFileExFlags`](https://python-all.ru/3.0/c-api/veryhigh.html#PyRun_SimpleFileExFlags)200201(см. ниже), оставляющий202203*closeit*204205равным206207`0`208209.210211**\[PyRun\_SimpleFileEx\]int `PyRun_SimpleFileEx`(FILE *\*fp*, const char *\*filename*, int *closeit*)**212213Это упрощённый интерфейс к214215[`PyRun_SimpleFileExFlags`](https://python-all.ru/3.0/c-api/veryhigh.html#PyRun_SimpleFileExFlags)216217(см. ниже), оставляющий218219*flags*220221равным222223*NULL*224225.226227**\[PyRun\_SimpleFileExFlags\]int `PyRun_SimpleFileExFlags`(FILE *\*fp*, const char *\*filename*, int *closeit*, [PyCompilerFlags](https://python-all.ru/3.0/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**228229Аналогично230231[`PyRun_SimpleStringFlags`](https://python-all.ru/3.0/c-api/veryhigh.html#PyRun_SimpleStringFlags)232233, но исходный код Python читается из234235*fp*236237, а не из строки в памяти.238239*filename*240241должно быть именем файла. Если242243*closeit*244245истинно, файл закрывается до возврата из PyRun\_SimpleFileExFlags.246247**\[PyRun\_InteractiveOne\]int `PyRun_InteractiveOne`(FILE *\*fp*, const char *\*filename*)**248249Это упрощённый интерфейс к250251[`PyRun_InteractiveOneFlags`](https://python-all.ru/3.0/c-api/veryhigh.html#PyRun_InteractiveOneFlags)252253(см. ниже), оставляющий254255*flags*256257равным258259*NULL*260261.262263**\[PyRun\_InteractiveOneFlags\]int `PyRun_InteractiveOneFlags`(FILE *\*fp*, const char *\*filename*, [PyCompilerFlags](https://python-all.ru/3.0/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**264265Читает и выполняет один оператор из файла, связанного с интерактивным устройством, в соответствии с аргументом266267*flags*268269. Если270271*filename*272273равно274275*NULL*276277, вместо него используется278279`"???"`280281. Пользователю выводятся приглашения282283`sys.ps1`284285и286287`sys.ps2`288289. Возвращает290291`0`292293, если ввод был выполнен успешно,294295`-1`296297, если произошло исключение, или код ошибки из файла298299`errcode.h`300301(входящего в состав Python), если была ошибка разбора. (302303`errcode.h`304305не включается через306307`Python.h`308309, поэтому его нужно включать отдельно, если необходимо.)310311**\[PyRun\_InteractiveLoop\]int `PyRun_InteractiveLoop`(FILE *\*fp*, const char *\*filename*)**312313Это упрощённый интерфейс к314315[`PyRun_InteractiveLoopFlags`](https://python-all.ru/3.0/c-api/veryhigh.html#PyRun_InteractiveLoopFlags)316317(см. ниже), оставляющий318319*flags*320321равным322323*NULL*324325.326327**\[PyRun\_InteractiveLoopFlags\]int `PyRun_InteractiveLoopFlags`(FILE *\*fp*, const char *\*filename*, [PyCompilerFlags](https://python-all.ru/3.0/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**328329Читает и выполняет операторы из файла, связанного с интерактивным устройством, до достижения EOF. Если330331*filename*332333равно334335*NULL*336337, используется338339`"???"`340341. Пользователю выводятся приглашения342343`sys.ps1`344345и346347`sys.ps2`348349. Возвращает350351`0`352353при EOF.354355**\[PyParser\_SimpleParseString\]struct \_node\* `PyParser_SimpleParseString`(const char *\*str*, int *start*)**356357Это упрощённый интерфейс к358359[`PyParser_SimpleParseStringFlagsFilename`](https://python-all.ru/3.0/c-api/veryhigh.html#PyParser_SimpleParseStringFlagsFilename)360361, описанной ниже, с362363*filename*364365, установленным в366367*NULL*368369, и370371*flags*372373, установленным в374375`0`376377.378379**\[PyParser\_SimpleParseStringFlags\]struct \_node\* `PyParser_SimpleParseStringFlags`(const char *\*str*, int *start*, int *flags*)**380381Это упрощённый интерфейс к382383[`PyParser_SimpleParseStringFlagsFilename`](https://python-all.ru/3.0/c-api/veryhigh.html#PyParser_SimpleParseStringFlagsFilename)384385, описанной ниже, с386387*filename*388389, установленным в390391*NULL*392393.394395**\[PyParser\_SimpleParseStringFlagsFilename\]struct \_node\* `PyParser_SimpleParseStringFlagsFilename`(const char *\*str*, const char *\*filename*, int *start*, int *flags*)**396397Анализирует исходный код Python из398399*str*400401, используя начальный токен402403*start*404405в соответствии с аргументом406407*flags*408409. Результат можно использовать для создания объекта кода, который может быть эффективно вычислен. Это полезно, если фрагмент кода должен вычисляться много раз.410411**\[PyParser\_SimpleParseFile\]struct \_node\* `PyParser_SimpleParseFile`(FILE *\*fp*, const char *\*filename*, int *start*)**412413Это упрощённый интерфейс к414415[`PyParser_SimpleParseFileFlags`](https://python-all.ru/3.0/c-api/veryhigh.html#PyParser_SimpleParseFileFlags)416417, описанной ниже, с418419*flags*420421, установленным в422423`0`424425**\[PyParser\_SimpleParseFileFlags\]struct \_node\* `PyParser_SimpleParseFileFlags`(FILE *\*fp*, const char *\*filename*, int *start*, int *flags*)**426427Аналогично428429[`PyParser_SimpleParseStringFlagsFilename`](https://python-all.ru/3.0/c-api/veryhigh.html#PyParser_SimpleParseStringFlagsFilename)430431, но исходный код Python читается из432433*fp*434435, а не из строки в памяти.436437**\[PyRun\_String\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyRun_String`(const char *\*str*, int *start*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*globals*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*locals*)**438439*Возвращаемое значение: новая ссылка.*440441Это упрощённый интерфейс к [`PyRun_StringFlags`](https://python-all.ru/3.0/c-api/veryhigh.html#PyRun_StringFlags), описанной ниже, с *flags*, установленным в *NULL*.442443**\[PyRun\_StringFlags\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyRun_StringFlags`(const char *\*str*, int *start*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*globals*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*locals*, [PyCompilerFlags](https://python-all.ru/3.0/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**444445*Возвращаемое значение: новая ссылка.*446447Выполняет исходный код Python из *str* в контексте, заданном словарями *globals* и *locals*, с флагами компилятора, указанными в *flags*. Параметр *start* задаёт начальный токен, который следует использовать для разбора исходного кода.448449Возвращает результат выполнения кода в виде объекта Python или *NULL*, если возникло исключение.450451**\[PyRun\_File\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyRun_File`(FILE *\*fp*, const char *\*filename*, int *start*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*globals*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*locals*)**452453*Возвращаемое значение: новая ссылка.*454455Это упрощённый интерфейс к [`PyRun_FileExFlags`](https://python-all.ru/3.0/c-api/veryhigh.html#PyRun_FileExFlags), описанной ниже, с *closeit*, установленным в `0`, и *flags*, установленным в *NULL*.456457**\[PyRun\_FileEx\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyRun_FileEx`(FILE *\*fp*, const char *\*filename*, int *start*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*globals*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*locals*, int *closeit*)**458459*Возвращаемое значение: новая ссылка.*460461Это упрощённый интерфейс к [`PyRun_FileExFlags`](https://python-all.ru/3.0/c-api/veryhigh.html#PyRun_FileExFlags), описанной ниже, с *flags*, установленным в *NULL*.462463**\[PyRun\_FileFlags\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyRun_FileFlags`(FILE *\*fp*, const char *\*filename*, int *start*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*globals*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*locals*, [PyCompilerFlags](https://python-all.ru/3.0/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**464465*Возвращаемое значение: новая ссылка.*466467Это упрощённый интерфейс к [`PyRun_FileExFlags`](https://python-all.ru/3.0/c-api/veryhigh.html#PyRun_FileExFlags), описанной ниже, с *closeit*, установленным в `0`.468469**\[PyRun\_FileExFlags\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyRun_FileExFlags`(FILE *\*fp*, const char *\*filename*, int *start*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*globals*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*locals*, int *closeit*, [PyCompilerFlags](https://python-all.ru/3.0/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**470471*Возвращаемое значение: новая ссылка.*472473Аналогично [`PyRun_StringFlags`](https://python-all.ru/3.0/c-api/veryhigh.html#PyRun_StringFlags), но исходный код Python читается из *fp*, а не из строки в памяти. *filename* должно быть именем файла. Если *closeit* истинно, файл закрывается перед тем, как [`PyRun_FileExFlags`](https://python-all.ru/3.0/c-api/veryhigh.html#PyRun_FileExFlags) вернёт управление.474475**\[Py\_CompileString\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `Py_CompileString`(const char *\*str*, const char *\*filename*, int *start*)**476477*Возвращаемое значение: новая ссылка.*478479Это упрощённый интерфейс к [`Py_CompileStringFlags`](https://python-all.ru/3.0/c-api/veryhigh.html#Py_CompileStringFlags), описанной ниже, с *flags*, установленным в *NULL*.480481**\[Py\_CompileStringFlags\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `Py_CompileStringFlags`(const char *\*str*, const char *\*filename*, int *start*, [PyCompilerFlags](https://python-all.ru/3.0/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**482483*Возвращаемое значение: новая ссылка.*484485Разбирает и компилирует исходный код Python из *str*, возвращая результирующий объект кода. Стартовый токен задаётся *start*; его можно использовать для ограничения компилируемого кода – он должен быть [`Py_eval_input`](https://python-all.ru/3.0/c-api/veryhigh.html#Py_eval_input), [`Py_file_input`](https://python-all.ru/3.0/c-api/veryhigh.html#Py_file_input) или [`Py_single_input`](https://python-all.ru/3.0/c-api/veryhigh.html#Py_single_input). Имя файла, указанное в *filename*, используется для создания объекта кода и может появляться в трассировках или сообщениях исключений [`SyntaxError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.SyntaxError). Возвращает *NULL*, если код не удаётся разобрать или скомпилировать.486487**\[PyEval\_EvalCode\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyEval_EvalCode`(PyCodeObject *\*co*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*globals*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*locals*)**488489*Возвращаемое значение: новая ссылка.*490491Это упрощённый интерфейс к [`PyEval_EvalCodeEx`](https://python-all.ru/3.0/c-api/veryhigh.html#PyEval_EvalCodeEx), принимающий только объект кода и словари глобальных и локальных переменных. Остальные аргументы установлены в *NULL*.492493**\[PyEval\_EvalCodeEx\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyEval_EvalCodeEx`(PyCodeObject *\*co*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*globals*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*locals*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*\*args*, int *argcount*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*\*kws*, int *kwcount*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*\*defs*, int *defcount*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*closure*)**494495Выполняет предварительно скомпилированный объект кода в заданном окружении. Это окружение состоит из словарей глобальных и локальных переменных, массивов аргументов, ключевых слов и значений по умолчанию, а также кортежа замыкания с ячейками.496497**\[PyEval\_EvalFrame\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyEval_EvalFrame`(PyFrameObject *\*f*)**498499Выполняет фрейм исполнения. Это упрощённый интерфейс к PyEval\_EvalFrameEx для обратной совместимости.500501**\[PyEval\_EvalFrameEx\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyEval_EvalFrameEx`(PyFrameObject *\*f*, int *throwflag*)**502503Это основная, неприукрашенная функция интерпретации Python. Она буквально состоит из 2000 строк. Кодовый объект, связанный с фреймом выполнения504505*f*506507, выполняется: байт-код интерпретируется, а вызовы выполняются по мере необходимости. Дополнительным параметром508509*throwflag*510511в основном можно пренебречь – если он истинен, то немедленно вызывается исключение; это используется для методов512513`throw()`514515объектов-генераторов.516517**\[PyEval\_MergeCompilerFlags\]int `PyEval_MergeCompilerFlags`([PyCompilerFlags](https://python-all.ru/3.0/c-api/veryhigh.html#PyCompilerFlags) *\*cf*)**518519Эта функция изменяет флаги текущего фрейма вычислений и возвращает true в случае успеха, false в случае ошибки.520521**\[Py\_eval\_input\]int `Py_eval_input`**522523Начальный символ грамматики Python для изолированных выражений; используется с [`Py_CompileString`](https://python-all.ru/3.0/c-api/veryhigh.html#Py_CompileString).524525**\[Py\_file\_input\]int `Py_file_input`**526527Начальный символ грамматики Python для последовательностей инструкций, читаемых из файла или другого источника; используется с [`Py_CompileString`](https://python-all.ru/3.0/c-api/veryhigh.html#Py_CompileString). Это символ, который следует использовать при компиляции произвольно длинного исходного кода Python.528529**\[Py\_single\_input\]int `Py_single_input`**530531Начальный символ из грамматики Python для одного оператора; используется с [`Py_CompileString`](https://python-all.ru/3.0/c-api/veryhigh.html#Py_CompileString). Этот символ используется в цикле интерактивного интерпретатора.532533**\[PyCompilerFlags\]struct `PyCompilerFlags`**534535Это структура, используемая для хранения флагов компилятора. Когда код только компилируется, она передаётся как `int flags`, а когда код выполняется – как `PyCompilerFlags *flags`. В последнем случае `from __future__ import` может изменять *flags*.536537Когда `PyCompilerFlags *flags` равен *NULL*, `cf_flags` считается равным `0`, и любые изменения, внесённые `from __future__ import`, отбрасываются.538539```c540struct PyCompilerFlags {541    int cf_flags;542}543```544545**\[CO\_FUTURE\_DIVISION\]int `CO_FUTURE_DIVISION`**546547Этот бит можно установить в548549*flags*550551, чтобы оператор деления552553`/`554555интерпретировался как «истинное деление» в соответствии с556557[**PEP 238**](https://python-all.ru/3.0/c-api/veryhigh.html)558559.560