Уровень очень высокого уровня

Функции в этой главе позволят вам выполнить исходный код Python, заданный в файле или буфере, но они не позволят вам взаимодействовать с интерпретатором более подробно.

Несколько этих функций принимают начальный символ из грамматики в качестве параметра. Доступные начальные символы — Py_eval_input, Py_file_input, и Py_single_input. Они описываются после функций, которые принимают их в качестве параметров.

Обратите также внимание, что несколько этих функций принимают параметры FILE*. Одна особая проблема, которую необходимо тщательно обработать, заключается в том, что структура FILE для разных библиотек C может быть различной и несовместимой. В Windows (по крайней мере) динамически подключаемые расширения могут фактически использовать разные библиотеки, поэтому следует позаботиться о том, чтобы параметры FILE* передавались в эти функции только в том случае, если точно известно, что они были созданы той же библиотекой, что и среда выполнения Python.

int Py_Main(int argc, wchar_t **argv)

Основная программа для стандартной интерпретатора. Она предоставляется для программ, которые встраивают Python. Параметры argc и argv должны быть подготовлены точно так же, как те, которые передаются в функцию main() программы на C (преобразованные в wchar_t в соответствии с локалью пользователя). Важно отметить, что список аргументов может быть изменён (но содержимое строк, на которые указывают аргументы списка, не изменяется). Возвращаемое значение будет 0, если интерпретатор завершается нормально (т. е. без исключения), 1, если интерпретатор завершается из-за исключения, или 2, если список параметров не представляет собой допустимую командную строку Python.

Обратите внимание, что если возникает исключение SystemExit, которое иначе не обрабатывается, эта функция не вернёт 1, а завершит процесс, если Py_InspectFlag не установлено.

int Py_BytesMain(int argc, char **argv): Аналогично Py_Main(), но argv является массивом байтовых строк.

Новое в версии 3.8.

int PyRun_AnyFile(FILE *fp, const char *filename): Это упрощённый интерфейс к PyRun_AnyFileExFlags() ниже, оставляя closeit установленным в значение 0 и flags установленным в значение NULL.

int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags): Это упрощённый интерфейс к PyRun_AnyFileExFlags() ниже, оставляя аргумент closeit установленным в значение 0.

int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit): Это упрощённый интерфейс к PyRun_AnyFileExFlags() ниже, оставляя аргумент flags установленным в значение NULL.

int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags): Если fp ссылается на файл, связанный с интерактивным устройством (консоль или терминал ввода или псевдотерминал Unix), возвращает значение PyRun_InteractiveLoop(), иначе возвращает результат PyRun_SimpleFile(). filename декодируется из кодировки файловой системы (sys.getfilesystemencoding()). Если filename равно NULL, эта функция использует "???" в качестве имени файла. Если closeit истинно, файл закрывается до возвращения PyRun_SimpleFileExFlags().

int PyRun_SimpleString(const char *command): Это упрощённый интерфейс к PyRun_SimpleStringFlags() ниже, оставляя аргумент PyCompilerFlags* установленным в значение NULL.

int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)

Выполняет исходный код Python из command в модуле __main__ в соответствии с аргументом flags. Если __main__ ещё не существует, он создаётся. Возвращает 0 при успехе или -1 при возникновении исключения. Если произошла ошибка, получить информацию об исключении невозможно. Для значения flags см. ниже.

Обратите внимание, что если возникает исключение SystemExit, которое иначе не обрабатывается, эта функция не вернёт -1, а завершит процесс, если Py_InspectFlag не установлено.

int PyRun_SimpleFile(FILE *fp, const char *filename): Это упрощённый интерфейс к PyRun_SimpleFileExFlags() ниже, оставляя closeit установленным в значение 0 и flags установленным в значение NULL.

int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit): Это упрощённый интерфейс к PyRun_SimpleFileExFlags() ниже, оставляя flags установленным в значение NULL.

int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags): Аналогично PyRun_SimpleStringFlags(), но исходный код Python читается из fp вместо строковой переменной в памяти. filename должно быть именем файла, оно декодируется из кодировки файловой системы (sys.getfilesystemencoding()). Если closeit истинно, файл закрывается до возвращения PyRun_SimpleFileExFlags.

Примечание

В Windows fp следует открывать в двоичном режиме (например, fopen(filename, "rb")). В противном случае Python может некорректно обработать файл сценария с окончанием строки LF.

int PyRun_InteractiveOne(FILE *fp, const char *filename): Это упрощённый интерфейс к PyRun_InteractiveOneFlags() ниже, оставляя flags установленным в значение NULL.

int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

Чтение и выполнение одной инструкции из файла, связанного с интерактивным устройством, в соответствии с аргументом flags. Пользователь будет приглашён с помощью sys.ps1 и sys.ps2 . filename декодируется из кодировки файловой системы (sys.getfilesystemencoding()).

