Очень высокоуровневый слой

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

Считывание и выполнение инструкции из файла, связанного с интерактивным устройством, до достижения EOF. Пользователю будет предложено использовать sys.ps1 и sys.ps2. filename декодируется из кодировки файловой системы (sys.getfilesystemencoding()). Возвращает 0 при EOF или отрицательное число при отказе.

int (*PyOS_InputHook)(void)

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

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)

Return value: New reference.

Упрощенный интерфейс, который PyRun_StringFlags() ниже, оставляя flags значение NULL.

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

Return value: New reference.

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

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

PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)

Return value: New reference.

Упрощенный интерфейс, который PyRun_FileExFlags() ниже, оставляя для closeit значение 0, а для flags значение NULL.

PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)

Return value: New reference.

Упрощенный интерфейс, который PyRun_FileExFlags() ниже, оставляя flags значение NULL.

PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)

Return value: New reference.

Упрощенный интерфейс, который PyRun_FileExFlags() ниже, оставляя closeit значение 0.

PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)

Return value: New reference.

Аналогично PyRun_StringFlags(), но исходный Python код считывается из fp вместо строки в памяти. filename должно быть именем файла, он декодируется из кодировки файловой системы (sys.getfilesystemencoding()). Если closeit имеет значение true, файл закрывается перед возвращением PyRun_FileExFlags().

PyObject* Py_CompileString(const char *str, const char *filename, int start)

Return value: New reference.

Упрощенный интерфейс, который Py_CompileStringFlags() ниже, оставляя flags значение NULL.

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

Return value: New reference.

Упрощенный интерфейс, Py_CompileStringExFlags() ниже, с optimize -1.

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

Return value: New reference.

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

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

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

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

Return value: New reference.

Подобно Py_CompileStringObject(), но filename является байтовой строкой, декодированной из кодировки файловой системы (os.fsdecode()).

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

PyObject* PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)

Return value: New reference.

Упрощенный интерфейс для 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)

Return value: New reference.

Вычислить предварительно скомпилированный объект кода с учетом конкретной среды для его оценки. Эта среда состоит из словаря глобальных переменных, объекта отображения локальных переменных, массивов аргументов, ключевых слов и значений по умолчанию, словаря значения по умолчанию для только ключевых аргументов и кортежа замыкания ячеек.

PyFrameObject

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

PyObject* PyEval_EvalFrame(PyFrameObject *f)

Return value: New reference.

Вычислить фрейм выполнения. Упрощенный интерфейс для PyEval_EvalFrameEx(), для обратной совместимости.

PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)

Return value: New reference.

Это основная, неизменная функция интерпретации 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.