Слой очень высокого уровня¶The Very High Level Layer

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

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

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

int Py_Main(int argc, wchar_t **argv)¶

Часть Stable ABI.

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

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

int Py_BytesMain(int argc, char **argv)¶: Часть Stable ABI с версии 3.8.
Аналогична 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, а завершит процесс, при условии, что 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)¶: Часть Stable ABI.
Можно установить так, чтобы указывать на функцию с прототипом int func(void). Эта функция будет вызываться, когда приглашение интерпретатора Python готовится перейти в состояние ожидания и ждёт ввода пользователя с терминала. Возвращаемое значение игнорируется. Переопределение этого хука можно использовать для интеграции приглашения интерпретатора с другими циклами событий, как это сделано в Modules/_tkinter.c в исходном коде Python.

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

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)¶: Возвращаемое значение: новая ссылка. Часть Stable 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)¶: Возвращаемое значение: новая ссылка. Часть Stable 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)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Выполняет предварительно скомпилированный объект кода в заданном окружении для его вычисления. Это окружение состоит из словаря глобальных переменных, объекта отображения локальных переменных, массивов аргументов, ключевых слов и значений по умолчанию, словаря значений по умолчанию для только ключевых аргументов и кортежа замыкания с ячейками.

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

PyObject *PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Это основная, неприукрашенная функция интерпретации Python. Выполняется объект кода, связанный с фреймом исполнения f, с интерпретацией байткода и вызовом функций по мере необходимости. Дополнительный параметр throwflag в основном можно игнорировать – если он равен true, то немедленно возбуждается исключение; это используется для методов 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.