Рівень дуже високого рівня

Функції в цій главі дозволять вам виконувати вихідний код Python, поданий у файлі або буфері, але вони не дозволять вам більш детально взаємодіяти з інтерпретатором.

Several of these functions accept a start symbol from the grammar as a parameter. The available start symbols are Py_eval_input, Py_file_input, Py_single_input, and Py_func_type_input. These are described following the functions which accept them as parameters.

Note also that several of these functions take FILE* parameters. One particular issue which needs to be handled carefully is that the FILE structure for different C libraries can be different and incompatible. Under Windows (at least), it is possible for dynamically linked extensions to actually use different libraries, so care should be taken that FILE* parameters are only passed to these functions if it is certain that they were created by the same library that the Python runtime is using.

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().*ім’я файлу* розшифровується з кодування файлової системи (sys.getfilesystemencoding()). Якщо ім’я файлу має значення NULL, ця функція використовує "???" як ім’я файлу. Якщо closeit має значення true, файл закривається до повернення PyRun_SimpleFileExFlags().

int PyRun_SimpleString(const char *command)

This is a simplified interface to PyRun_SimpleStringFlags() below, leaving the PyCompilerFlags* argument set to NULL.

int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)

Виконує вихідний код Python з команди в модулі __main__ відповідно до аргументу flags. Якщо __main__ ще не існує, він буде створений. Повертає 0 у разі успіху або -1, якщо було викликано виключення. Якщо сталася помилка, неможливо отримати інформацію про винятки. Про значення прапорів дивіться нижче.

Note that if an otherwise unhandled SystemExit is raised, this function will not return -1, but exit the process, as long as PyConfig.inspect is zero.

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 має бути назвою файлу, воно розшифровується з filesystem encoding and error handler. Якщо closeit має значення true, файл закривається до повернення PyRun_SimpleFileExFlags().

Примітка

У Windows fp слід відкривати як бінарний режим (наприклад, fopen(filename, "rb")). Інакше Python може неправильно обробити файл сценарію з закінченням рядка LF.

int PyRun_InteractiveOneObject(FILE *fp, PyObject *filename, PyCompilerFlags *flags)

Read and execute a single statement from a file associated with an interactive device according to the flags argument. The user will be prompted using sys.ps1 and sys.ps2. filename must be a Python str object.

Повертає 0, якщо введення було виконано успішно, -1, якщо стався виняток, або код помилки з файлу включення errcode.h, який поширюється як частина Python, якщо був помилка аналізу. (Зауважте, що 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)

Similar to PyRun_InteractiveOneObject(), but filename is a const char*, which is decoded from the filesystem encoding and error handler.

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. ім’я файлу розшифровується з filesystem encoding and error handler. Повертає 0 на EOF або від’ємне число у разі помилки.

int (*PyOS_InputHook)(void)

Part of the Stable ABI.

Can be set to point to a function with the prototype int func(void). The function will be called when Python’s interpreter prompt is about to become idle and wait for user input from the terminal. The return value is ignored. Overriding this hook can be used to integrate the interpreter’s prompt with other event loops, as done in Modules/_tkinter.c in the Python source code.

Змінено в версії 3.12: This function is only called from the 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: This function is only called from the main interpreter.

PyObject *PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)

Return value: New reference.

Це спрощений інтерфейс для PyRun_StringFlags() нижче, залишаючи flags встановленими на NULL.

PyObject *PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)

Return value: New reference.

Execute Python source code from str in the context specified by the objects globals and locals with the compiler flags specified by flags. globals must be a dictionary; locals can be any object that implements the mapping protocol. The parameter start specifies the start symbol and must be one of the available start symbols.

Повертає результат виконання коду як об’єкт Python або NULL, якщо було викликано виняткову ситуацію.

PyObject *PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)

Return value: New reference.

Це спрощений інтерфейс для PyRun_FileExFlags() нижче, залишаючи closeit встановленим на 0 і flags встановленим на NULL.

PyObject *PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)

Return value: New reference.

Це спрощений інтерфейс для PyRun_FileExFlags() нижче, залишаючи flags встановленими на NULL.

PyObject *PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)

Return value: New reference.

Це спрощений інтерфейс для PyRun_FileExFlags() нижче, залишаючи closeit встановленим на 0.

