# La capa de muy alto nivel

Las funciones en este capítulo te permitirán ejecutar código fuente de Python desde un archivo o un búfer, pero no te permitirán interactuar de una manera detallada con el intérprete.

Varias de estas funciones aceptan un símbolo de inicio de la gramática como parámetro. Los símbolos de inicio disponibles son `Py_eval_input`, `Py_file_input`, y `Py_single_input`. Estos se describen siguiendo las funciones que los aceptan como parámetros.

Tenga en cuenta también que varias de estas funciones toman parámetros `FILE*`. Una cuestión particular que debe manejarse con cuidado es que la estructura `FILE` para diferentes bibliotecas en C puede ser diferente e incompatible. En Windows (al menos), es posible que las extensiones vinculadas dinámicamente utilicen diferentes bibliotecas, por lo que se debe tener cuidado de que los parámetros `FILE*` solo se pasen a estas funciones si es seguro que estaban creado por la misma biblioteca que está utilizando el tiempo de ejecución de Python.

int `Py_Main`(int argc, wchar_t **argv)

  El programa principal para el intérprete estándar. Está disponible para programas que incorporan Python. Los parámetros argc y argv deben prepararse exactamente como los que se pasan a la función `main()` de un programa en C (convertido a wchar_t de acuerdo con la configuración regional del usuario). Es importante tener en cuenta que la lista de argumentos puede ser modificada (pero el contenido de las cadenas de caracteres señaladas por la lista de argumentos no lo es). El valor de retorno será `0` si el intérprete acaba normalmente (es decir, sin excepción), `1` si el intérprete acaba debido a una excepción, o `2` si la lista de parámetros no representa una línea de comando Python válida.

  Tenga en cuenta que si se lanza un `SystemExit` no manejado, esta función no retornará `1`, pero saldrá del proceso, siempre que `Py_InspectFlag` no esté configurado.

int `Py_BytesMain`(int argc, char **argv)

  Similar a `Py_Main()` pero argv es un arreglo de cadenas de caracteres de bytes.

  Nuevo en la versión 3.8.

int `PyRun_AnyFile`(FILE *fp, const char *filename)

  Esta es una interfaz simplificada para `PyRun_AnyFileExFlags()` más abajo, dejando closeit establecido a `0` y flags establecido a `NULL`.

int `PyRun_AnyFileFlags`(FILE *fp, const char *filename, PyCompilerFlags *flags)

  Esta es una interfaz simplificada para `PyRun_AnyFileExFlags()` más abajo, dejando closeit establecido a `0`.

int `PyRun_AnyFileEx`(FILE *fp, const char *filename, int closeit)

  Esta es una interfaz simplificada para `PyRun_AnyFileExFlags()` más abajo, dejando flags establecido a `NULL`.

