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.

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.

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.

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 Py_BytesMain(int argc, char **argv)

Part of the Stable ABI since version 3.8.

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

Added in version 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)

This is a simplified interface to PyRun_SimpleStringFlags() below, leaving the PyCompilerFlags* argument set to 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.

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)

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 fichero, se decodifica desde filesystem encoding and error handler. Si closeit es verdadero, el fichero 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 del manejador de codificación y errores del sistema de archivos.

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 del manejador de codificación y errores del sistema de archivos. Retorna 0 en EOF o un número negativo en caso de falla.

int (*PyOS_InputHook)(void)

Part of the Stable ABI.

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.

Distinto en la versión 3.12: This function is only called from the main interpreter.

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

Distinto en la versión 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.

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 de fp en lugar de una cadena de caracteres en memoria. filename debe ser el nombre del fichero, es decodificado desde el filesystem encoding and error handler. Si closeit es verdadero, el fichero se cierra antes de que PyRun_FileExFlags() retorne.

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

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

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.

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.

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

Added in version 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 bytes decodificada a partir del manejador de codificación y errores del sistema de archivos.

Added in version 3.2.

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

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

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. Part of the Stable ABI.

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.

PyObject *PyEval_EvalFrame(PyFrameObject *f)

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

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. Part of the Stable ABI.

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

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

Flags del compilador.

int cf_feature_version

cf_feature_version es la versión menor de Python. Debe ser inicializado a 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.

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.