Уровень очень высокого уровня

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

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

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

int Py_Main(int argc, wchar_t **argv)

Часть Стабильной ABI.

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

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

int Py_BytesMain(int argc, char **argv): Часть Стабильной ABI с версии 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 из command в модуле __main__ в соответствии с аргументом flags. Если __main__ ещё не существует, он создаётся. Возвращает 0 при успешном выполнении или -1 при возникновении исключения. Если произошла ошибка, получить информацию об исключении невозможно. Смысл flags см. ниже.

Обратите внимание, что если поднимается исключение SystemExit, которое иначе не обрабатывается, эта функция не вернёт -1, а завершит процесс, при условии, что PyConfig.inspect равно нулю.

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() ниже, при этом flags установлено в NULL.

int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags): Аналогично PyRun_SimpleStringFlags(), но исходный код Python читается из fp вместо строковой переменной. filename должно быть именем файла, оно декодируется из кодировки файловой системы и обработчика ошибок. Если closeit равно true, файл закрывается перед возвратом PyRun_SimpleFileExFlags().

Примечание

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

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. filename декодируется из кодировки файловой системы и обработчика ошибок.

Возвращает 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): Считывает и выполняет операторы из файла, связанного с интерактивным устройством, до тех пор, пока не будет достигнут конец файла. Пользователь будет приглашён с помощью sys.ps1 и sys.ps2. filename декодируется из кодировки файловой системы и обработчика ошибок. Возвращает 0 в конце файла или отрицательное число при ошибке.

END_OF_DOCUMENT_MARKER

int (*PyOS_InputHook)(void): Часть Стабильной ABI.
Может быть установлено для указания на функцию с прототипом int func(void). Функция будет вызвана, когда интерпретатор Python собирается перейти в состояние ожидания и ждать ввода от пользователя с терминала. Значение возврата игнорируется. Переопределение этого хука может использоваться для интеграции приглашения интерпретатора с другими циклами обработки событий, как это сделано в Modules/_tkinter.c в исходном коде Python.

Изменено в версии 3.12: Эта функция вызывается только из главного интерпретатора.

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().

Изменено в версии 3.12: Эта функция вызывается только из главного интерпретатора.

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. 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() ниже, оставляя 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 равно true, файл закрывается перед возвратом PyRun_FileExFlags().

PyObject *Py_CompileString(const char *str, const char *filename, int start): Значение возврата: Новая ссылка. Часть Стабильной ABI.
Это упрощённый интерфейс к Py_CompileStringFlags() ниже, оставляя flags равным NULL.

PyObject *Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags): Значение возврата: Новая ссылка.
Это упрощённый интерфейс к Py_CompileStringExFlags() ниже, с optimize равным -1.

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

Значение возврата: Новая ссылка.

Анализ и компиляция исходного кода Python в str, возвращая полученный объект кода. Начальный токен задаётся start; это может использоваться для ограничения кода, который может быть скомпилирован, и должен быть Py_eval_input, Py_file_input или Py_single_input. Имя файла, указанное filename, используется для создания объекта кода и может появляться в трассировках или сообщениях об исключении 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(), но filename — это строка байтов, декодированная из кодировки и обработчика ошибок файловой системы.

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

PyObject *PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals): Значение возврата: Новая ссылка. Часть Стабильной 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): Значение возврата: Новая ссылка. Часть Стабильной ABI.
Оценивает прекомпилированный объект кода, учитывая конкретную среду для его оценки. Эта среда состоит из словаря глобальных переменных, объекта отображения локальных переменных, массивов аргументов, ключевых слов и значений по умолчанию, словаря значений по умолчанию для ключевых аргументов и кортежа замыканий ячеек.

PyObject *PyEval_EvalFrame(PyFrameObject *f): Значение возврата: Новая ссылка. Часть Стабильной ABI.
Оценивает фрейм выполнения. Это упрощённый интерфейс к PyEval_EvalFrameEx(), для обратной совместимости.

PyObject *PyEval_EvalFrameEx(PyFrameObject *f, int throwflag): Значение возврата: Новая ссылка. Часть Стабильной 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 может изменить flags.

Всякий раз, когда 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.