Слой очень высокого уровня¶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 в соответствии с локалью пользователя). Список аргументов может изменяться (но содержимое строк, на которые указывает список аргументов, не изменяется). Возвращаемое значение – целое число, переданное функции sys.exit(), 1 если интерпретатор завершился из-за исключения, или 2 если список параметров не представляет допустимую командную строку 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 равно 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 см. ниже.

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 истинно, файл закрывается до возврата из 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.