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

Функции в этой главе позволят вам выполнить код 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, эта функция использует "???" в качестве имени файла.

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 имеет значение true, файл закрывается перед возвратом 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.

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

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

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

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

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 равно true, файл закрывается перед тем, как 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-структура объектов, используемых для описания объектов фреймов. Поля этого типа могут быть изменены в любое время.

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

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