Слой очень высокого уровня

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

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

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

int Py_Main(int argc, wchar_t **argv)

Часть Стабильный ABI.

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

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

int Py_BytesMain(int argc, char **argv)

Часть Стабильный ABI с версии 3.8.

Аналогично Py_Main(), но argv - это массив байтовых строк.

Added in version 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 равно true, файл будет закрыт до возврата PyRun_SimpleFileExFlags().

int PyRun_SimpleString(const char *command)

Это упрощенный интерфейс для PyRun_SimpleStringFlags() ниже, оставляя аргумент PyCompilerFlags* установленным на NULL.

int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)

Выполняет исходный код Python из команды в модуле __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() ниже, оставляя флаги установленными в NULL.

int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

Аналогично PyRun_SimpleStringFlags(), но исходный код Python считывается из fp, а не из строки в памяти. filename должно быть именем файла, оно декодируется из filesystem encoding and error handler. Если closeit равно true, файл будет закрыт до возврата PyRun_SimpleFileExFlags().

Примечание

В Windows файл fp должен быть открыт в двоичном режиме (например, fopen(filename, "rb")). В противном случае Python может некорректно обрабатывать файл сценария с LF-концом строки.

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

Это упрощенный интерфейс для PyRun_InteractiveOneFlags() ниже, оставляя флаги установленными в NULL.

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

Считывание и выполнение одного оператора из файла, связанного с интерактивным устройством, в соответствии с аргументом flags. Пользователь получает запрос, используя sys.ps1 и sys.ps2. Имя filename декодируется из filesystem encoding and error handler.

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

int PyRun_InteractiveLoop(FILE *fp, const char *filename)

Это упрощенный интерфейс для PyRun_InteractiveLoopFlags() ниже, оставляя флаги установленными в NULL.

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

Чтение и выполнение операторов из файла, связанного с интерактивным устройством, до достижения EOF. Пользователь получает запрос, используя клавиши sys.ps1 и sys.ps2. Имя filename декодируется из filesystem encoding and error handler. Возвращает 0 при достижении EOF или отрицательное число при неудаче.

int (*PyOS_InputHook)(void)

Часть Стабильный ABI.

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

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

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: Эта функция вызывается только из main interpreter.

PyObject *PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)

Возвращаемое значение: Новая ссылка.

Это упрощенный интерфейс для PyRun_StringFlags() ниже, оставляя флаги установленными в 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() ниже, оставляя флаги установленными в 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 должно быть именем файла, оно декодируется из filesystem encoding and error handler. Если closeit равно true, файл будет закрыт до возврата PyRun_FileExFlags().

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

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

Это упрощенный интерфейс для Py_CompileStringFlags() ниже, оставляя флаги установленными в NULL.

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

Возвращаемое значение: Новая ссылка.

Это упрощенный интерфейс Py_CompileStringExFlags(), приведенный ниже, с оптимизацией, установленной на -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__ - true), 1 (ассерты удаляются, __debug__ - false) или 2 (удаляются и docstrings).

Added in version 3.4.

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

Возвращаемое значение: Новая ссылка.

Аналогично Py_CompileStringObject(), но filename - это байтовая строка, декодированная из filesystem encoding and error handler.

Added in version 3.2.

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

Возвращаемое значение: Новая ссылка. Часть Стабильный 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)

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

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

PyObject *PyEval_EvalFrame(PyFrameObject *f)

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

Оценить кадр выполнения. Это упрощенный интерфейс для PyEval_EvalFrameEx(), для обратной совместимости.

PyObject *PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)

Возвращаемое значение: Новая ссылка. Часть Стабильный 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 может изменять флаги.

Если 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.