pybind11: Creación de bindings de Python para código C++

pybind11 es una biblioteca ligera y exclusivamente de cabeceras para C++ que permite crear bindings de alto rendimiento entre código C++ y Python. Es una alternativa moderna y más cómoda a la biblioteca Boost.Python. La idea principal es que escribes una pequeña capa de código "pegamento" en C++ usando macros y plantillas de pybind11, que se compila en una biblioteca dinámica (archivo .so o .pyd). Luego, este archivo se puede importar en Python como un módulo normal.

¿Para qué sirve esto? En proyectos reales, a menudo surge la necesidad de combinar el alto rendimiento y el control de bajo nivel de C++ con la flexibilidad y el rico ecosistema de Python. Puedes escribir código crítico para la velocidad (algoritmos numéricos, procesamiento de imágenes, control de hardware) en C++ y luego usarlo desde Python, manteniendo la comodidad del prototipado y el análisis de datos. pybind11 hace que este proceso sea extremadamente simple e intuitivo, manejando automáticamente la conversión de tipos, la gestión de memoria y el lanzamiento de excepciones.

Ventajas clave de pybind11: sobrecarga mínima al llamar funciones, soporte completo de C++ moderno (C++11 y superior), conversión automática de contenedores estándar (std::vector, std::map) a listas y diccionarios de Python, y un sistema sencillo y expresivo para registrar clases, métodos y propiedades. La biblioteca se desarrolla activamente y se utiliza en proyectos importantes como PyTorch, TensorFlow y Open3D.

Instalación

pybind11 es una biblioteca de solo cabeceras, por lo que su instalación se reduce a copiar los archivos de cabecera en tu proyecto. La forma más sencilla y recomendada es usar el gestor de paquetes pip, que instalará la biblioteca en el sistema y proporcionará la utilidad pybind11-config para obtener las rutas de compilación:

pip install pybind11

Después de la instalación, puedes verificar que todo funciona ejecutando el comando:

pybind11-config --includes

Esto mostrará las banderas del compilador necesarias para incluir los archivos de cabecera de pybind11. Para compilar el módulo, también necesitarás un compilador de C++ (g++, clang, MSVC) y las cabeceras de Python (normalmente se instalan junto con Python). Ejemplo de compilación usando CMake o directamente con g++:

c++ -O3 -Wall -shared -std=c++11 -fPIC $(python3 -m pybind11 --includes) example.cpp -o example$(python3-config --extension-suffix)

Inicio rápido: ejemplo mínimo funcional

Crea un archivo example.cpp con el siguiente contenido:

#include <pybind11/pybind11.h>

namespace py = pybind11;

int add(int i, int j) {
    return i + j;
}

PYBIND11_MODULE(example, m) {
    m.doc() = "plugin de ejemplo pybind11";
    m.def("add", &add, "Una función que suma dos números");
}

Compílalo (reemplaza python3 con tu intérprete):

c++ -O3 -Wall -shared -std=c++11 -fPIC $(python3 -m pybind11 --includes) example.cpp -o example$(python3-config --extension-suffix)

Ahora puedes usar el módulo desde Python:

import example
resultado = example.add(3, 4)
print(resultado)  # Mostrará: 7
print(example.__doc__)  # Mostrará: plugin de ejemplo pybind11

Métodos y clases principales de pybind11

A continuación se presentan las funciones y clases clave de la biblioteca que se utilizan para crear bindings.

1. PYBIND11_MODULE(name, variable)

Firma: PYBIND11_MODULE(name, variable) (macro)

Qué hace: Define el punto de entrada para el módulo de Python. Crea una función de inicialización que se llama automáticamente cuando se importa el módulo. El primer argumento es el nombre del módulo (sin comillas) y el segundo es una variable de tipo py::module_ que se usa para registrar funciones, clases y constantes.