Возвращает 0 при успешном выполнении ввода, -1 при возникновении исключения или код ошибки из файла заголовков errcode.h, распространяемого в составе Python, если произошла ошибка разбора. (Обратите внимание, что errcode.h не включён в Python.h, поэтому его необходимо включить явно, если это необходимо.)

int PyRun_InteractiveLoop(FILE *fp, const char *filename): Это упрощённый интерфейс к PyRun_InteractiveLoopFlags() ниже, оставляя flags установленным в значение NULL.

int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags): Чтение и выполнение инструкций из файла, связанного с интерактивным устройством, до тех пор, пока не будет достигнут конец файла. Пользователь будет приглашён с помощью sys.ps1 и sys.ps2 . filename декодируется из кодировки файловой системы (sys.getfilesystemencoding()). Возвращает 0 в конце файла или отрицательное число при ошибке.

int (*PyOS_InputHook)(void): Можно установить для указания функции с прототипом int func(void). Функция будет вызвана, когда приглашение интерпретатора Python станет бездействующим и будет ожидать ввода пользователя с терминала. Возвращаемое значение игнорируется. Переопределение этого обработчика может использоваться для интеграции приглашения интерпретатора с другими циклами событий, как это сделано в Modules/_tkinter.c в исходном коде Python.

END_OF_DOCUMENT_MARKER

char* (*PyOS_ReadlineFunctionPointer)(FILE *, FILE *, const char *)

Может быть задано для указания функции с прототипом char *func(FILE *stdin, FILE *stdout, char *prompt), которая переопределяет функцию по умолчанию, используемую для чтения одной строки ввода в командной строке интерпретатора. Функция должна вывести строку prompt, если это не NULL, а затем прочитать строку ввода из указанного файла стандартного ввода, вернув полученную строку. Например, модуль readline устанавливает этот обработчик для предоставления функций редактирования строк и автодополнения.

Результат должен быть строкой, выделенной с помощью PyMem_RawMalloc() или PyMem_RawRealloc(), или NULL в случае ошибки.

Изменено в версии 3.4: Результат должен быть выделен с помощью PyMem_RawMalloc() или PyMem_RawRealloc(), а не PyMem_Malloc() или PyMem_Realloc().

struct _node* PyParser_SimpleParseString(const char *str, int start): Это упрощённый интерфейс к PyParser_SimpleParseStringFlagsFilename() ниже, оставляющий filename равным NULL и flags равным 0.

Устарело начиная с версии 3.9, будет удалено в версии 3.10.

struct _node* PyParser_SimpleParseStringFlags(const char *str, int start, int flags): Это упрощённый интерфейс к PyParser_SimpleParseStringFlagsFilename() ниже, оставляющий filename равным NULL.

Устарело начиная с версии 3.9, будет удалено в версии 3.10.

struct _node* PyParser_SimpleParseStringFlagsFilename(const char *str, const char *filename, int start, int flags): Разбор исходного кода Python из str используя начальный токен start в соответствии с аргументом flags. Результат может быть использован для создания объекта кода, который можно эффективно оценить. Это полезно, если фрагмент кода должен быть оценен многократно. filename декодируется из кодировки файловой системы (sys.getfilesystemencoding()).

Устарело начиная с версии 3.9, будет удалено в версии 3.10.

struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start): Это упрощённый интерфейс к PyParser_SimpleParseFileFlags() ниже, оставляющий flags равным 0.

Устарело начиная с версии 3.9, будет удалено в версии 3.10.

struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags): Аналогично PyParser_SimpleParseStringFlagsFilename(), но исходный код Python читается из fp вместо строки в памяти.

Устарело начиная с версии 3.9, будет удалено в версии 3.10.

PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals): Значение возврата: Новая ссылка.
Это упрощённый интерфейс к PyRun_StringFlags() ниже, оставляющий flags равным NULL.

PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)

Значение возврата: Новая ссылка.

Выполнить исходный код Python из str в контексте, указанном объектами globals и locals, с флагами компилятора, указанными в flags. globals должен быть словарем; locals может быть любым объектом, реализующим протокол отображения.

Параметр start указывает начальный токен, который должен быть использован для разбора исходного кода.

Возвращает результат выполнения кода как объект Python, или NULL если была поднята исключительная ситуация.

PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals): Значение возврата: Новая ссылка.
Это упрощённый интерфейс к PyRun_FileExFlags() ниже, оставляющий closeit равным 0 и flags равным NULL.

PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit): Значение возврата: Новая ссылка.
Это упрощённый интерфейс к PyRun_FileExFlags() ниже, оставляющий flags равным NULL.

PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags): Значение возврата: Новая ссылка.
Это упрощённый интерфейс к PyRun_FileExFlags() ниже, оставляющий closeit равным 0.

PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags): Значение возврата: Новая ссылка.
Аналогично PyRun_StringFlags(), но исходный код Python читается из fp вместо строки в памяти. filename должно быть именем файла, оно декодируется из кодировки файловой системы (sys.getfilesystemencoding()). Если closeit истинно, файл закрывается перед возвратом PyRun_FileExFlags().

