Слой очень высокого уровня¶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. Важно отметить, что список аргументов может быть изменён (однако содержимое строк, на которые указывают элементы списка аргументов, не изменяется). Возвращаемое значение будет равно 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 равно 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_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. Пользователю будет предложен ввод с помощью 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. Пользователю будет предложен ввод с помощью 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.