pybind11

pybind11: operabilidad perfecta entre C++ 11 y Python

Ejemplo de herramientas de configuración • Ejemplo de compilación de Scikit • Ejemplo de CMake

pybind11 es una biblioteca liviana de solo encabezados que expone tipos de C++ en Python y viceversa, principalmente para crear enlaces de Python de código C++ existente. Sus objetivos y sintaxis son similares a los de la excelente biblioteca Boost.Python de David Abrahams: minimizar el código repetitivo en módulos de extensión tradicionales infiriendo información de tipo mediante introspección en tiempo de compilación.

El principal problema con Boost.Python (y la razón para crear un proyecto similar) es Boost. Boost es un conjunto enormemente grande y complejo de bibliotecas de utilidades que funciona con casi todos los compiladores de C++ que existen. Esta compatibilidad tiene su costo: se necesitan trucos arcanos de plantillas y soluciones alternativas para admitir los compiladores más antiguos y con más errores. Ahora que los compiladores compatibles con C++ 11 están ampliamente disponibles, esta maquinaria pesada se ha convertido en una dependencia excesivamente grande e innecesaria.

Piense en esta biblioteca como una pequeña versión autónoma de Boost.Python sin todo lo que no es relevante para la generación de enlaces. Sin comentarios, los archivos de encabezado principales solo requieren ~4K líneas de código y dependen de Python (3.8+ o PyPy) y la biblioteca estándar C++. Esta implementación compacta fue posible gracias a algunas características del lenguaje C++ 11 (específicamente: tuplas, funciones lambda y plantillas variadas). Desde su creación, esta biblioteca ha crecido más allá de Boost.Python en muchos sentidos, lo que ha llevado a un código vinculante mucho más simple en muchas situaciones comunes.

La documentación de referencia y tutorial se proporciona en pybind11.readthedocs.io. Una versión PDF del manual está disponible aquí. Y el código fuente siempre está disponible en github.com/pybind/pybind11.

Características principales

pybind11 puede asignar las siguientes características principales de C++ a Python:

• Funciones que aceptan y devuelven estructuras de datos personalizadas por valor, referencia o puntero
• Métodos de instancia y métodos estáticos.
• Funciones sobrecargadas
• Atributos de instancia y atributos estáticos
• Tipos de excepciones arbitrarias
• Enumeraciones
• Devoluciones de llamada
• Iteradores y rangos
• Operadores personalizados
• Herencia única y múltiple
• Estructuras de datos STL
• Punteros inteligentes con recuento de referencias como std::shared_ptr
• Referencias internas con recuento de referencias correcto.
• Las clases de C++ con métodos virtuales (y virtuales puros) se pueden ampliar en Python
• Soporte integrado de NumPy (NumPy 2 requiere pybind11 2.12+)

golosinas

Además de la funcionalidad principal, pybind11 proporciona algunas ventajas adicionales:

• Python 3.8+ y PyPy3 7.3 son compatibles con una interfaz independiente de la implementación (pybind11 2.9 fue la última versión compatible con Python 2 y 3.5).
• Es posible vincular funciones lambda de C++ 11 con variables capturadas. Los datos de captura lambda se almacenan dentro del objeto de función Python resultante.
• pybind11 utiliza constructores de movimiento C++11 y operadores de asignación de movimiento siempre que sea posible para transferir de manera eficiente tipos de datos personalizados.
• Es fácil exponer el almacenamiento interno de tipos de datos personalizados a través de los protocolos de búfer de Python. Esto es útil, por ejemplo, para una conversión rápida entre clases matriciales de C++ como Eigen y NumPy sin costosas operaciones de copia.
• pybind11 puede vectorizar funciones automáticamente para que se apliquen de forma transparente a todas las entradas de uno o más argumentos de la matriz NumPy.
• Las operaciones de asignación y acceso basadas en sectores de Python se pueden admitir con solo unas pocas líneas de código.
• Todo está contenido en unos pocos archivos de encabezado; no es necesario vincular ninguna biblioteca adicional.
• Los archivos binarios generalmente son más pequeños en un factor de al menos 2 en comparación con los enlaces equivalentes generados por Boost.Python. Una conversión reciente de pybind11 de PyRosetta, un enorme proyecto de enlace Boost.Python, informó una reducción del tamaño binario de 5,4x y una reducción del tiempo de compilación de 5,8x .
• Las firmas de funciones se calculan previamente en tiempo de compilación (usando constexpr ), lo que genera archivos binarios más pequeños.
• Con un poco de esfuerzo adicional, los tipos de C++ se pueden seleccionar y deseleccionar de manera similar a los objetos normales de Python.

Compiladores compatibles

1. Clang/LLVM 3.3 o posterior (para clang de Apple Xcode, esta es 5.0.0 o posterior)
2. GCC 4.8 o más reciente
3. Microsoft Visual Studio 2017 o más reciente
4. Compilador Intel Classic C++ 18 o posterior (ICC 20.2 probado en CI)
5. Cygwin/GCC (probado previamente en 2.5.1)
6. NVCC (CUDA 11.0 probado en CI)
7. NVIDIA PGI (20.9 probado en CI)

Acerca de

Este proyecto fue creado por Wenzel Jakob. Jonas Adler, Lori A. Burns, Sylvain Corlay, Eric Cousineau, Aaron Gokaslan, Ralf Grosse-Kunstleve, Trent Houliston, Axel Huebl, @hulucc, Yannick Jadoul, Sergey Lyskov, Johan contribuyeron con importantes características y/o mejoras al código. Mabille, Tomasz Miąsko, Dean Moldovan, Ben Pritchard, Jason Rhinelander, Boris Schäling, Pim Schellart, Henry Schreiner, Ivan Smirnov, Boris Staletic y Patrick Stewart.

Agradecemos a Google por su generosa contribución financiera a la infraestructura de integración continua utilizada por este proyecto.

Contribuyendo

Consulte la guía de contribución para obtener información sobre cómo crear y contribuir a pybind11.

Licencia

pybind11 se proporciona bajo una licencia estilo BSD que se puede encontrar en el archivo LICENCIA. Al usar, distribuir o contribuir a este proyecto, acepta los términos y condiciones de esta licencia.