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

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

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

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

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_InteractiveOneObject(FILE *fp, PyObject *filename, PyCompilerFlags *flags)

Считывает и выполняет одну инструкцию из файла, связанного с интерактивным устройством, в соответствии с аргументом flags. Пользователю выводятся приглашения sys.ps1 и sys.ps2. Значение filename должно быть объектом Python типа str.

Возвращает 0, если ввод выполнен успешно, -1 при возникновении исключения или код ошибки из распространяемого вместе с Python заголовочного файла errcode.h при ошибке разбора. (Обратите внимание: errcode.h не включается в Python.h, поэтому при необходимости его нужно подключить отдельно.)

int PyRun_InteractiveOne(FILE *fp, const char *filename)

Это упрощённый интерфейс к PyRun_InteractiveOneFlags(), описанной ниже; аргумент flags имеет значение NULL.

int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

Подобна PyRun_InteractiveOneObject(), но filename имеет тип const char* и декодируется с использованием кодировки файловой системы и обработчика ошибок.

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 устанавливает эту точку перехвата, чтобы обеспечить редактирование строк и автодополнение по клавише Tab.

Результат должен быть строкой, выделенной с помощью 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; с его помощью можно ограничить код, который допускается компилировать. Он должен быть одним из доступных начальных символов. Имя файла, заданное параметром 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 в большинстве случаев можно игнорировать: если он имеет значение true, это приводит к немедленному возбуждению исключения; он используется методами throw() объектов-генераторов.

Изменено в версии 3.4: Теперь эта функция содержит отладочную проверку, помогающую убедиться, что активное исключение не отбрасывается без уведомления.

int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)

Эта функция изменяет флаги текущего кадра выполнения и возвращает true в случае успеха или false в случае неудачи.

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.

Доступ к флагам компилятора осуществляется с помощью макросов:

PyCF_ALLOW_TOP_LEVEL_AWAIT

PyCF_ONLY_AST

PyCF_OPTIMIZED_AST

PyCF_TYPE_COMMENTS

См. раздел флаги компилятора в документации модуля Python ast, который экспортирует эти константы под теми же именами.

Флаги низкого уровня

Следующие флаги и маски предназначены для узкоспециализированных задач стандартной библиотеки и интерактивных интерпретаторов. В коде за пределами стандартной библиотеки редко возникает необходимость их использовать. Они считаются деталями реализации и могут измениться в любой момент.

PyCF_ALLOW_INCOMPLETE_INPUT

Этот флаг — внутренний интерфейс между компилятором и модулем codeop. Не используйте его: его поведение не поддерживается и может измениться без предупреждения.

Если этот флаг установлен, при ошибке компиляции из-за того, что исходный текст заканчивается там, где ожидается продолжение (например, в середине блока с отступом или незакрытой строковой константы), возникает недокументированное исключение _IncompleteInputError, подкласс SyntaxError. Модуль codeop устанавливает этот флаг вместе с PyCF_DONT_IMPLY_DEDENT, чтобы отличать неполный ввод от ввода с настоящей синтаксической ошибкой. Благодаря этому интерактивные интерпретаторы могут запросить следующую строку, а не сообщать об ошибке.

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

PyCF_DONT_IMPLY_DEDENT

По умолчанию при компиляции с начальным символом Py_single_input достижение конца исходного текста неявно закрывает все открытые блоки с отступом. Если установлен этот флаг, открытые блоки закрываются только в том случае, если последняя строка исходного текста заканчивается символом новой строки; в противном случае компиляция завершается ошибкой SyntaxError:

PyCompilerFlags flags = {
    .cf_flags = 0,
    .cf_feature_version = PY_MINOR_VERSION,
};
const char *source = "if a:\n    pass";

/* The "if" block is closed implicitly;
   this returns a code object: */
Py_CompileStringFlags(source, "<input>", Py_single_input, &flags);

/* With the flag, this fails with a SyntaxError,
   because the last line does not end with a newline: */
flags.cf_flags = PyCF_DONT_IMPLY_DEDENT;
Py_CompileStringFlags(source, "<input>", Py_single_input, &flags);

Модуль codeop использует этот флаг для обнаружения неполного интерактивного ввода. Пока пользователь вводит текст внутри блока с отступом, исходный текст ещё не заканчивается символом новой строки, поэтому его не удаётся скомпилировать и у пользователя запрашивается следующая строка.

PyCF_IGNORE_COOKIE

Считывает исходный текст в кодировке UTF-8, игнорируя объявление кодировки PEP 263 («cookie кодировки»), если оно присутствует:

PyCompilerFlags flags = {
    .cf_flags = 0,
    .cf_feature_version = PY_MINOR_VERSION,
};
const char *source = "# coding: latin-1\ns = '\xe9'\n";

/* The coding cookie is honored: byte 0xE9 is decoded as
   Latin-1, and this returns a code object that sets s to "é": */
Py_CompileStringFlags(source, "<input>", Py_file_input, &flags);

/* With the flag, the cookie is ignored and compilation fails
   with a SyntaxError, because 0xE9 is not valid UTF-8: */
flags.cf_flags = PyCF_IGNORE_COOKIE;
Py_CompileStringFlags(source, "<input>", Py_file_input, &flags);

Встроенные функции compile(), eval() и exec() устанавливают этот флаг, если исходный текст является объектом str, поскольку передают текст анализатору, закодировав его в UTF-8.

PyCF_SOURCE_IS_UTF8

Указывает, что исходный текст заведомо закодирован в UTF-8. Встроенные функции compile(), eval() и exec() устанавливают этот флаг, однако в настоящее время он не оказывает никакого влияния.

Приведённые выше флаги «PyCF» можно комбинировать с флагами «CO_FUTURE», например CO_FUTURE_ANNOTATIONS, чтобы включить функции, которые обычно выбираются с помощью инструкций future. Полный список см. в разделе Флаги объекта кода.

Следующие маски объединяют несколько флагов:

PyCF_MASK

Битовая маска всех флагов CO_FUTURE (см. раздел Флаги объекта кода), которые выбирают функции, обычно включаемые с помощью инструкций future. Если код, скомпилированный с аргументом PyCompilerFlags *flags, содержит инструкцию from __future__ import, флаг импортированной функции добавляется в flags, чтобы последующий код, выполняемый в том же контексте, наследовал его.

PyCF_MASK_OBSOLETE

Не используйте эту маску в новом коде. Она сохранена только для того, чтобы старый код, передающий свои флаги в compile(), продолжал работать.

Битовая маска флагов устаревших функций future, которые больше не оказывают никакого влияния.

PyCF_COMPILE_MASK

Битовая маска всех флагов PyCF, изменяющих способ компиляции исходного кода, например PyCF_ONLY_AST. Встроенная функция compile() использует эту маску для проверки аргумента flags.