Слой очень высокого уровня¶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, char **argv)¶

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

Обратите внимание, что если возникнет иначе необработанное SystemError, эта функция не вернёт 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 равен 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 см. ниже.

Обратите внимание, что если возникнет иначе необработанное SystemError, эта функция не вернёт -1, а завершит процесс, если Py_InspectFlag не установлен.

int PyRun_SimpleFile(FILE *fp, const char *filename)¶

Это упрощённый интерфейс к PyRun_SimpleFileExFlags() (см. ниже), в котором closeit установлен в 0, а flags – в NULL.

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

Это упрощённый интерфейс к PyRun_SimpleFileExFlags() ниже, оставляя closeit равным 0.

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.

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

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

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

Читает и выполняет один оператор из файла, связанного с интерактивным устройством, в соответствии с аргументом flags. Если filename равно NULL, вместо него используется "???". Пользователю выводятся приглашения sys.ps1 и sys.ps2. Возвращает 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. Если filename равно NULL, используется "???". Пользователю выводятся приглашения sys.ps1 и sys.ps2. Возвращает 0 при EOF.

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. Результат можно использовать для создания объекта кода, который может быть эффективно вычислен. Это полезно, если фрагмент кода должен вычисляться много раз.

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. Параметр 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 должно быть именем файла. Если 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)¶

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

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

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

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

Это упрощённый интерфейс к PyEval_EvalCodeEx(), принимающий только объект кода и словари глобальных и локальных переменных. Остальные аргументы устанавливаются в NULL.

PyObject* PyEval_EvalCodeEx(PyCodeObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *closure)¶

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

PyObject* PyEval_EvalFrame(PyFrameObject *f)¶

Выполняет фрейм исполнения. Это упрощённый интерфейс к PyEval_EvalFrameEx для обратной совместимости.

PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)¶

Это основная, неприукрашенная функция интерпретации Python. Она буквально состоит из 2000 строк. Кодовый объект, связанный с фреймом выполнения f, выполняется: байт-код интерпретируется, а вызовы выполняются по мере необходимости. Дополнительным параметром throwflag в основном можно пренебречь – если он истинен, то немедленно вызывается исключение; это используется для методов throw() объектов-генераторов.

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.