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

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

Некоторые из этих функций принимают в качестве параметра начальный символ из грамматики. Доступными начальными символами являются Py_eval_input, Py_file_input и Py_single_input. Они описаны после функций, которые принимают их в качестве параметров.

Обратите внимание, что некоторые из этих функций принимают параметры FILE*. Один конкретный вопрос, требующий осторожного обращения, заключается в том, что структура FILE для различных библиотек C может быть различной и несовместимой. В Windows (по крайней мере) динамически подключаемые расширения могут использовать разные библиотеки, поэтому необходимо следить за тем, чтобы параметры FILE* передавались в эти функции только в том случае, если есть уверенность, что они были созданы той же библиотекой, которую использует среда выполнения Python.

int Py_Main(int argc, wchar_t **argv)¶

Part of the Stable ABI.

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

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

int Py_BytesMain(int argc, char **argv)¶

Part of the Stable ABI since version 3.8.

Аналогично Py_Main(), но argv - это массив байтовых строк.

Добавлено в версии 3.8.

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 из команды в модуле __main__ в соответствии с аргументом флаги. Если __main__ еще не существует, он создается. Возвращает 0 при успехе или -1, если возникло исключение. Если возникла ошибка, нет способа получить информацию об исключении. Значение флагов см. ниже.

Обратите внимание, что если возникнет необработанная в противном случае ошибка 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() ниже, оставляя флаги установленными в NULL.

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

Аналогично PyRun_SimpleStringFlags(), но исходный код Python считывается из fp вместо строки в памяти. filename должно быть именем файла, оно декодируется из filesystem encoding and error handler. Если closeit равно true, файл закрывается до возврата PyRun_SimpleFileExFlags().

Примечание

В Windows fp должен быть открыт в двоичном режиме (например, fopen(filename, "rb")). В противном случае Python может некорректно обрабатывать файл сценария с LF окончанием строки.

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

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

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

Считывание и выполнение одного оператора из файла, связанного с интерактивным устройством, в соответствии с аргументом flags. Пользователю будет предложено использовать sys.ps1 и sys.ps2. Имя filename расшифровывается из аргумента filesystem encoding and error handler.

Возвращает 0 при успешном выполнении ввода, -1 при возникновении исключения или код ошибки из включаемого файла errcode.h, распространяемого как часть Python, если возникла ошибка разбора. (Обратите внимание, что errcode.h не включается в Python.h, поэтому при необходимости его нужно включать специально).

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

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

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

Чтение и выполнение утверждений из файла, связанного с интерактивным устройством, до достижения EOF. Пользователю будет предложено использовать sys.ps1 и sys.ps2. Имя filename декодируется из filesystem encoding and error handler. Возвращает 0 при EOF или отрицательное число при неудаче.

int (*PyOS_InputHook)(void)¶

Part of the Stable ABI.

Может быть задана как указание на функцию с прототипом 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().

PyObject *PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)¶

Return value: New reference.

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

PyObject *PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)¶

Return value: New reference.

Выполнить исходный код Python из str в контексте, заданном объектами globals и locals с флагами компилятора, заданными flags. globals должен быть словарем; locals может быть любым объектом, реализующим протокол отображения. Параметр start указывает начальный токен, который должен быть использован для разбора исходного кода.

Возвращает результат выполнения кода в виде объекта Python, или NULL, если возникло исключение.

PyObject *PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)¶

Return value: New reference.

Это упрощенный интерфейс для PyRun_FileExFlags() ниже, оставляя closeit установленным в 0 и flags установленным в NULL.

PyObject *PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)¶

Return value: New reference.

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

PyObject *PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)¶

Return value: New reference.

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

PyObject *PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)¶

Return value: New reference.

Аналогично PyRun_StringFlags(), но исходный код Python считывается из fp вместо строки в памяти. filename должно быть именем файла, оно декодируется из filesystem encoding and error handler. Если closeit равен true, файл закрывается до возврата PyRun_FileExFlags().

PyObject *Py_CompileString(const char *str, const char *filename, int start)¶

Return value: New reference. Part of the Stable ABI.

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

PyObject *Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)¶

Return value: New reference.

Это упрощенный интерфейс для Py_CompileStringExFlags() ниже, с optimize, установленным на -1.

PyObject *Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)¶

Return value: New reference.

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

Целое число optimize определяет уровень оптимизации компилятора; значение -1 выбирает уровень оптимизации интерпретатора, заданный опциями -O. Явными уровнями являются 0 (без оптимизации; __debug__ - истина), 1 (утверждения удаляются, __debug__ - ложь) или 2 (docstrings также удаляются).

Добавлено в версии 3.4.

PyObject *Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)¶

Return value: New reference.

Подобно Py_CompileStringObject(), но filename - это байтовая строка, декодированная из filesystem encoding and error handler.

Добавлено в версии 3.2.

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

Return value: New reference. Part of the Stable 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)¶

Return value: New reference. Part of the Stable ABI.

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

type PyFrameObject¶

Part of the Limited API (as an opaque struct).

Структура C объектов, используемая для описания объектов кадра. Поля этого типа могут быть изменены в любое время.

PyObject *PyEval_EvalFrame(PyFrameObject *f)¶

Return value: New reference. Part of the Stable ABI.

Оценить кадр выполнения. Это упрощенный интерфейс для PyEval_EvalFrameEx(), для обратной совместимости.

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

Return value: New reference. Part of the Stable 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 может модифицировать флаги.

Когда PyCompilerFlags *flags становится NULL, cf_flags рассматривается как равное 0, и любая модификация, вызванная from __future__ import, отбрасывается.

int cf_flags¶

Флаги компилятора.

int cf_feature_version¶

cf_feature_version - это минорная версия Python. Она должна быть инициализирована в PY_MINOR_VERSION.

По умолчанию поле игнорируется, оно используется тогда и только тогда, когда в cf_flags установлен флаг PyCF_ONLY_AST.

Изменено в версии 3.8: Добавлено поле cf_feature_version.

int CO_FUTURE_DIVISION¶

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