Слой очень высокого уровня¶The Very High Level Layer

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

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)¶: Возвращаемое значение: новая ссылка.
Это упрощённый интерфейс к 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 истинно, файл закрывается до того, как 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 **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *kwdefs, PyObject *closure)¶: Выполняет предварительно скомпилированный объект кода в заданном окружении для его вычисления. Это окружение состоит из словаря глобальных переменных, объекта отображения локальных переменных, массивов аргументов, ключевых слов и значений по умолчанию, словаря значений по умолчанию для только ключевых аргументов и кортежа замыкания с ячейками.

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

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

PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)¶: Это основная, неприукрашенная функция интерпретации Python. Она буквально насчитывает 2000 строк. Код объекта f, связанный с фреймом выполнения, выполняется: интерпретируются байткод и по мере необходимости выполняются вызовы. Дополнительный параметр throwflag в основном можно игнорировать – если он истинный, то немедленно выбрасывается исключение; это используется для методов 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, отбрасываются.

struct PyCompilerFlags {
    int cf_flags;
}

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