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

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

Некоторые из этих функций принимают начальный символ грамматики в качестве параметра. Доступны следующие начальные символы: Py_eval_input, Py_file_input, Py_single_input и Py_func_type_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_InteractiveOneObject(FILE *fp, PyObject *filename, PyCompilerFlags *flags)¶

Читает и выполняет один оператор из файла, связанного с интерактивным устройством, в соответствии с аргументом flags. Пользователю будет выведено приглашение с помощью sys.ps1 и sys.ps2. filename должен быть объектом str Python.

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

int PyRun_InteractiveOne(FILE *fp, const char *filename)¶

Это упрощённый интерфейс к PyRun_InteractiveOneFlags() (см. ниже); flags оставлен равным NULL.

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

Аналогично PyRun_InteractiveOneObject(), но filename является const char*, которое декодируется из кодировки файловой системы и обработчика ошибок.

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

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.

Доступные флаги компилятора доступны в виде макросов:

PyCF_ALLOW_TOP_LEVEL_AWAIT¶

PyCF_ONLY_AST¶

PyCF_OPTIMIZED_AST¶

PyCF_TYPE_COMMENTS¶

См. флаги компилятора в документации модуля Python ast, который экспортирует эти константы под теми же именами.

Флаги «PyCF» выше можно комбинировать с флагами «CO_FUTURE», такими как CO_FUTURE_ANNOTATIONS, чтобы включить возможности, обычно выбираемые с помощью future-операторов. Полный список см. в Флаги объекта кода.