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

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

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

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

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

Part of the Стабильный ABI.

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

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

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

Part of the Стабильный 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(). имя файла декодируется из кодировки файловой системы (sys.getfilesystemencoding()). Если имя файла равно NULL, эта функция использует "???" в качестве имени файла. Если значение closeit равно true, файл будет закрыт до возврата PyRun_SimpleFileExFlags().

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(), приведенный ниже, оставляя флаги установленными на 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-строкой, заканчивающейся 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. имя файла расшифровывается из 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. имя файла расшифровывается как filesystem encoding and error handler. Возвращает 0 в EOF или отрицательное число в случае сбоя.

int (*PyOS_InputHook)(void)¶

Part of the Стабильный 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)¶

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

Это упрощенный интерфейс для PyRun_StringFlags(), приведенный ниже, оставляя флаги установленными на 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(), приведенный ниже, оставляя флаги установленными на 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 должно быть именем файла, оно расшифровывается из filesystem encoding and error handler. Если значение closeit равно true, файл будет закрыт до того, как вернется PyRun_FileExFlags().

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

Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

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

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

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

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

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

Проанализируйте и скомпилируйте исходный код Python в формате str, вернув результирующий объект кода. Маркер start задается символом start; это может быть использовано для ограничения кода, который может быть скомпилирован и который должен быть: c:data:Py_eval_input, Py_file_input или Py_single_input. Имя файла, указанное в filename, используется для создания объекта code и может отображаться в сообщениях об отслеживании или исключительных ситуациях SyntaxError. Это возвращает NULL, если код не может быть проанализирован или скомпилирован.

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

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

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

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

Например Py_CompileStringObject(), но имя файла - это строка байтов, декодированная из filesystem encoding and error handler.

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

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

Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

Это упрощенный интерфейс для PyEval_EvalCodeEx(), содержащий только объект code и глобальные и локальные переменные. Остальные аргументы имеют значение 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)¶

Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

PyObject *PyEval_EvalFrame(PyFrameObject *f)¶

Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

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

Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

Это основная, неприкрашенная функция интерпретации Python. Объект code, связанный с фреймом выполнения 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.

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

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

int CO_FUTURE_DIVISION¶

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