`veryhigh.md`

512 строк · 24.4 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/2.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`](https://python-all.ru/2.6/c-api/veryhigh.html#Py_eval_input), [`Py_file_input`](https://python-all.ru/2.6/c-api/veryhigh.html#Py_file_input) и [`Py_single_input`](https://python-all.ru/2.6/c-api/veryhigh.html#Py_single_input). Они описаны после функций, которые принимают их в качестве параметров.1213Также стоит отметить, что некоторые из этих функций принимают параметры типа `FILE*`. Одна из проблем, которую нужно аккуратно учитывать: структура `FILE` из разных библиотек C может различаться и быть несовместимой. В Windows (по крайней мере) динамически связываемые расширения могут на самом деле использовать разные библиотеки, поэтому следует соблюдать осторожность: параметры `FILE*` следует передавать этим функциям только в том случае, если точно известно, что они созданы той же библиотекой, которую использует среда выполнения Python.1415**int `Py_Main`(int *argc*, char *\*\*argv*)**1617Главная программа для стандартного интерпретатора. Она предоставляется для программ, которые встраивают Python. Параметры *argc* и *argv* должны быть подготовлены точно так же, как те, что передаются функции `main()` программы на C. Важно отметить, что список аргументов может быть изменён (но содержимое строк, на которые указывает список аргументов, не изменяется). Возвращаемое значение будет целым числом, переданным функции [`sys.exit()`](https://python-all.ru/2.6/library/sys.html#sys.exit), `1` если интерпретатор завершается из-за исключения, или `2` если список параметров не представляет собой допустимую командную строку Python.1819Обратите внимание, что если возникнет иначе необработанное [`SystemError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.SystemError), эта функция не вернёт `1`, а завершит процесс, если `Py_InspectFlag` не установлен.2021**int `PyRun_AnyFile`(FILE *\*fp*, const char *\*filename*)**2223Это упрощённый интерфейс к2425[`PyRun_AnyFileExFlags()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyRun_AnyFileExFlags)2627(см. ниже), в котором параметр2829*closeit*3031установлен в3233`0`3435, а3637*flags*3839– в4041*NULL*4243.4445**int `PyRun_AnyFileFlags`(FILE *\*fp*, const char *\*filename*, [PyCompilerFlags](https://python-all.ru/2.6/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**4647Это упрощённый интерфейс к4849[`PyRun_AnyFileExFlags()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyRun_AnyFileExFlags)5051(см. ниже), в котором аргумент5253*closeit*5455установлен в5657`0`5859.6061**int `PyRun_AnyFileEx`(FILE *\*fp*, const char *\*filename*, int *closeit*)**6263Это упрощённый интерфейс к6465[`PyRun_AnyFileExFlags()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyRun_AnyFileExFlags)6667(см. ниже), в котором аргумент6869*flags*7071установлен в7273*NULL*7475.7677**int `PyRun_AnyFileExFlags`(FILE *\*fp*, const char *\*filename*, int *closeit*, [PyCompilerFlags](https://python-all.ru/2.6/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**7879Если8081*fp*8283ссылается на файл, связанный с интерактивным устройством (консоль или терминальный ввод, или псевдотерминал Unix), возвращает значение8485[`PyRun_InteractiveLoop()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyRun_InteractiveLoop)8687, в противном случае возвращает результат8889[`PyRun_SimpleFile()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyRun_SimpleFile)9091. Если9293*filename*9495равен9697*NULL*9899, эта функция использует100101`"???"`102103в качестве имени файла.104105**int `PyRun_SimpleString`(const char *\*command*)**106107Это упрощённый интерфейс к108109[`PyRun_SimpleStringFlags()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyRun_SimpleStringFlags)110111(см. ниже), в котором аргумент112113*PyCompilerFlags\**114115установлен в NULL.116117**int `PyRun_SimpleStringFlags`(const char *\*command*, [PyCompilerFlags](https://python-all.ru/2.6/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**118119Выполняет исходный код Python из *command* в модуле [`__main__`](https://python-all.ru/2.6/library/__main__.html#module-__main__) в соответствии с аргументом *flags*. Если модуль [`__main__`](https://python-all.ru/2.6/library/__main__.html#module-__main__) ещё не существует, он создаётся. Возвращает `0` при успехе или `-1`, если было возбуждено исключение. В случае ошибки получить информацию об исключении невозможно. О значении *flags* см. ниже.120121Обратите внимание, что если возникнет иначе необработанное [`SystemError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.SystemError), эта функция не вернёт `-1`, а завершит процесс, если `Py_InspectFlag` не установлен.122123**int `PyRun_SimpleFile`(FILE *\*fp*, const char *\*filename*)**124125Это упрощённый интерфейс к126127[`PyRun_SimpleFileExFlags()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyRun_SimpleFileExFlags)128129(см. ниже), в котором130131*closeit*132133установлен в134135`0`136137, а138139*flags*140141– в142143*NULL*144145.146147**int `PyRun_SimpleFileFlags`(FILE *\*fp*, const char *\*filename*, [PyCompilerFlags](https://python-all.ru/2.6/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**148149Это упрощённый интерфейс к150151[`PyRun_SimpleFileExFlags()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyRun_SimpleFileExFlags)152153ниже, оставляя154155*closeit*156157равным158159`0`160161.162163**int `PyRun_SimpleFileEx`(FILE *\*fp*, const char *\*filename*, int *closeit*)**164165Это упрощённый интерфейс к166167[`PyRun_SimpleFileExFlags()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyRun_SimpleFileExFlags)168169(см. ниже), в котором170171*flags*172173установлен в174175*NULL*176177.178179**int `PyRun_SimpleFileExFlags`(FILE *\*fp*, const char *\*filename*, int *closeit*, [PyCompilerFlags](https://python-all.ru/2.6/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**180181Аналогично182183[`PyRun_SimpleStringFlags()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyRun_SimpleStringFlags)184185, но исходный код Python читается из186187*fp*188189, а не из строки в памяти.190191*filename*192193должно быть именем файла. Если194195*closeit*196197равно true, файл закрывается перед возвратом из PyRun\_SimpleFileExFlags.198199**int `PyRun_InteractiveOne`(FILE *\*fp*, const char *\*filename*)**200201Это упрощённый интерфейс к202203[`PyRun_InteractiveOneFlags()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyRun_InteractiveOneFlags)204205(см. ниже), в котором206207*flags*208209установлен в210211*NULL*212213.214215**int `PyRun_InteractiveOneFlags`(FILE *\*fp*, const char *\*filename*, [PyCompilerFlags](https://python-all.ru/2.6/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**216217Читает и выполняет один оператор из файла, связанного с интерактивным устройством, в соответствии с аргументом218219*flags*220221. Если222223*filename*224225равно226227*NULL*228229, вместо него используется230231`"???"`232233. Пользователю выводятся приглашения234235`sys.ps1`236237и238239`sys.ps2`240241. Возвращает242243`0`244245, если ввод был выполнен успешно,246247`-1`248249, если произошло исключение, или код ошибки из файла250251`errcode.h`252253(входящего в состав Python), если была ошибка разбора. (254255`errcode.h`256257не включается через258259`Python.h`260261, поэтому его нужно включать отдельно, если необходимо.)262263**int `PyRun_InteractiveLoop`(FILE *\*fp*, const char *\*filename*)**264265Это упрощённый интерфейс к266267[`PyRun_InteractiveLoopFlags()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyRun_InteractiveLoopFlags)268269(см. ниже), в котором270271*flags*272273установлен в274275*NULL*276277.278279**int `PyRun_InteractiveLoopFlags`(FILE *\*fp*, const char *\*filename*, [PyCompilerFlags](https://python-all.ru/2.6/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**280281Читает и выполняет операторы из файла, связанного с интерактивным устройством, до достижения EOF. Если282283*filename*284285равно286287*NULL*288289, используется290291`"???"`292293. Пользователю выводятся приглашения294295`sys.ps1`296297и298299`sys.ps2`300301. Возвращает302303`0`304305при EOF.306307**struct \_node\* `PyParser_SimpleParseString`(const char *\*str*, int *start*)**308309Это упрощённый интерфейс к310311[`PyParser_SimpleParseStringFlagsFilename()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyParser_SimpleParseStringFlagsFilename)312313ниже, оставляя314315*filename*316317установленным в318319*NULL*320321, а322323*flags*324325– в326327`0`328329.330331**struct \_node\* `PyParser_SimpleParseStringFlags`(const char *\*str*, int *start*, int *flags*)**332333Это упрощённый интерфейс к334335[`PyParser_SimpleParseStringFlagsFilename()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyParser_SimpleParseStringFlagsFilename)336337ниже, оставляя338339*filename*340341установленным в342343*NULL*344345.346347**struct \_node\* `PyParser_SimpleParseStringFlagsFilename`(const char *\*str*, const char *\*filename*, int *start*, int *flags*)**348349Анализирует исходный код Python из350351*str*352353, используя начальный токен354355*start*356357в соответствии с аргументом358359*flags*360361. Результат можно использовать для создания объекта кода, который может быть эффективно вычислен. Это полезно, если фрагмент кода должен вычисляться много раз.362363**struct \_node\* `PyParser_SimpleParseFile`(FILE *\*fp*, const char *\*filename*, int *start*)**364365Это упрощённый интерфейс к366367[`PyParser_SimpleParseFileFlags()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyParser_SimpleParseFileFlags)368369ниже, оставляя370371*flags*372373равным374375`0`376377**struct \_node\* `PyParser_SimpleParseFileFlags`(FILE *\*fp*, const char *\*filename*, int *start*, int *flags*)**378379Аналогично380381[`PyParser_SimpleParseStringFlagsFilename()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyParser_SimpleParseStringFlagsFilename)382383, но исходный код Python читается из384385*fp*386387вместо строки в памяти.388389**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyRun_String`(const char *\*str*, int *start*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*globals*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*locals*)**390391*Возвращаемое значение: новая ссылка.*392393Это упрощённый интерфейс к [`PyRun_StringFlags()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyRun_StringFlags) ниже, оставляя *flags* установленным в *NULL*.394395**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyRun_StringFlags`(const char *\*str*, int *start*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*globals*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*locals*, [PyCompilerFlags](https://python-all.ru/2.6/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**396397*Возвращаемое значение: новая ссылка.*398399Выполняет исходный код Python из *str* в контексте, заданном словарями *globals* и *locals*, с флагами компилятора, указанными в *flags*. Параметр *start* задаёт начальный токен, который следует использовать для разбора исходного кода.400401Возвращает результат выполнения кода в виде объекта Python или *NULL*, если возникло исключение.402403**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyRun_File`(FILE *\*fp*, const char *\*filename*, int *start*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*globals*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*locals*)**404405*Возвращаемое значение: новая ссылка.*406407Это упрощённый интерфейс к [`PyRun_FileExFlags()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyRun_FileExFlags) ниже, оставляя *closeit* установленным в `0`, а *flags* – в *NULL*.408409**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyRun_FileEx`(FILE *\*fp*, const char *\*filename*, int *start*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*globals*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*locals*, int *closeit*)**410411*Возвращаемое значение: новая ссылка.*412413Это упрощённый интерфейс к [`PyRun_FileExFlags()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyRun_FileExFlags) ниже, оставляя *flags* установленным в *NULL*.414415**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyRun_FileFlags`(FILE *\*fp*, const char *\*filename*, int *start*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*globals*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*locals*, [PyCompilerFlags](https://python-all.ru/2.6/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**416417*Возвращаемое значение: новая ссылка.*418419Это упрощённый интерфейс к [`PyRun_FileExFlags()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyRun_FileExFlags) ниже, оставляя *closeit* установленным в `0`.420421**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyRun_FileExFlags`(FILE *\*fp*, const char *\*filename*, int *start*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*globals*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*locals*, int *closeit*, [PyCompilerFlags](https://python-all.ru/2.6/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**422423*Возвращаемое значение: новая ссылка.*424425Аналогично [`PyRun_StringFlags()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyRun_StringFlags), но исходный код Python читается из *fp*, а не из строки в памяти. *filename* должно быть именем файла. Если *closeit* истинно, файл закрывается перед тем, как [`PyRun_FileExFlags()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyRun_FileExFlags) вернёт результат.426427**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `Py_CompileString`(const char *\*str*, const char *\*filename*, int *start*)**428429*Возвращаемое значение: новая ссылка.*430431Это упрощённый интерфейс к [`Py_CompileStringFlags()`](https://python-all.ru/2.6/c-api/veryhigh.html#Py_CompileStringFlags) ниже, оставляя *flags* установленным в *NULL*.432433**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `Py_CompileStringFlags`(const char *\*str*, const char *\*filename*, int *start*, [PyCompilerFlags](https://python-all.ru/2.6/c-api/veryhigh.html#PyCompilerFlags) *\*flags*)**434435*Возвращаемое значение: новая ссылка.*436437Разбирает и компилирует исходный код Python из *str*, возвращая результирующий объект кода. Стартовый токен задаётся *start*; его можно использовать для ограничения компилируемого кода – он должен быть [`Py_eval_input`](https://python-all.ru/2.6/c-api/veryhigh.html#Py_eval_input), [`Py_file_input`](https://python-all.ru/2.6/c-api/veryhigh.html#Py_file_input) или [`Py_single_input`](https://python-all.ru/2.6/c-api/veryhigh.html#Py_single_input). Имя файла, указанное в *filename*, используется для создания объекта кода и может появляться в трассировках или сообщениях исключений [`SyntaxError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.SyntaxError). Возвращает *NULL*, если код не удаётся разобрать или скомпилировать.438439**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyEval_EvalCode`(PyCodeObject *\*co*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*globals*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*locals*)**440441*Возвращаемое значение: новая ссылка.*442443Это упрощённый интерфейс к [`PyEval_EvalCodeEx()`](https://python-all.ru/2.6/c-api/veryhigh.html#PyEval_EvalCodeEx), принимающий только объект кода и словари глобальных и локальных переменных. Остальные аргументы устанавливаются в *NULL*.444445**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyEval_EvalCodeEx`(PyCodeObject *\*co*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*globals*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*locals*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*\*args*, int *argcount*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*\*kws*, int *kwcount*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*\*defs*, int *defcount*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*closure*)**446447Выполняет предварительно скомпилированный объект кода в заданном окружении. Это окружение состоит из словарей глобальных и локальных переменных, массивов аргументов, ключевых слов и значений по умолчанию, а также кортежа замыкания с ячейками.448449**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyEval_EvalFrame`(PyFrameObject *\*f*)**450451Выполняет фрейм исполнения. Это упрощённый интерфейс к PyEval\_EvalFrameEx для обратной совместимости.452453**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyEval_EvalFrameEx`(PyFrameObject *\*f*, int *throwflag*)**454455Это основная, неприукрашенная функция интерпретации Python. Она буквально состоит из 2000 строк. Кодовый объект, связанный с фреймом выполнения456457*f*458459, выполняется: байт-код интерпретируется, а вызовы выполняются по мере необходимости. Дополнительным параметром460461*throwflag*462463в основном можно пренебречь – если он истинен, то немедленно вызывается исключение; это используется для методов464465`throw()`466467объектов-генераторов.468469**int `PyEval_MergeCompilerFlags`([PyCompilerFlags](https://python-all.ru/2.6/c-api/veryhigh.html#PyCompilerFlags) *\*cf*)**470471Эта функция изменяет флаги текущего фрейма вычислений и возвращает true в случае успеха, false в случае ошибки.472473**int `Py_eval_input`**474475Начальный символ из грамматики Python для изолированных выражений; используется с [`Py_CompileString()`](https://python-all.ru/2.6/c-api/veryhigh.html#Py_CompileString).476477**int `Py_file_input`**478479Начальный символ из грамматики Python для последовательностей инструкций, читаемых из файла или другого источника; используется с [`Py_CompileString()`](https://python-all.ru/2.6/c-api/veryhigh.html#Py_CompileString). Это символ для компиляции произвольно длинного исходного кода Python.480481**int `Py_single_input`**482483Начальный символ из грамматики Python для одной инструкции; используется с [`Py_CompileString()`](https://python-all.ru/2.6/c-api/veryhigh.html#Py_CompileString). Это символ, используемый в цикле интерактивного интерпретатора.484485**struct `PyCompilerFlags`**486487Это структура, используемая для хранения флагов компилятора. Когда код только компилируется, она передаётся как `int flags`, а когда код выполняется – как `PyCompilerFlags *flags`. В последнем случае `from __future__ import` может изменять *flags*.488489Когда `PyCompilerFlags *flags` равен *NULL*, `cf_flags` считается равным `0`, и любые изменения, внесённые `from __future__ import`, отбрасываются.490491```c492struct PyCompilerFlags {493    int cf_flags;494}495```496497**int `CO_FUTURE_DIVISION`**498499Этот бит можно установить в500501*flags*502503, чтобы оператор деления504505`/`506507интерпретировался как «истинное деление» в соответствии с508509[**PEP 238**](https://python-all.ru/2.6/c-api/veryhigh.html)510511.512