# Incrustando Python en otra aplicación

Los capítulos anteriores discutieron cómo extender Python, es decir, cómo extender la funcionalidad de Python al adjuntarle una biblioteca de funciones C. También es posible hacerlo al revés: enriquezca su aplicación C/C++ incrustando Python en ella. La incrustación proporciona a su aplicación la capacidad de implementar parte de la funcionalidad de su aplicación en Python en lugar de C o C++. Esto se puede usar para muchos propósitos; Un ejemplo sería permitir a los usuarios adaptar la aplicación a sus necesidades escribiendo algunos scripts en Python. También puede usarlo usted mismo si parte de la funcionalidad se puede escribir en Python más fácilmente.

Incrustar Python es similar a extenderlo, pero no del todo. La diferencia es que cuando extiende Python, el programa principal de la aplicación sigue siendo el intérprete de Python, mientras que si incrusta Python, el programa principal puede no tener nada que ver con Python — en cambio, algunas partes de la aplicación ocasionalmente llaman al Intérprete de Python para ejecutar algún código de Python.

Entonces, si está incrustando Python, está proporcionando su propio programa principal. Una de las cosas que tiene que hacer este programa principal es inicializar el intérprete de Python. Como mínimo, debe llamar a la función `Py_Initialize()`. Hay llamadas opcionales para pasar argumentos de línea de comandos a Python. Luego, puede llamar al intérprete desde cualquier parte de la aplicación.

Hay varias formas diferentes de llamar al intérprete: puede pasar una cadena que contiene declaraciones de Python a `PyRun_SimpleString()`, o puede pasar un puntero de archivo estándar y un nombre de archivo (solo para identificación en mensajes de error) a `PyRun_SimpleFile()`. También puede llamar a las operaciones de nivel inferior descritas en los capítulos anteriores para construir y usar objetos de Python.

Ver también

Python/C API reference manual

  Los detalles de la interfaz C de Python se dan en este manual. Una gran cantidad de información necesaria se puede encontrar aquí.

## Incrustación de muy alto nivel

La forma más simple de incrustar Python es el uso de la interfaz de muy alto nivel. Esta interfaz está diseñada para ejecutar un script de Python sin necesidad de interactuar directamente con la aplicación. Esto puede usarse, por ejemplo, para realizar alguna operación en un archivo.

    #define PY_SSIZE_T_CLEAN
    #include <Python.h>

    int
    main(int argc, char *argv[])
    {
        PyStatus status;
        PyConfig config;
        PyConfig_InitPythonConfig(&config);

        /* optional but recommended */
        status = PyConfig_SetBytesString(&config, &config.program_name, argv[0]);
        if (PyStatus_Exception(status)) {
            goto exception;
        }

        status = Py_InitializeFromConfig(&config);
        if (PyStatus_Exception(status)) {
            goto exception;
        }
        PyConfig_Clear(&config);

        PyRun_SimpleString("from time import time,ctime\n"
                           "print('Today is', ctime(time()))\n");
        if (Py_FinalizeEx() < 0) {
            exit(120);
        }
        return 0;

      exception:
         PyConfig_Clear(&config);
         Py_ExitStatusException(status);
    }

Nota

`#define PY_SSIZE_T_CLEAN` se usaba para indicar que `Py_ssize_t` debería usarse en algunas APIs en lugar de `int`. No es necesario desde Python 3.13, pero lo mantenemos aquí por compatibilidad. Ver Cadena de caracteres y búferes para una descripción de esta macro.

La configuración `PyConfig.program_name` debe llamarse antes de `Py_InitializeFromConfig()` para informar al intérprete sobre las rutas a las bibliotecas de tiempo de ejecución de Python. A continuación, el intérprete de Python se inicializa con `Py_Initialize()`, seguido de la ejecución de un script Python codificado que imprime la fecha y la hora. Luego, la llamada `Py_FinalizeEx()` cierra el intérprete, seguido por el final del programa. En un programa real, es posible que desee obtener el script de Python de otra fuente, tal vez una rutina de editor de texto, un archivo o una base de datos. Obtener el código Python de un archivo se puede hacer mejor usando la función `PyRun_SimpleFile()`, que le ahorra la molestia de asignar espacio de memoria y cargar el contenido del archivo.

## Más allá de la incrustación de muy alto nivel: una visión general

La interfaz de alto nivel le permite ejecutar piezas arbitrarias de código Python desde su aplicación, pero el intercambio de valores de datos es bastante engorroso, por decir lo menos. Si lo desea, debe usar llamadas de nivel inferior. A costa de tener que escribir más código C, puede lograr casi cualquier cosa.

Cabe señalar que extender Python e incrustar Python es la misma actividad, a pesar de la intención diferente. La mayoría de los temas tratados en los capítulos anteriores siguen siendo válidos. Para mostrar esto, considere lo que realmente hace el código de extensión de Python a C:

1. Convierte valores de datos de Python a C,

