pybind11

pybind11 — Fonctionnement transparent entre C++11 et Python

Exemple de setuptools • Exemple de construction Scikit • Exemple de CMake

pybind11 est une bibliothèque légère d'en-tête uniquement qui expose les types C++ en Python et vice versa, principalement pour créer des liaisons Python à partir du code C++ existant. Ses objectifs et sa syntaxe sont similaires à l'excellente bibliothèque Boost.Python de David Abrahams : minimiser le code passe-partout dans les modules d'extension traditionnels en déduisant les informations de type à l'aide de l'introspection au moment de la compilation.

Le principal problème de Boost.Python, et la raison de la création d'un projet similaire, est Boost. Boost est une suite extrêmement vaste et complexe de bibliothèques d'utilitaires qui fonctionne avec presque tous les compilateurs C++ existants. Cette compatibilité a un coût : des astuces et des solutions de contournement obscures sont nécessaires pour prendre en charge les spécimens de compilateur les plus anciens et les plus bogués. Maintenant que les compilateurs compatibles C++ 11 sont largement disponibles, cette machinerie lourde est devenue une dépendance excessivement importante et inutile.

Considérez cette bibliothèque comme une petite version autonome de Boost.Python avec tout ce qui n'est pas pertinent pour la génération de liaisons. Sans commentaires, les fichiers d'en-tête principaux ne nécessitent qu'environ 4 000 lignes de code et dépendent de Python (3.8+ ou PyPy) et de la bibliothèque standard C++. Cette implémentation compacte a été possible grâce à certaines fonctionnalités du langage C++11 (notamment : tuples, fonctions lambda et modèles variadiques). Depuis sa création, cette bibliothèque s'est développée au-delà de Boost.Python à bien des égards, conduisant à un code de liaison considérablement plus simple dans de nombreuses situations courantes.

Un didacticiel et une documentation de référence sont fournis sur pybind11.readthedocs.io. Une version PDF du manuel est disponible ici. Et le code source est toujours disponible sur github.com/pybind/pybind11.

Fonctionnalités principales

pybind11 peut mapper les fonctionnalités de base C++ suivantes à Python :

• Fonctions acceptant et renvoyant des structures de données personnalisées par valeur, référence ou pointeur
• Méthodes d'instance et méthodes statiques
• Fonctions surchargées
• Attributs d'instance et attributs statiques
• Types d'exceptions arbitraires
• Énumérations
• Rappels
• Itérateurs et plages
• Opérateurs personnalisés
• Héritage simple et multiple
• Structures de données STL
• Pointeurs intelligents avec comptage de références comme std::shared_ptr
• Références internes avec comptage de références correct
• Les classes C++ avec des méthodes virtuelles (et virtuelles pures) peuvent être étendues en Python
• Prise en charge NumPy intégrée (NumPy 2 nécessite pybind11 2.12+)

Cadeaux

En plus des fonctionnalités de base, pybind11 fournit quelques avantages supplémentaires :

• Python 3.8+ et PyPy3 7.3 sont pris en charge avec une interface indépendante de l'implémentation (pybind11 2.9 était la dernière version à prendre en charge Python 2 et 3.5).
• Il est possible de lier des fonctions lambda C++11 avec des variables capturées. Les données de capture lambda sont stockées dans l'objet fonction Python résultant.
• pybind11 utilise des constructeurs de déplacement C++ 11 et des opérateurs d'affectation de déplacement autant que possible pour transférer efficacement des types de données personnalisés.
• Il est facile d'exposer le stockage interne des types de données personnalisés via les protocoles tampon de Python. C'est pratique, par exemple, pour une conversion rapide entre des classes matricielles C++ comme Eigen et NumPy sans opérations de copie coûteuses.
• pybind11 peut automatiquement vectoriser les fonctions afin qu'elles soient appliquées de manière transparente à toutes les entrées d'un ou plusieurs arguments du tableau NumPy.
• Les opérations d'accès et d'affectation basées sur les tranches de Python peuvent être prises en charge avec seulement quelques lignes de code.
• Tout est contenu dans quelques fichiers d'en-tête ; il n'est pas nécessaire d'établir un lien avec des bibliothèques supplémentaires.
• Les binaires sont généralement plus petits d'un facteur d'au moins 2 par rapport aux liaisons équivalentes générées par Boost.Python. Une récente conversion pybind11 de PyRosetta, un énorme projet de liaison Boost.Python, a signalé une réduction de la taille binaire de 5,4x et une réduction du temps de compilation de 5,8x .
• Les signatures de fonction sont précalculées au moment de la compilation (à l'aide de constexpr ), ce qui conduit à des binaires plus petits.
• Avec peu d'effort supplémentaire, les types C++ peuvent être décapés et décapés de la même manière que les objets Python classiques.

Compilateurs pris en charge

1. Clang/LLVM 3.3 ou version ultérieure (pour le clang d'Apple Xcode, il s'agit de la version 5.0.0 ou ultérieure)
2. GCC 4.8 ou version ultérieure
3. Microsoft Visual Studio 2017 ou version ultérieure
4. Compilateur Intel Classic C++ 18 ou version ultérieure (ICC 20.2 testé en CI)
5. Cygwin/GCC (précédemment testé sur 2.5.1)
6. NVCC (CUDA 11.0 testé en CI)
7. NVIDIA PGI (20,9 testé en CI)

À propos

Ce projet a été créé par Wenzel Jakob. Des fonctionnalités et/ou améliorations importantes du code ont été apportées par Jonas Adler, Lori A. Burns, Sylvain Corlay, Eric Cousineau, Aaron Gokaslan, Ralf Grosse-Kunstleve, Trent Houliston, Axel Huebl, @hulucc, Yannick Jadoul, Sergey Lyskov, Johan. Mabille, Tomasz Miąsko, Dean Moldave, Ben Pritchard, Jason Rhinelander, Boris Schäling, Pim Schellart, Henry Schreiner, Ivan Smirnov, Boris Staletic et Patrick Stewart.

Nous remercions Google pour sa généreuse contribution financière à l'infrastructure d'intégration continue utilisée par ce projet.

Contribuer

Consultez le guide de contribution pour plus d'informations sur la création et la contribution à pybind11.

Licence

pybind11 est fourni sous une licence de style BSD qui se trouve dans le fichier LICENSE. En utilisant, distribuant ou contribuant à ce projet, vous acceptez les termes et conditions de cette licence.