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

Функции, приведённые в этой главе, позволят вам выполнить исходный код 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 истинно, файл закрывается до возврата 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), переопределяя функцию по умолчанию, используемую для чтения одной строки ввода в приглашении интерпретатора. Ожидается, что функция выведет строку приглашения, если она не 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 истинно, файл закрывается до возврата 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__ — истина), 1 (утверждения удаляются, __debug__ — ложно) или 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 в большинстве случаев можно игнорировать — если он истинен, то он вызывает немедленную генерацию исключения; используется для методов throw() объектов-генераторов.

Изменено в версии 3.4: Функция теперь включает утверждение отладки, чтобы гарантировать, что она не отбрасывает активное исключение без уведомления.

int PyEval_MergeCompilerFlags(PyCompilerFlags *cf): Функция изменяет флаги текущего фрейма вычисления и возвращает истину в случае успеха и ложь в случае неудачи.

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.

По умолчанию поле игнорируется, оно используется тогда и только тогда, когда в cf_flags установлен флаг PyCF_ONLY_AST.

Изменено в версии 3.8: Добавлено поле cf_feature_version.

int CO_FUTURE_DIVISION: Данный бит может быть установлен в flags, чтобы оператор деления / интерпретировался как «истинное деление» согласно PEP 238.