pybind11: Python-Bindings für C++-Code erstellen

pybind11 ist eine leichtgewichtige, reine Header-Bibliothek für C++, mit der Sie leistungsstarke Bindings zwischen C++- und Python-Code erstellen können. Sie ist eine moderne und benutzerfreundlichere Alternative zur Boost.Python-Bibliothek. Die Grundidee: Sie schreiben eine dünne "Klebe"-Schicht in C++ mit pybind11-Makros und -Templates, die zu einer dynamischen Bibliothek (Datei .so oder .pyd) kompiliert wird. Diese Datei können Sie dann wie ein normales Modul in Python importieren.

Warum ist das nützlich? In realen Projekten müssen oft die hohe Leistung und die Low-Level-Kontrolle von C++ mit der Flexibilität und dem reichhaltigen Ökosystem von Python kombiniert werden. Sie können geschwindigkeitskritischen Code (numerische Algorithmen, Bildverarbeitung, Hardware-Zugriff) in C++ schreiben und dann bequem aus Python nutzen – ohne auf die Vorteile von Rapid Prototyping und Datenanalyse zu verzichten. pybind11 macht diesen Prozess extrem einfach und intuitiv, indem es Typkonvertierung, Speicherverwaltung und Exception-Handling automatisch übernimmt.

Die wichtigsten Vorteile von pybind11: minimaler Overhead beim Funktionsaufruf, volle Unterstützung für modernes C++ (C++11 und neuer), automatische Konvertierung von Standardcontainern (std::vector, std::map) in Python-Listen und -Dictionaries sowie ein einfaches und ausdrucksstarkes System zur Registrierung von Klassen, Methoden und Eigenschaften. Die Bibliothek wird aktiv weiterentwickelt und kommt in großen Projekten wie PyTorch, TensorFlow und Open3D zum Einsatz.

Installation

pybind11 ist eine Header-Bibliothek, daher beschränkt sich die Installation auf das Kopieren der Header-Dateien in Ihr Projekt. Der einfachste und empfohlene Weg ist die Verwendung des Paketmanagers pip, der die Bibliothek systemweit installiert und das Dienstprogramm pybind11-config für die Compiler-Pfade bereitstellt:

pip install pybind11

Nach der Installation können Sie mit folgendem Befehl prüfen, ob alles funktioniert:

pybind11-config --includes

Dieser Befehl gibt die Compiler-Flags aus, die zum Einbinden der pybind11-Header benötigt werden. Zum Kompilieren des Moduls benötigen Sie außerdem einen C++-Compiler (g++, clang, MSVC) und die Python-Header (normalerweise zusammen mit Python installiert). Beispiel für die Kompilierung mit CMake oder direkt über g++:

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

Schnellstart: Minimales funktionsfähiges Beispiel

Erstellen Sie eine Datei example.cpp mit folgendem Inhalt:

#include <pybind11/pybind11.h>

namespace py = pybind11;

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

PYBIND11_MODULE(example, m) {
    m.doc() = "pybind11 example plugin";
    m.def("add", &add, "Eine Funktion, die zwei Zahlen addiert");
}

Kompilieren Sie die Datei (ersetzen Sie python3 durch Ihren Interpreter):

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

Jetzt können Sie das Modul in Python verwenden:

import example
result = example.add(3, 4)
print(result)  # Gibt aus: 7
print(example.__doc__)  # Gibt aus: pybind11 example plugin

Wichtige Methoden und Klassen von pybind11

Im Folgenden finden Sie die wichtigsten Funktionen und Klassen der Bibliothek, die zum Erstellen von Bindings verwendet werden.

1. PYBIND11_MODULE(name, variable)

Signatur: PYBIND11_MODULE(name, variable) (Makro)

Funktion: Definiert den Einstiegspunkt für ein Python-Modul. Erstellt eine Initialisierungsfunktion, die automatisch aufgerufen wird, wenn das Modul in Python importiert wird. Der Parameter name ist der Modulname (ohne Anführungszeichen), variable ist ein Zeiger auf das py::module_-Objekt.

2. module_::def(name, func, description)

Signatur: module_ &def(const char *name, Func &&func, const char *doc = "")

Funktion: Macht eine C++-Funktion in Python verfügbar. Der erste Parameter ist der Funktionsname in Python, der zweite ein Zeiger auf die C++-Funktion (oder ein Lambda). Der optionale dritte Parameter ist ein Docstring.

3. class_<T>(module, name)

Signatur: class_<T>(handle scope, const char *name)

Funktion: Registriert eine C++-Klasse T als Python-Klasse. Ermöglicht die Definition von Konstruktoren, Methoden, Eigenschaften und statischen Methoden.