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**.
