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

Функции в этой главе позволят вам выполнить исходный код 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 истинно, файл закрывается перед тем, как 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 истинно, файл закрывается перед тем, как 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 равно истине, файл закрывается до возврата 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__ равно истине), 1 (убираются утверждения, __debug__ равно ложной) или 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.
Выполняет предварительно скомпилированный объект кода, учитывая определённую среду для его выполнения. Эта среда состоит из словаря глобальных переменных, объекта отображения локальных переменных, массивов аргументов, ключевых слов и значений по умолчанию, словаря значений по умолчанию для ключевых аргументов и кортежа замыканий ячеек.

type PyFrameObject: Часть Ограниченного API (как неявная структура).
Структура C-объектов, используемых для описания объектов кадров. Поля этого типа могут изменяться в любое время.

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): Эта функция изменяет флаги текущего кадра выполнения и возвращает истинное значение при успехе, ложное — при ошибке.

int Py_eval_input: Начальный символ из грамматики Python для изолированных выражений; для использования с Py_CompileString().

int Py_file_input: Начальный символ из грамматики Python для последовательностей операторов, читаемых из файла или другого источника; для использования с Py_CompileString(). Это символ, который следует использовать при компиляции произвольно длинного исходного кода Python.

END_OF_DOCUMENT_MARKER

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.