int `PyRun_AnyFileExFlags`(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

  If fp refers to a file associated with an interactive device (console or terminal input or Unix pseudo-terminal), return the value of `PyRun_InteractiveLoop()`, otherwise return the result of `PyRun_SimpleFile()`. filename is decoded from the filesystem encoding (`sys.getfilesystemencoding()`). If filename is `NULL`, this function uses `"???"` as the filename. If closeit is true, the file is closed before `PyRun_SimpleFileExFlags()` returns.

int `PyRun_SimpleString`(const char *command)

  Esta es una interfaz simplificada para `PyRun_SimpleStringFlags()` más abajo, dejando el argumento `PyCompilerFlags`* establecido a `NULL`.

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

  Ejecuta el código fuente de Python desde command en el módulo `__main__` de acuerdo con el argumento flags. Si `__main__` aún no existe, se crea. Retorna `0` en caso de éxito o `-1` si se produjo una excepción. Si hubo un error, no hay forma de obtener la información de excepción. Para el significado de flags, ver abajo.

  Tenga en cuenta que si no se maneja de otro modo `SystemExit`, esta función no retornará `-1`, pero saldrá del proceso, siempre que `Py_InspectFlag` no esté configurado.

int `PyRun_SimpleFile`(FILE *fp, const char *filename)

  Esta es una interfaz simplificada para `PyRun_SimpleStringFlags()` más abajo, dejando closeit establecido a `0` y flags establecido a `NULL`.

int `PyRun_SimpleFileEx`(FILE *fp, const char *filename, int closeit)

  Esta es una interfaz simplificada para `PyRun_SimpleStringFlags()` más abajo, dejando flags establecido a `NULL`.

int `PyRun_SimpleFileExFlags`(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

  Similar a `PyRun_SimpleStringFlags()`, pero el código fuente de Python se lee desde fp en lugar de una cadena de caracteres en memoria. filename debe ser el nombre del archivo, se decodifica a partir de la codificación del sistema de archivos (`sys.getfilesystemencoding()`). Si closeit es verdadero, el archivo se cierra antes de que PyRun_SimpleFileExFlags retorne.

  Nota

  En Windows, fp debe abrirse en modo binario (por ejemplo, `fopen(filename, "rb")`. De lo contrario, Python puede no manejar correctamente el archivo de script con la terminación de línea LF.

int `PyRun_InteractiveOne`(FILE *fp, const char *filename)

  Esta es una interfaz simplificada para `PyRun_InteractiveOneFlags()` más abajo, dejando flags establecido a `NULL`.

int `PyRun_InteractiveOneFlags`(FILE *fp, const char *filename, PyCompilerFlags *flags)

  Lee y ejecuta declaraciones de un archivo asociado con un dispositivo interactivo de acuerdo al argumento flags. Se le solicitará al usuario usando `sys.ps1` y `sys.ps2`. filename se decodifica a partir de la codificación del sistema de archivos (`sys.getfilesystemencoding()`).

  Retorna `0` cuando la entrada se ejecuta con éxito, `-1` si hubo una excepción, o un código de error del archivo `errcode.h` distribuido como parte de Python si hubo un error de análisis gramatical. (Tenga en cuenta que `errcode.h` no está incluido en `Python.h`, por lo que debe incluirse específicamente si es necesario).

int `PyRun_InteractiveLoop`(FILE *fp, const char *filename)

  Esta es una interfaz simplificada para `PyRun_InteractiveLoopFlags()` más abajo, dejando flags establecido a `NULL`.

int `PyRun_InteractiveLoopFlags`(FILE *fp, const char *filename, PyCompilerFlags *flags)

  Lee y ejecuta declaraciones de un archivo asociado con un dispositivo interactivo hasta llegar al EOF. Se le solicitará al usuario usando `sys.ps1` y `sys.ps2`. filename se decodifica a partir de la codificación del sistema de archivos (`sys.getfilesystemencoding()`). Retorna `0` en EOF o un número negativo en caso de falla.

int `(*PyOS_InputHook)`(void)

  Se puede configurar para que apunte a una función con el prototipo `int func(void)`. Se llamará a la función cuando el indicador del intérprete de Python esté a punto de estar inactivo y espere la entrada del usuario desde el terminal. El valor de retorno es ignorado. Sobrescribiendo este enlace se puede utilizar para integrar la solicitud del intérprete con otros bucles de eventos, como se hace en `Modules/_tkinter.c` en el código fuente de Python.

char* `(*PyOS_ReadlineFunctionPointer)`(FILE *, FILE *, const char *)

  Se puede configurar para que apunte a una función con el prototipo `char *func (FILE *stdin, FILE *stdout, char *prompt)`, sobrescribiendo la función predeterminada utilizada para leer una sola línea de entrada desde el intérprete. Se espera que la función genere la cadena de caracteres prompt si no es `NULL`, y luego lea una línea de entrada del archivo de entrada estándar proporcionado, retornando la cadena de caracteres resultante. Por ejemplo, el módulo `readline` establece este enlace para proporcionar funciones de edición de línea y finalización de tabulación.

  El resultado debe ser una cadena de caracteres alocado por `PyMem_RawMalloc()` o `PyMem_RawRealloc()`, o `NULL` si ocurre un error.

  Distinto en la versión 3.4: El resultado debe ser alocado por `PyMem_RawMalloc()` o `PyMem_RawRealloc()`, en vez de ser alocado por `PyMem_Malloc()` o `PyMem_Realloc()`.

struct _node* `PyParser_SimpleParseString`(const char *str, int start)

  Esta es una interfaz simplificada para `PyParser_SimpleParseStringFlagsFilename()` más abajo, dejando filename establecido a `NULL` y flags establecido a `0`.

  Deprecated since version 3.9, will be removed in version 3.10.

struct _node* `PyParser_SimpleParseStringFlags`(const char *str, int start, int flags)

  Esta es una interfaz simplificada para `PyParser_SimpleParseStringFlagsFilename()` más abajo, dejando filename establecido a `NULL`.

  Deprecated since version 3.9, will be removed in version 3.10.

struct _node* `PyParser_SimpleParseStringFlagsFilename`(const char *str, const char *filename, int start, int flags)

  Analiza gramaticalmente el código fuente de Python desde str usando el token de inicio start de acuerdo con el argumento flags. El resultado se puede usar para crear un objeto de código que se puede evaluar de manera eficiente. Esto es útil si un fragmento de código debe evaluarse muchas veces. filename se decodifica a partir de la codificación del sistema de archivos (`sys.getfilesystemencoding()`).

  Deprecated since version 3.9, will be removed in version 3.10.

struct _node* `PyParser_SimpleParseFile`(FILE *fp, const char *filename, int start)

  Esta es una interfaz simplificada para `PyParser_SimpleParseFileFlags()` más abajo, dejando flags establecido a `0`.

  Deprecated since version 3.9, will be removed in version 3.10.

struct _node* `PyParser_SimpleParseFileFlags`(FILE *fp, const char *filename, int start, int flags)

  Similar a `PyParser_SimpleParseStringFlagsFilename()`, pero el código fuente de Python se lee desde fp en lugar de una cadena de caracteres en memoria.

  Deprecated since version 3.9, will be removed in version 3.10.

PyObject* `PyRun_String`(const char *str, int start, PyObject *globals, PyObject *locals)
  Return value: New reference.

  Esta es una interfaz simplificada para `PyRun_StringFlags()` más abajo, dejando flags establecido a `NULL`.

PyObject* `PyRun_StringFlags`(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
  Return value: New reference.

  Ejecuta el código fuente de Python desde str en el contexto especificado por los objetos globals y locals con los indicadores del compilador especificados por flags. globals debe ser un diccionario; locals puede ser cualquier objeto que implemente el protocolo de mapeo. El parámetro start especifica el token de inicio que se debe usar para analizar el código fuente.

  Retorna el resultado de ejecutar el código como un objeto Python, o `NULL`” si se produjo una excepción.

PyObject* `PyRun_File`(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)
  Return value: New reference.

  Esta es una interfaz simplificada para `PyRun_FileExFlags()` más abajo, dejando closeit establecido a `0` y flags establecido a `NULL`.

PyObject* `PyRun_FileEx`(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)
  Return value: New reference.

  Esta es una interfaz simplificada para `PyRun_FileExFlags()` más abajo, dejando flags establecido a `NULL`.

PyObject* `PyRun_FileFlags`(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
  Return value: New reference.

  Esta es una interfaz simplificada para `PyRun_FileExFlags()` más abajo, dejando closeit establecido a `0`.

PyObject* `PyRun_FileExFlags`(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)
  Return value: New reference.

  Similar a `PyRun_StringFlags()`, pero el código fuente de Python se lee desde fp en lugar de una cadena de caracteres en memoria. filename debe ser el nombre del archivo, se decodifica a partir de la codificación del sistema de archivos (`sys.getfilesystemencoding()`). Si closeit es verdadero, el archivo se cierra antes que `PyRun_FileExFlags()` retorne.

PyObject* `Py_CompileString`(const char *str, const char *filename, int start)
  Return value: New reference.

  Esta es una interfaz simplificada para `Py_CompileStringFlags()` más abajo, dejando flags establecido a `NULL`.

PyObject* `Py_CompileStringFlags`(const char *str, const char *filename, int start, PyCompilerFlags *flags)
  Return value: New reference.

  Esta es una interfaz simplificada para `Py_CompileStringExFlags()` más abajo, con optimize establecido a `-1`.

PyObject* `Py_CompileStringObject`(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)
  Return value: New reference.

  Analiza gramaticalmente y compila el código fuente de Python en str, retornando el objeto de código resultante. El token de inicio viene dado por start; esto se puede usar para restringir el código que se puede compilar y debe ser `Py_eval_input`, `Py_file_input`, o `Py_single_input`. El nombre de archivo especificado por filename se usa para construir el objeto de código y puede aparecer en tracebacks o mensajes de excepción `SyntaxError`. Esto retorna `NULL`” si el código no se puede analizar gramaticalmente o compilar.

  El número entero optimize especifica el nivel de optimización del compilador; un valor de `-1` selecciona el nivel de optimización del intérprete como se indica en las opciones `-O`. Los niveles explícitos son `0` (sin optimización; `__debug__` es verdadero), `1` (los asserts se eliminan, `__debug__` es falso) o `2` (los docstrings también se eliminan) )

  Nuevo en la versión 3.4.

PyObject* `Py_CompileStringExFlags`(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)
  Return value: New reference.

  Como `Py_CompileStringObject()`, pero filename es una cadena de caracteres de byte decodificado desde la codificación del sistema de archivos (`os.fsdecode()`).

  Nuevo en la versión 3.2.

PyObject* `PyEval_EvalCode`(PyObject *co, PyObject *globals, PyObject *locals)
  Return value: New reference.

  Esta es una interfaz simplificada para `PyEval_EvalCodeEx()`, con solo el objeto de código y las variables globales y locales. Los otros argumentos están establecidos en `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.

  Evaluar un objeto de código precompilado, dado un entorno particular para su evaluación. Este entorno consta de un diccionario de variables globales, un objeto de mapeo de variables locales, arreglos de argumentos, palabras clave y valores predeterminados, un diccionario de valores predeterminados para argumentos keyword-only y una tupla de cierre de células.

`PyFrameObject`

  La estructura en C de los objetos utilizados para describir objetos del marco. Los campos de este tipo están sujetos a cambios en cualquier momento.

PyObject* `PyEval_EvalFrame`(PyFrameObject *f)
  Return value: New reference.

  Evaluar un marco de ejecución. Esta es una interfaz simplificada para `PyEval_EvalFrameEx()`, para compatibilidad con versiones anteriores.

PyObject* `PyEval_EvalFrameEx`(PyFrameObject *f, int throwflag)
  Return value: New reference.

  Esta es la función principal sin barnizar de la interpretación de Python. El objeto de código asociado con el marco de ejecución del marco f se ejecuta, interpretando el código de bytes y ejecutando llamadas según sea necesario. El parámetro adicional throwflag se puede ignorar por lo general; si es verdadero, entonces se genera una excepción de inmediato; esto se usa para los métodos `throw()` de objetos generadores.

  Distinto en la versión 3.4: Esta función ahora incluye una afirmación de depuración para ayudar a garantizar que no descarte silenciosamente una excepción activa.

int `PyEval_MergeCompilerFlags`(PyCompilerFlags *cf)

  Esta función cambia los flags del marco de evaluación actual, y retorna verdad (true) en caso de éxito, falso (false) en caso de fallo.

int `Py_eval_input`

  El símbolo de inicio de la gramática de Python para expresiones aisladas; para usar con `Py_CompileString()`.

int `Py_file_input`

  El símbolo de inicio de la gramática de Python para secuencias de declaración leídos desde un archivo u otra fuente; para usar con `Py_CompileString()`. Este es el símbolo usado cuando se compile un código fuente en Python arbitrariamente largo.

int `Py_single_input`

  El símbolo de inicio de la gramática de Python para una declaración única; para usar con `Py_CompileString()`. Este es el símbolo usado para el bucle interactivo del intérprete.

struct `PyCompilerFlags`

  Esta es la estructura usada para contener los flags del compilador. En casos donde el código es sólo compilado, es pasado como `int flags`, y en casos donde el código es ejecutado, es pasado como `PyCompilerFlags *flags`. En este caso, `from __future__ import` puede modificar los flags.

  Siempre y cuando `PyCompilerFlags *flags` es `NULL`, `cf_flags` es tratado como igual a `0`, y cualquier modificación debido a `from __future__ import` es descartada.

  int `cf_flags`

    Flags del compilador.

  int `cf_feature_version`

    cf_feature_version es la versión menor de Python. Debe ser inicializado a `PY_MINOR_VERSION`.

    El campo es ignorado por defecto, es usado si y solo si el flag `PyCF_ONLY_AST` está configurado en cf_flags.

  Distinto en la versión 3.8: Agregado el campo cf_feature_version.

int `CO_FUTURE_DIVISION`

  Este bit puede ser configurado en flags para causar que un operador de división `/` sea interpretado como una «división real» de acuerdo a PEP 238.