2. Realice una llamada de función a una rutina C usando los valores convertidos, y

3. Convierte los valores de datos de la llamada de C a Python.

Al incrustar Python, el código de interfaz hace:

1. Convierte valores de datos de C a Python,

2. Realice una llamada de función a una rutina de interfaz de Python utilizando los valores convertidos, y

3. Convierte los valores de datos de la llamada de Python a C.

Como puede ver, los pasos de conversión de datos simplemente se intercambian para acomodar la dirección diferente de la transferencia de idiomas cruzados. La única diferencia es la rutina que llama entre ambas conversiones de datos. Al extender, llama a una rutina C, al incrustar, llama a una rutina Python.

Este capítulo no discutirá cómo convertir datos de Python a C y viceversa. Además, se supone que se entiende el uso adecuado de las referencias y el tratamiento de errores. Dado que estos aspectos no difieren de extender el intérprete, puede consultar los capítulos anteriores para obtener la información requerida.

## Incrustación pura

El primer programa tiene como objetivo ejecutar una función en un script Python. Al igual que en la sección sobre la interfaz de muy alto nivel, el intérprete de Python no interactúa directamente con la aplicación (pero eso cambiará en la siguiente sección).

El código para ejecutar una función definida en un script de Python es:

    #define PY_SSIZE_T_CLEAN
    #include <Python.h>

    int
    main(int argc, char *argv[])
    {
        PyObject *pName, *pModule, *pFunc;
        PyObject *pArgs, *pValue;
        int i;

        if (argc < 3) {
            fprintf(stderr,"Usage: call pythonfile funcname [args]\n");
            return 1;
        }

        Py_Initialize();
        pName = PyUnicode_DecodeFSDefault(argv[1]);
        /* Error checking of pName left out */

        pModule = PyImport_Import(pName);
        Py_DECREF(pName);

        if (pModule != NULL) {
            pFunc = PyObject_GetAttrString(pModule, argv[2]);
            /* pFunc is a new reference */

            if (pFunc && PyCallable_Check(pFunc)) {
                pArgs = PyTuple_New(argc - 3);
                for (i = 0; i < argc - 3; ++i) {
                    pValue = PyLong_FromLong(atoi(argv[i + 3]));
                    if (!pValue) {
                        Py_DECREF(pArgs);
                        Py_DECREF(pModule);
                        fprintf(stderr, "Cannot convert argument\n");
                        return 1;
                    }
                    /* pValue reference stolen here: */
                    PyTuple_SetItem(pArgs, i, pValue);
                }
                pValue = PyObject_CallObject(pFunc, pArgs);
                Py_DECREF(pArgs);
                if (pValue != NULL) {
                    printf("Result of call: %ld\n", PyLong_AsLong(pValue));
                    Py_DECREF(pValue);
                }
                else {
                    Py_DECREF(pFunc);
                    Py_DECREF(pModule);
                    PyErr_Print();
                    fprintf(stderr,"Call failed\n");
                    return 1;
                }
            }
            else {
                if (PyErr_Occurred())
                    PyErr_Print();
                fprintf(stderr, "Cannot find function \"%s\"\n", argv[2]);
            }
            Py_XDECREF(pFunc);
            Py_DECREF(pModule);
        }
        else {
            PyErr_Print();
            fprintf(stderr, "Failed to load \"%s\"\n", argv[1]);
            return 1;
        }
        if (Py_FinalizeEx() < 0) {
            return 120;
        }
        return 0;
    }

Este código carga un script de Python usando `argv[1]` y llama a la función nombrada en `argv[2]`. Sus argumentos enteros son los otros valores del arreglo `argv`. Si usted compila y enlaza este programa (llamemos al ejecutable terminado call), y úselo para ejecutar un script Python, como:

    def multiply(a,b):
        print("Will compute", a, "times", b)
        c = 0
        for i in range(0, a):
            c = c + b
        return c

entonces el resultado debería ser:

    $ call multiply multiply 3 2
    Will compute 3 times 2
    Result of call: 6

Aunque el programa es bastante grande por su funcionalidad, la mayor parte del código es para la conversión de datos entre Python y C, y para informes de errores. La parte interesante con respecto a incrustar Python comienza con:

    Py_Initialize();
    pName = PyUnicode_DecodeFSDefault(argv[1]);
    /* Error checking of pName left out */
    pModule = PyImport_Import(pName);

After initializing the interpreter, the script is loaded using `PyImport_Import()`. This routine needs a Python string as its argument, which is constructed using the `PyUnicode_DecodeFSDefault()` data conversion routine.

    pFunc = PyObject_GetAttrString(pModule, argv[2]);
    /* pFunc is a new reference */

    if (pFunc && PyCallable_Check(pFunc)) {
        ...
    }
    Py_XDECREF(pFunc);

