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

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

Изменено в версии 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 истинно, файл закрывается до возврата из 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 (инструкции assert удаляются, __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 в основном можно игнорировать: если он истинный, исключение немедленно возбуждается. Этот параметр используется методами 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.

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

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

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