Слой очень высокого уровня¶The Very High Level Layer
Функции этой главы позволяют выполнять исходный код Python, переданный в файле или буфере, но не дают возможности взаимодействовать с интерпретатором на более детальном уровне.
Некоторые из этих функций принимают начальный символ грамматики в качестве параметра. Доступные начальные символы: Py_eval_input, Py_file_input и Py_single_input. Они описаны после функций, которые принимают их в качестве параметров.
Также стоит отметить, что некоторые из этих функций принимают параметры типа FILE*. Одна из проблем, которую нужно аккуратно учитывать: структура FILE из разных библиотек C может различаться и быть несовместимой. В Windows (по крайней мере) динамически связываемые расширения могут на самом деле использовать разные библиотеки, поэтому следует соблюдать осторожность: параметры FILE* следует передавать этим функциям только в том случае, если точно известно, что они созданы той же библиотекой, которую использует среда выполнения Python.
- int Py_Main(int argc, wchar_t **argv)¶
Основная программа стандартного интерпретатора. Она предоставляется для программ, в которые встраивается Python. Параметры argc и argv должны быть подготовлены точно так же, как те, которые передаются функции main() программы на C (преобразованные в wchar_t в соответствии с локалью пользователя). Важно отметить, что список аргументов может быть изменён (но содержимое строк, на которые указывает список аргументов, не изменяется). Возвращаемое значение будет 0, если интерпретатор завершился нормально (т.е. без исключения), 1, если интерпретатор завершился из-за исключения, или 2, если список параметров не представляет корректную командную строку Python.
Обратите внимание, что если возникнет неперехваченное исключение SystemExit, эта функция не вернёт 1, а завершит процесс, при условии, что флаг Py_InspectFlag не установлен.
- 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, эта функция использует "???" в качестве имени файла.
- 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 должно быть именем файла; оно декодируется из кодировки файловой системы (sys.getfilesystemencoding()). Если closeit истинно, файл закрывается до возврата из PyRun_SimpleFileExFlags.
- 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 декодируется из кодировки файловой системы (sys.getfilesystemencoding()).
Возвращает 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)¶
Читает и выполняет инструкции из файла, связанного с интерактивным устройством, до достижения EOF. Пользователю будет выводиться приглашение с помощью sys.ps1 и sys.ps2. filename декодируется из кодировки файловой системы (sys.getfilesystemencoding()). Возвращает 0 при EOF.
- struct _node* PyParser_SimpleParseString(const char *str, int start)¶
Это упрощённый интерфейс к PyParser_SimpleParseStringFlagsFilename() ниже, оставляя filename установленным в NULL, а flags – в 0.
- struct _node* PyParser_SimpleParseStringFlags(const char *str, int start, int flags)¶
Это упрощённый интерфейс к PyParser_SimpleParseStringFlagsFilename() ниже, оставляя filename установленным в NULL.
- struct _node* PyParser_SimpleParseStringFlagsFilename(const char *str, const char *filename, int start, int flags)¶
Разбирает исходный код Python из str, используя начальный токен start в соответствии с аргументом flags. Результат можно использовать для создания объекта кода, который может вычисляться эффективно. Это полезно, если фрагмент кода должен вычисляться много раз. filename декодируется из кодировки файловой системы (sys.getfilesystemencoding()).
- struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)¶
Это упрощённый интерфейс к PyParser_SimpleParseFileFlags() ниже, оставляя flags равным 0
- struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)¶
Аналогично PyParser_SimpleParseStringFlagsFilename(), но исходный код Python читается из fp вместо строки в памяти.
- 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. Параметр 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 должен быть именем файла, он декодируется из кодировки файловой системы (sys.getfilesystemencoding()). Если closeit истинно, файл закрывается до того, как PyRun_FileExFlags() вернёт результат.
- PyObject* Py_CompileString(const char *str, const char *filename, int start)¶
- Возвращаемое значение: новая ссылка.
Это упрощённый интерфейс к Py_CompileStringFlags() ниже, оставляя flags установленным в NULL.
- PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)¶
- Возвращаемое значение: новая ссылка.
Это упрощённый интерфейс к Py_CompileStringExFlags(), приведённой ниже, с optimize, установленным в -1.
- PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)¶
Разбирает и компилирует исходный код Python из str, возвращая результирующий объект кода. Начальный токен задаётся start; его можно использовать для ограничения компилируемого кода, и он должен быть Py_eval_input, Py_file_input или Py_single_input. Имя файла, указанное в filename, используется для создания объекта кода и может появляться в трассировках или сообщениях исключений SyntaxError, оно декодируется из кодировки файловой системы (sys.getfilesystemencoding()). Возвращает NULL, если код не может быть разобран или скомпилирован.
Целое число optimize задаёт уровень оптимизации компилятора; значение -1 выбирает уровень оптимизации интерпретатора, заданный опциями -O. Явные уровни: 0 (без оптимизации; __debug__ равен true), 1 (утверждения удалены, __debug__ равен false) или 2 (докстроки также удалены).
Новое в версии 3.2.
- PyObject* PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)¶
- Возвращаемое значение: новая ссылка.
Это упрощённый интерфейс к PyEval_EvalCodeEx(), принимающий только объект кода и словари глобальных и локальных переменных. Остальные аргументы устанавливаются в NULL.
- PyObject* PyEval_EvalCodeEx(PyObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *closure)¶
Выполняет предварительно скомпилированный объект кода в заданном окружении. Это окружение состоит из словарей глобальных и локальных переменных, массивов аргументов, ключевых слов и значений по умолчанию, а также кортежа замыкания с ячейками.
- PyObject* PyEval_EvalFrame(PyFrameObject *f)¶
Выполняет фрейм исполнения. Это упрощённый интерфейс к PyEval_EvalFrameEx для обратной совместимости.
- PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)¶
Это основная, неприукрашенная функция интерпретации Python. Она буквально насчитывает 2000 строк. Объект кода, связанный с фреймом исполнения f, выполняется: интерпретируется байт-код и по необходимости вызываются функции. Дополнительный параметр throwflag в основном можно игнорировать: если он истинен, то немедленно выбрасывается исключение; это используется для методов throw() объектов-генераторов.
- 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, отбрасываются.
struct PyCompilerFlags { int cf_flags; }