Una vez que se carga el script, el nombre que estamos buscando se recupera usando `PyObject_GetAttrString()`. Si el nombre existe y el objeto retornado es invocable, puede asumir con seguridad que es una función. Luego, el programa continúa construyendo una tupla de argumentos como de costumbre. La llamada a la función Python se realiza con:

    pValue = PyObject_CallObject(pFunc, pArgs);

Al regresar la función, `pValue` es `NULL` o contiene una referencia al valor de retorno de la función. Asegúrese de liberar la referencia después de examinar el valor.

## Extendiendo Python incrustado

Hasta ahora, el intérprete de Python incorporado no tenía acceso a la funcionalidad de la aplicación misma. La API de Python lo permite al extender el intérprete incorporado. Es decir, el intérprete incorporado se amplía con las rutinas proporcionadas por la aplicación. Si bien suena complejo, no es tan malo. Simplemente olvide por un momento que la aplicación inicia el intérprete de Python. En cambio, considere que la aplicación es un conjunto de subrutinas y escriba un código de pegamento que le otorgue a Python acceso a esas rutinas, al igual que escribiría una extensión normal de Python. Por ejemplo:

    static int numargs=0;

    /* Return the number of arguments of the application command line */
    static PyObject*
    emb_numargs(PyObject *self, PyObject *args)
    {
        if(!PyArg_ParseTuple(args, ":numargs"))
            return NULL;
        return PyLong_FromLong(numargs);
    }

    static PyMethodDef emb_module_methods[] = {
        {"numargs", emb_numargs, METH_VARARGS,
         "Return the number of arguments received by the process."},
        {NULL, NULL, 0, NULL}
    };

    static struct PyModuleDef emb_module = {
        .m_base = PyModuleDef_HEAD_INIT,
        .m_name = "emb",
        .m_size = 0,
        .m_methods = emb_module_methods,
    };

    static PyObject*
    PyInit_emb(void)
    {
        return PyModuleDef_Init(&emb_module);
    }

Inserte el código anterior justo encima de la función `main()`. Además, inserte las siguientes dos declaraciones antes de la llamada a `Py_Initialize()`:

    numargs = argc;
    PyImport_AppendInittab("emb", &PyInit_emb);

Estas dos líneas inicializan la variable `numargs` y hacen que la función `emb.numargs()` sea accesible para el intérprete de Python incorporado. Con estas extensiones, el script de Python puede hacer cosas como

    import emb
    print("Number of arguments", emb.numargs())

En una aplicación real, los métodos expondrán una API de la aplicación a Python.

## Incrustando Python en C++

También es posible incrustar Python en un programa C++; precisamente cómo se hace esto dependerá de los detalles del sistema C++ utilizado; en general, necesitará escribir el programa principal en C++ y usar el compilador de C++ para compilar y vincular su programa. No es necesario volver a compilar Python usando C++.

## Compilar y enlazar bajo sistemas tipo Unix

No es necesariamente trivial encontrar los indicadores correctos para pasar a su compilador (y enlazador) para incrustar el intérprete de Python en su aplicación, particularmente porque Python necesita cargar módulos de biblioteca implementados como extensiones dinámicas en C (archivos `.so`) enlazados en su contra.

Para conocer los indicadores necesarios del compilador y el enlazador, puede ejecutar el script `pythonX.Y-config` que se genera como parte del proceso de instalación (también puede estar disponible un script `python3-config` ) Este script tiene varias opciones, de las cuales las siguientes serán directamente útiles para usted:

- `pythonX.Y-config --cflags` le dará las banderas recomendadas al compilar:

      $ /opt/bin/python3.11-config --cflags
      -I/opt/include/python3.11 -I/opt/include/python3.11 -Wsign-compare  -DNDEBUG -g -fwrapv -O3 -Wall

- `pythonX.Y-config --ldflags --embed` le dará las banderas recomendadas al vincular:

      $ /opt/bin/python3.11-config --ldflags --embed
      -L/opt/lib/python3.11/config-3.11-x86_64-linux-gnu -L/opt/lib -lpython3.11 -lpthread -ldl  -lutil -lm

Nota

Para evitar confusiones entre varias instalaciones de Python (y especialmente entre el sistema Python y su propio Python compilado), se recomienda que use la ruta absoluta a `pythonX.Y-config`, como en el ejemplo anterior.

Si este procedimiento no funciona para usted (no se garantiza que funcione para todas las plataformas tipo Unix; sin embargo, le damos la bienvenida informes de errores) deberá leer la documentación de su sistema sobre dinámica vincular o examinar Python `Makefile` (use `sysconfig.get_makefile_filename()` para encontrar su ubicación) y las opciones de compilación. En este caso, el módulo `sysconfig` es una herramienta útil para extraer mediante programación los valores de configuración que querrá combinar. Por ejemplo:

    >>> import sysconfig
    >>> sysconfig.get_config_var('LIBS')
    '-lpthread -ldl  -lutil'
    >>> sysconfig.get_config_var('LINKFORSHARED')
    '-Xlinker -export-dynamic'