PyObject *PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)

Return value: New reference.

Подібно до PyRun_StringFlags(), але вихідний код Python читається з fp замість рядка в пам’яті. ім’я файлу має бути ім’ям файлу, воно декодується з filesystem encoding and error handler. Якщо closeit має значення true, файл закривається до повернення PyRun_FileExFlags().

PyObject *Py_CompileString(const char *str, const char *filename, int start)

Return value: New reference. Part of the Stable ABI.

Це спрощений інтерфейс для Py_CompileStringFlags() нижче, залишаючи flags встановленими на NULL.

PyObject *Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)

Return value: New reference.

Це спрощений інтерфейс для Py_CompileStringExFlags() нижче, з optimize встановленим на -1.

PyObject *Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)

Return value: New reference.

Parse and compile the Python source code in str, returning the resulting code object. The start symbol is given by start; this can be used to constrain the code which can be compiled and should be available start symbols. The filename specified by filename is used to construct the code object and may appear in tracebacks or SyntaxError exception messages. This returns NULL if the code cannot be parsed or compiled.

Ціле число optimize визначає рівень оптимізації компілятора; значення -1 вибирає рівень оптимізації інтерпретатора, як задано параметрами -O. Явні рівні: 0 (немає оптимізації; __debug__ є істинним), 1 (затвердження видалено, __debug__ є хибним) або 2 (рядки документа також видалено ).

Added in version 3.4.

PyObject *Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)

Return value: New reference.

Подібно до Py_CompileStringObject(), але filename — це рядок байтів, декодований з filesystem encoding and error handler.

Added in version 3.2.

PyObject *PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)

Return value: New reference. Part of the Stable 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)

Return value: New reference. Part of the Stable ABI.

Оцініть попередньо скомпільований об’єкт коду з урахуванням певного середовища для його оцінки. Це середовище складається зі словника глобальних змінних, об’єкта відображення локальних змінних, масивів аргументів, ключових слів і значень за замовчуванням, словника значень за замовчуванням для аргументів keyword-only і закриваючого кортежу клітинок.

PyObject *PyEval_EvalFrame(PyFrameObject *f)

Return value: New reference. Part of the Stable ABI.

Оцініть кадр виконання. Це спрощений інтерфейс для PyEval_EvalFrameEx() для зворотної сумісності.

PyObject *PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)

Return value: New reference. Part of the Stable ABI.

Це основна функція інтерпретації Python без прикрас. Об’єкт коду, пов’язаний із кадром виконання f, виконується, інтерпретуючи байт-код і виконуючи виклики за потреби. Додатковий параметр throwflag здебільшого можна ігнорувати - якщо воно істинне, то це спричиняє миттєве виключення винятку; це використовується для методів throw() об’єктів генератора.

Змінено в версії 3.4: Ця функція тепер включає твердження налагодження, щоб гарантувати, що вона не відкидає мовчки активний виняток.

int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)

Ця функція змінює прапори поточного кадру оцінки та повертає true у разі успіху, false у разі невдачі.

struct PyCompilerFlags

Це структура, яка використовується для зберігання прапорів компілятора. У випадках, коли код лише компілюється, він передається як прапорці int, а у випадках, коли код виконується, він передається як PyCompilerFlags *flags. У цьому випадку from __future__ import може змінювати прапори.

Whenever PyCompilerFlags *flags is NULL, cf_flags is treated as equal to 0, and any modification due to from __future__ import is discarded.

int cf_flags

Прапори компілятора.

int cf_feature_version

cf_feature_version є другорядною версією Python. Його слід ініціалізувати як PY_MINOR_VERSION.

The field is ignored by default, it is used if and only if PyCF_ONLY_AST flag is set in cf_flags.

Змінено в версії 3.8: Додано поле cf_feature_version.

The available compiler flags are accessible as macros:

PyCF_ALLOW_TOP_LEVEL_AWAIT

PyCF_ONLY_AST

PyCF_OPTIMIZED_AST

PyCF_TYPE_COMMENTS

See compiler flags in documentation of the ast Python module, which exports these constants under the same names.

Low-level flags

