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

Функції в цій главі дозволять вам виконувати вихідний код 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`, and `Py_single_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_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`. ім’я файлу розшифровується з filesystem encoding and error handler.

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

int (*PyOS_InputHook)(void)
  Part of the Stable ABI.

  Може вказувати на функцію з прототипом `int func(void)`. Функція буде викликана, коли підказка інтерпретатора Python збирається перейти в режим очікування та чекати введення користувача з терміналу. Повернене значення ігнорується. Перевизначення цього хука можна використати для інтеграції підказки інтерпретатора з іншими циклами подій, як це зроблено в `Modules/_tkinter.c` у вихідному коді Python.

  Змінено в версії 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.

  Виконайте вихідний код Python із str у контексті, визначеному об’єктами globals і locals з прапорцями компілятора, визначеними flags. globals має бути словником; locals може бути будь-яким об’єктом, який реалізує протокол відображення. Параметр start визначає початковий маркер, який слід використовувати для аналізу вихідного коду.

  Повертає результат виконання коду як об’єкт 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 token is given by start; this can be used to constrain the code which can be compiled and should be `Py_eval_input`, `Py_file_input`, or `Py_single_input`. 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 у разі невдачі.

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`, а у випадках, коли код виконується, він передається як `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.

  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.