Слой очень высокого уровня¶
Функции, описанные в этой главе, позволят вам выполнить исходный код 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()
программы на языке Си (преобразованные в wchar_t в соответствии с локалью пользователя). Важно отметить, что список аргументов может быть изменен (но содержимое строк, на которые указывает список аргументов, не изменяется). Возвращаемое значение будет0
, если интерпретатор завершает работу нормально (т. е. без исключения),1
, если интерпретатор завершает работу из-за исключения, или2
, если список параметров не представляет собой корректную командную строку Python.Обратите внимание, что если возникнет необработанный
SystemExit
, эта функция не вернет1
, а завершит процесс, покаPyConfig.inspect
будет равна нулю.
-
int Py_BytesMain(int argc, char **argv)¶
- Часть Стабильный ABI с версии 3.8.
Аналогично
Py_Main()
, но argv - это массив байтовых строк.Added in version 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 из команды в модуле
__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()
ниже, оставляя флаги установленными вNULL
.
-
int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)¶
Аналогично
PyRun_SimpleStringFlags()
, но исходный код Python считывается из fp, а не из строки в памяти. filename должно быть именем файла, оно декодируется из filesystem encoding and error handler. Если closeit равно true, файл будет закрыт до возвратаPyRun_SimpleFileExFlags()
.Примечание
В Windows файл fp должен быть открыт в двоичном режиме (например,
fopen(filename, "rb")
). В противном случае Python может некорректно обрабатывать файл сценария с LF-концом строки.
-
int PyRun_InteractiveOne(FILE *fp, const char *filename)¶
Это упрощенный интерфейс для
PyRun_InteractiveOneFlags()
ниже, оставляя флаги установленными вNULL
.
-
int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)¶
Считывание и выполнение одного оператора из файла, связанного с интерактивным устройством, в соответствии с аргументом flags. Пользователь получает запрос, используя
sys.ps1
иsys.ps2
. Имя filename декодируется из filesystem encoding and error handler.Возвращает
0
, если входные данные были выполнены успешно,-1
, если произошло исключение, или код ошибки из включаемого файлаerrcode.h
, распространяемого как часть Python, если произошла ошибка разбора. (Обратите внимание, чтоerrcode.h
не включается вPython.h
, поэтому при необходимости его нужно включать отдельно).
-
int PyRun_InteractiveLoop(FILE *fp, const char *filename)¶
Это упрощенный интерфейс для
PyRun_InteractiveLoopFlags()
ниже, оставляя флаги установленными вNULL
.
-
int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)¶
Чтение и выполнение операторов из файла, связанного с интерактивным устройством, до достижения EOF. Пользователь получает запрос, используя клавиши
sys.ps1
иsys.ps2
. Имя filename декодируется из filesystem encoding and error handler. Возвращает0
при достижении EOF или отрицательное число при неудаче.
-
int (*PyOS_InputHook)(void)¶
- Часть Стабильный ABI.
Может указывать на функцию с прототипом
int func(void)
. Функция будет вызываться, когда интерпретатор Python будет простаивать и ожидать ввода пользователя с терминала. Возвращаемое значение игнорируется. Переопределение этого хука может быть использовано для интеграции подсказки интерпретатора с другими циклами событий, как это сделано вModules/_tkinter.c
в исходном коде Python.Изменено в версии 3.12: Эта функция вызывается только из main interpreter.
-
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: Эта функция вызывается только из main interpreter.
-
PyObject *PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)¶
- Возвращаемое значение: Новая ссылка.
Это упрощенный интерфейс для
PyRun_StringFlags()
ниже, оставляя флаги установленными в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()
ниже, оставляя флаги установленными в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 должно быть именем файла, оно декодируется из filesystem encoding and error handler. Если closeit равно true, файл будет закрыт до возвратаPyRun_FileExFlags()
.
-
PyObject *Py_CompileString(const char *str, const char *filename, int start)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Это упрощенный интерфейс для
Py_CompileStringFlags()
ниже, оставляя флаги установленными вNULL
.
-
PyObject *Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)¶
- Возвращаемое значение: Новая ссылка.
Это упрощенный интерфейс
Py_CompileStringExFlags()
, приведенный ниже, с оптимизацией, установленной на-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
(удаляются и docstrings).Added in version 3.4.
-
PyObject *Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)¶
- Возвращаемое значение: Новая ссылка.
Аналогично
Py_CompileStringObject()
, но filename - это байтовая строка, декодированная из filesystem encoding and error handler.Added in version 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.
Оценить объект прекомпилированного кода, задав определенное окружение для его оценки. Это окружение состоит из словаря глобальных переменных, объекта отображения локальных переменных, массивов аргументов, ключевых слов и значений по умолчанию, словаря значений по умолчанию для аргументов keyword-only и кортежа закрытия ячеек.
-
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
может изменять флаги.Если
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 cf_flags¶