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

Функції в цій главі дозволять вам виконувати вихідний код 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 `Py_Main`(int argc, wchar_t **argv)
  Part of the Stable ABI.

  The main program for the standard interpreter. This is made available for programs which embed Python. The argc and argv parameters should be prepared exactly as those which are passed to a C program’s `main()` function (converted to wchar_t according to the user’s locale). It is important to note that the argument list may be modified (but the contents of the strings pointed to by the argument list are not). The return value will be `0` if the interpreter exits normally (i.e., without an exception), `1` if the interpreter exits due to an exception, or `2` if the parameter list does not represent a valid Python command line.

  Note that if an otherwise unhandled `SystemExit` is raised, this function will not return `1`, but exit the process, as long as `Py_InspectFlag` is not set.

int `Py_BytesMain`(int argc, char **argv)
  Part of the Stable ABI since version 3.8.

  Similar to `Py_Main()` but argv is an array of bytes strings.

  Нове в версії 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()`.*ім’я файлу* розшифровується з кодування файлової системи (`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 `Py_InspectFlag` is not set.

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.

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()`.

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` (рядки документа також видалено ).

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

  Нове в версії 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 і закриваючого кортежу клітинок.

type `PyFrameObject`
  Part of the Limited API (as an opaque struct).

  The C structure of the objects used to describe frame objects. The fields of this type are subject to change at any time.

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.

int `CO_FUTURE_DIVISION`

  Цей біт можна встановити у flags, щоб оператор ділення `/` інтерпретувався як «дійсне ділення» відповідно до PEP 238.