pybind11

pybind11 – Nahtlose Bedienbarkeit zwischen C++11 und Python

Setuptools-Beispiel • Scikit-Build-Beispiel • CMake-Beispiel

pybind11 ist eine leichte Header-Bibliothek, die C++-Typen in Python und umgekehrt verfügbar macht, hauptsächlich um Python-Bindungen für vorhandenen C++-Code zu erstellen. Seine Ziele und Syntax ähneln der hervorragenden Boost.Python-Bibliothek von David Abrahams: Minimierung des Boilerplate-Codes in herkömmlichen Erweiterungsmodulen durch Ableitung von Typinformationen mithilfe der Introspektion zur Kompilierungszeit.

Das Hauptproblem bei Boost.Python – und der Grund für die Erstellung eines so ähnlichen Projekts – ist Boost. Boost ist eine enorm große und komplexe Suite von Dienstprogrammbibliotheken, die mit fast jedem existierenden C++-Compiler funktioniert. Diese Kompatibilität hat ihren Preis: Um die ältesten und fehlerhaftesten Compiler-Exemplare zu unterstützen, sind obskure Template-Tricks und Workarounds erforderlich. Da C++11-kompatible Compiler nun allgemein verfügbar sind, ist diese schwere Maschinerie zu einer übermäßig großen und unnötigen Abhängigkeit geworden.

Stellen Sie sich diese Bibliothek als eine winzige, eigenständige Version von Boost.Python vor, in der alles entfernt wurde, was für die Bindungsgenerierung nicht relevant ist. Ohne Kommentare erfordern die Kern-Header-Dateien nur ca. 4 KB Codezeilen und hängen von Python (3.8+ oder PyPy) und der C++-Standardbibliothek ab. Diese kompakte Implementierung war dank einiger C++11-Sprachfunktionen möglich (insbesondere: Tupel, Lambda-Funktionen und Variadic-Vorlagen). Seit ihrer Erstellung ist diese Bibliothek in vielerlei Hinsicht über Boost.Python hinaus gewachsen und hat in vielen gängigen Situationen zu deutlich einfacherem Bindungscode geführt.

Tutorial- und Referenzdokumentation finden Sie unter pybind11.readthedocs.io. Eine PDF-Version des Handbuchs finden Sie hier. Und der Quellcode ist immer unter github.com/pybind/pybind11 verfügbar.

Kernfunktionen

pybind11 kann Python die folgenden Kernfunktionen von C++ zuordnen:

• Funktionen, die benutzerdefinierte Datenstrukturen pro Wert, Referenz oder Zeiger akzeptieren und zurückgeben
• Instanzmethoden und statische Methoden
• Überlastete Funktionen
• Instanzattribute und statische Attribute
• Beliebige Ausnahmetypen
• Aufzählungen
• Rückrufe
• Iteratoren und Bereiche
• Benutzerdefinierte Operatoren
• Einfache und mehrfache Vererbung
• STL-Datenstrukturen
• Intelligente Zeiger mit Referenzzählung wie std::shared_ptr
• Interne Referenzen mit korrekter Referenzzählung
• C++-Klassen mit virtuellen (und rein virtuellen) Methoden können in Python erweitert werden
• Integrierte NumPy-Unterstützung (NumPy 2 erfordert pybind11 2.12+)

Leckereien

Zusätzlich zur Kernfunktionalität bietet pybind11 einige zusätzliche Extras:

• Python 3.8+ und PyPy3 7.3 werden mit einer implementierten unabhängigen Schnittstelle unterstützt (pybind11 2.9 war die letzte Version, die Python 2 und 3.5 unterstützte).
• Es ist möglich, C++11-Lambda-Funktionen mit erfassten Variablen zu binden. Die Lambda-Erfassungsdaten werden im resultierenden Python-Funktionsobjekt gespeichert.
• pybind11 verwendet wann immer möglich C++11-Verschiebungskonstruktoren und Verschiebungszuweisungsoperatoren, um benutzerdefinierte Datentypen effizient zu übertragen.
• Es ist einfach, den internen Speicher benutzerdefinierter Datentypen über die Pufferprotokolle von Pythons verfügbar zu machen. Dies ist beispielsweise für eine schnelle Konvertierung zwischen C++-Matrixklassen wie Eigen und NumPy ohne teure Kopiervorgänge praktisch.
• pybind11 kann Funktionen automatisch vektorisieren, sodass sie transparent auf alle Einträge eines oder mehrerer NumPy-Array-Argumente angewendet werden.
• Die Slice-basierten Zugriffs- und Zuweisungsvorgänge von Python können mit nur wenigen Codezeilen unterstützt werden.
• Alles ist in nur wenigen Header-Dateien enthalten; Es ist nicht erforderlich, eine Verknüpfung mit weiteren Bibliotheken herzustellen.
• Binärdateien sind im Allgemeinen um mindestens den Faktor 2 kleiner im Vergleich zu entsprechenden, von Boost.Python generierten Bindungen. Eine kürzlich durchgeführte pybind11-Konvertierung von PyRosetta, einem riesigen Boost.Python-Bindungsprojekt, ergab eine Reduzierung der Binärgröße um das 5,4-fache und eine Reduzierung der Kompilierungszeit um das 5,8-fache .
• Funktionssignaturen werden zur Kompilierzeit vorberechnet (mit constexpr ), was zu kleineren Binärdateien führt.
• Mit wenig zusätzlichem Aufwand können C++-Typen ähnlich wie normale Python-Objekte ausgewählt und entpickt werden.

Unterstützte Compiler

1. Clang/LLVM 3.3 oder neuer (für Apple Xcodes Clang ist dies 5.0.0 oder neuer)
2. GCC 4.8 oder neuer
3. Microsoft Visual Studio 2017 oder neuer
4. Intel Classic C++ Compiler 18 oder neuer (ICC 20.2 in CI getestet)
5. Cygwin/GCC (zuvor auf 2.5.1 getestet)
6. NVCC (CUDA 11.0 getestet in CI)
7. NVIDIA PGI (20,9 getestet in CI)

Um

Dieses Projekt wurde von Wenzel Jakob erstellt. Wesentliche Funktionen und/oder Verbesserungen des Codes wurden von Jonas Adler, Lori A. Burns, Sylvain Corlay, Eric Cousineau, Aaron Gokaslan, Ralf Grosse-Kunstleve, Trent Houliston, Axel Huebl, @hulucc, Yannick Jadoul, Sergey Lyskov und Johan beigesteuert Mabille, Tomasz Miąsko, Dean Moldovan, Ben Pritchard, Jason Rhinelander, Boris Schäling, Pim Schellart, Henry Schreiner, Ivan Smirnov, Boris Staletic und Patrick Stewart.

Wir danken Google für einen großzügigen finanziellen Beitrag zur kontinuierlichen Integrationsinfrastruktur, die von diesem Projekt verwendet wird.

Mitwirken

Informationen zum Erstellen und Mitwirken an pybind11 finden Sie im Beitragsleitfaden.

Lizenz

pybind11 wird unter einer BSD-ähnlichen Lizenz bereitgestellt, die in der LICENSE-Datei zu finden ist. Durch die Nutzung, Verbreitung oder Mitwirkung an diesem Projekt stimmen Sie den Bedingungen dieser Lizenz zu.