The following flags and masks serve narrow needs of the standard library and interactive interpreters. Code outside the standard library rarely has a reason to use them. They are considered implementation details and may change at any time.

PyCF_ALLOW_INCOMPLETE_INPUT

This flag is a private interface between the compiler and the codeop module. Do not use it; its behavior is unsupported and may change without warning.

With this flag set, when compilation fails because the source text ends where more input is expected, for example in the middle of an indented block or an unterminated string literal, the error raised is the undocumented _IncompleteInputError, a subclass of SyntaxError. The codeop module sets this flag, together with PyCF_DONT_IMPLY_DEDENT, to tell input that is incomplete apart from input with a real syntax error, so that interactive interpreters know when to prompt for another line instead of reporting an error.

Added in version 3.11.

PyCF_DONT_IMPLY_DEDENT

By default, when compiling with the Py_single_input start symbol, reaching the end of the source text implicitly closes any open indented blocks. With this flag set, open blocks are only closed if the last line of the source ends with a newline; otherwise, compilation fails with a 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);

The codeop module uses this flag to detect incomplete interactive input. While the user is still typing inside an indented block, the source does not yet end with a newline, so it fails to compile and the user is prompted for another line.

PyCF_IGNORE_COOKIE

Read the source text as UTF-8, ignoring its PEP 263 encoding declaration («coding cookie»), if any:

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);

The compile(), eval() and exec() built-in functions set this flag when the source is a str object, because they pass the text to the parser encoded as UTF-8.

PyCF_SOURCE_IS_UTF8

Mark the source text as known to be UTF-8 encoded. The compile(), eval() and exec() built-in functions set this flag, but it currently has no effect.

The «PyCF» flags above can be combined with «CO_FUTURE» flags such as CO_FUTURE_ANNOTATIONS to enable features normally selectable using future statements. See Code Object Flags for a complete list.

The following masks combine several flags:

PyCF_MASK

Bitmask of all CO_FUTURE flags (see Code Object Flags), which select features normally enabled by future statements. When code compiled with a PyCompilerFlags *flags argument contains a from __future__ import statement, the flag for the imported feature is added to flags, so that code executed later in the same context inherits it.

PyCF_MASK_OBSOLETE

Do not use this mask in new code. It is kept only so that old code passing its flags to compile() keeps working.

Bitmask of flags for obsolete future features that no longer have any effect.

PyCF_COMPILE_MASK

Bitmask of all PyCF flags that change how the source is compiled, such as PyCF_ONLY_AST. The compile() built-in function uses this mask to validate its flags argument.

Available start symbols

int Py_eval_input

Початковий символ із граматики Python для ізольованих виразів; для використання з Py_CompileString().

int Py_file_input

Початковий символ із граматики Python для послідовностей операторів, прочитаних із файлу чи іншого джерела; для використання з Py_CompileString(). Це символ, який слід використовувати під час компіляції будь-якої довжини вихідного коду Python.

int Py_single_input

Початковий символ із граматики Python для окремого оператора; для використання з Py_CompileString(). Це символ, який використовується для інтерактивного циклу інтерпретатора.

int Py_func_type_input

The start symbol from the Python grammar for a function type; for use with Py_CompileString(). This is used to parse «signature type comments» from PEP 484.

This requires the PyCF_ONLY_AST flag to be set.

Дивись також

• ast.FunctionType

• PEP 484

Added in version 3.8.

Stack Effects

Дивись також

dis.stack_effect()

PY_INVALID_STACK_EFFECT

Sentinel value representing an invalid stack effect.

This is currently equivalent to INT_MAX.

Added in version 3.8.

int PyCompile_OpcodeStackEffect(int opcode, int oparg)

Compute the stack effect of opcode with argument oparg.

On success, this function returns the stack effect; on failure, this returns PY_INVALID_STACK_EFFECT.

Added in version 3.4.

int PyCompile_OpcodeStackEffectWithJump(int opcode, int oparg, int jump)

Similar to PyCompile_OpcodeStackEffect(), but don’t include the stack effect of jumping if jump is zero.

If jump is 0, this will not include the stack effect of jumping, but if jump is 1 or -1, this will include it.

On success, this function returns the stack effect; on failure, this returns PY_INVALID_STACK_EFFECT.

Added in version 3.8.