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

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

Несколько таких функций принимают в качестве параметра начальный символ грамматики. Доступны следующие начальные символы: Py_eval_input, Py_file_input и Py_single_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 имеет значение true, файл закрывается перед возвратом из 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 имеет значение 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 декодируется с использованием кодировки файловой системы и обработчика ошибок.

Возвращает 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 декодируется с использованием кодировки файловой системы и обработчика ошибок. Возвращает 0 в конце файла или отрицательное число в случае сбоя.

int (*PyOS_InputHook)(void): Часть стабильного 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 задаёт начальный символ и должен иметь одно из следующих значений: Py_eval_input, Py_file_input или Py_single_input.

Возвращает результат выполнения кода в виде объекта 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 имеет значение true, файл закрывается перед возвратом из PyRun_FileExFlags().

PyObject *Py_CompileString(const char *str, const char *filename, int start): Возвращаемое значение: новая ссылка.Часть стабильного 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; его можно использовать, чтобы ограничить компилируемый код. Он должен иметь одно из значений: Py_eval_input, Py_file_input или Py_single_input. Имя файла, указанное в filename, используется для создания объекта кода и может появляться в трассировках стека или сообщениях исключений SyntaxError. Возвращает NULL, если код невозможно разобрать или скомпилировать.

Целое число optimize задаёт уровень оптимизации компилятора; значение -1 выбирает уровень оптимизации интерпретатора, определяемый параметрами -O. Явные уровни: 0 (без оптимизации; __debug__ имеет значение true), 1 (операторы assert удаляются, __debug__ имеет значение false) или 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): Возвращаемое значение: новая ссылка.Часть стабильного 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.
Выполняет предварительно скомпилированный объект кода в заданном контексте. Этот контекст состоит из словаря глобальных переменных, объекта-отображения локальных переменных, массивов аргументов, ключевых слов и значений по умолчанию, словаря значений по умолчанию для аргументов только по ключевому слову и кортежа замыкания, содержащего ячейки.

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 может изменять 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. Полный список см. в разделе Флаги объектов кода.