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

Функции в этой главе позволят вам выполнить код 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, а завершит процесс, если Py_InspectFlag не задан.

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, а завершит процесс, если 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() ниже, оставляя 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 в конце файла или отрицательное число при ошибке.

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

END_OF_DOCUMENT_MARKER

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() ниже, оставляя 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().

END_OF_DOCUMENT_MARKER

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.