PyObject* Py_CompileString(const char *str, const char *filename, int start): Значение возврата: Новая ссылка.
Это упрощённый интерфейс к Py_CompileStringFlags() ниже, оставляющий flags равным NULL.

PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags): Значение возврата: Новая ссылка.
Это упрощённый интерфейс к Py_CompileStringExFlags() ниже, с optimize, установленным в -1.

PyObject* Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)

Значение возврата: Новая ссылка.

Разбор и компиляция исходного кода Python в str, возвращающий результирующий объект кода. Начальный токен задаётся start; это может быть использовано для ограничения кода, который может быть скомпилирован и должен быть Py_eval_input, Py_file_input, или Py_single_input.

Указанное в filename имя файла используется для построения объекта кода и может отображаться в трассировках или сообщениях об ошибках SyntaxError. Возвращает NULL если код не может быть разобран или скомпилирован.

Целое число optimize указывает уровень оптимизации компилятора; значение -1 выбирает уровень оптимизации интерпретатора, заданный параметрами -O. Явные уровни — 0 (без оптимизации; __debug__ равно истине), 1 (утверждения удаляются, __debug__ ложно) или 2 (удаляются и строковые документации).

Добавлен в версии 3.4.

PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize): Значение возврата: Новая ссылка.
Как Py_CompileStringObject(), но filename — строка байтов, декодированная из кодировки файловой системы (os.fsdecode()).

Добавлен в версии 3.2.

PyObject* PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals): Значение возврата: Новая ссылка.
Это упрощённый интерфейс к PyEval_EvalCodeEx(), с только объектом кода и глобальными и локальными переменными. Другие аргументы установлены в NULL.

PyObject* PyEval_EvalCodeEx(PyObject *co, PyObject *globals, PyObject *locals, PyObject *const *args, int argcount, PyObject *const *kws, int kwcount, PyObject *const *defs, int defcount, PyObject *kwdefs, PyObject *closure): Значение возврата: Новая ссылка.
Оценить предварительно скомпилированный объект кода, с заданной средой для его оценки. Эта среда состоит из словаря глобальных переменных, объекта отображения локальных переменных, массивов аргументов, ключевых слов и значений по умолчанию, словаря значений по умолчанию для ключевых аргументов и кортежа замыканий ячеек.

PyFrameObject: Структура C объектов, используемых для описания объектов фреймов. Поля этого типа могут изменяться в любое время.

END_OF_DOCUMENT_MARKER

PyObject* PyEval_EvalFrame(PyFrameObject *f): Значение возврата: Новая ссылка.
Вычисление кадра выполнения. Это упрощённый интерфейс к PyEval_EvalFrameEx(), для обратной совместимости.

PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag): Значение возврата: Новая ссылка.
Это основная, необработанная функция интерпретации Python. Код объекта, связанный с кадром выполнения f, выполняется, интерпретируя байткод и выполняя вызовы по мере необходимости. Дополнительный параметр throwflag можно в основном игнорировать — если он истинный, то он вызывает немедленное возникновение исключения; это используется для методов throw() объектов генераторов.

Изменено в версии 3.4: Эта функция теперь включает в себя проверку отладки, чтобы гарантировать, что она не отбрасывает активное исключение без уведомления.

int PyEval_MergeCompilerFlags(PyCompilerFlags *cf): Эта функция изменяет флаги текущего кадра оценки и возвращает true при успехе, false при ошибке.

int Py_eval_input: Начальный символ из грамматики Python для изолированных выражений; для использования с Py_CompileString().

int Py_file_input: Начальный символ из грамматики Python для последовательностей инструкций, считываемых из файла или другого источника; для использования с Py_CompileString(). Этот символ следует использовать при компиляции произвольно длинного исходного кода Python.

int Py_single_input: Начальный символ из грамматики Python для одной инструкции; для использования с Py_CompileString(). Этот символ используется для цикла интерпретатора интерактивного режима.

struct PyCompilerFlags

Это структура, используемая для хранения флагов компилятора. В тех случаях, когда код только компилируется, он передаётся как int flags, а в тех случаях, когда код выполняется, он передаётся как PyCompilerFlags *flags. В этом случае, from __future__ import может изменить flags.

Всякий раз, когда PyCompilerFlags *flags имеет значение NULL, cf_flags обрабатывается как равное 0, и любые изменения, вызванные from __future__ import, отбрасываются.

int cf_flags: Флаги компилятора.

int cf_feature_version

cf_feature_version — это второстепенная версия Python. Она должна быть инициализирована значением PY_MINOR_VERSION.

Поле игнорируется по умолчанию, используется только в том случае, если флаг PyCF_ONLY_AST установлен в cf_flags.

Изменено в версии 3.8: Добавлено поле cf_feature_version.

int CO_FUTURE_DIVISION: Этот бит может быть установлен в flags для того, чтобы оператор деления / интерпретировался как «истинное деление» в соответствии с PEP 238.