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

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

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

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

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, а завершит процесс, если PyConfig.inspect равно нулю.

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 должно быть именем файла, оно декодируется из кодировки файловой системы и обработчика ошибок. Если 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 декодируется из кодировки файловой системы и обработчика ошибок.

Возвращает 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): Чтение и выполнение операторов из файла, связанного с интерактивным устройством, до достижения EOF. Пользователю будет предложено использовать sys.ps1 и sys.ps2 . filename декодируется из кодировки файловой системы и обработчика ошибок. Возвращает 0 при EOF или отрицательное число при ошибке.

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

Изменено в версии 3.12: Эта функция вызывается только из главного интерпретатора.

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().

Изменено в версии 3.12: Эта функция вызывается только из главного интерпретатора.

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 должно быть именем файла, оно декодируется с использованием кодировки файловой системы и обработчика ошибок. Если closeit равно истине, файл закрывается перед возвратом PyRun_FileExFlags().

PyObject *Py_CompileString(const char *str, const char *filename, int start): Значение возврата: Новая ссылка. Часть Стабильной ABI.
Это упрощённый интерфейс к 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 — строка байтов, декодированная с помощью кодировки файловой системы и обработчика ошибок.

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

PyObject *PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals): Значение возврата: Новая ссылка. Часть Стабильной ABI.
Это упрощённый интерфейс к 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): Значение возврата: Новая ссылка. Часть Стабильной ABI.
Выполнение предварительно скомпилированного объекта кода в заданной среде выполнения. Эта среда состоит из словаря глобальных переменных, объекта отображения локальных переменных, массивов аргументов, ключевых слов и значений по умолчанию, словаря значений по умолчанию для ключевых аргументов и кортежа замыканий ячеек.

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

PyObject *PyEval_EvalFrameEx(PyFrameObject *f, int throwflag): Значение возврата: Новая ссылка. Часть Стабильной ABI.
Основная функция интерпретации 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.