pybind11

pybind11 — C++11 と Python 間のシームレスな操作性

Setuptools の例 • Scikit-build の例 • CMake の例

pybind11は、主に既存の C++ コードの Python バインディングを作成するために、Python で C++ 型を公開する、またはその逆の軽量ヘッダー専用ライブラリです。その目標と構文は、David Abrahams による優れた Boost.Python ライブラリと似ており、コンパイル時のイントロスペクションを使用して型情報を推論することで、従来の拡張モジュールのボイラープレート コードを最小限に抑えます。

Boost.Python の主な問題、そしてこのような同様のプロジェクトを作成する理由は、Boost にあります。 Boost は、存在するほぼすべての C++ コンパイラで動作する、非常に大規模で複雑なユーティリティ ライブラリのスイートです。この互換性には代償が伴います。最も古くてバグの多いコンパイラサンプルをサポートするには、難解なテンプレートのトリックと回避策が必要です。 C++11 と互換性のあるコンパイラが広く利用できるようになった現在、この重い機械は過度に大きく不必要な依存関係となっています。

このライブラリは、バインディングの生成に関係のないものをすべて取り除いた、Boost.Python の小さな自己完結型バージョンと考えてください。コメントがなければ、コア ヘッダー ファイルに必要なコードは約 4,000 行だけで、Python (3.8 以降、または PyPy) と C++ 標準ライブラリに依存します。このコンパクトな実装は、いくつかの C++11 言語機能 (具体的には、タプル、ラムダ関数、および可変個引数テンプレート) のおかげで可能になりました。作成されて以来、このライブラリは多くの点で Boost.Python を超えて成長し、多くの一般的な状況でバインディング コードが劇的に単純化されました。

チュートリアルとリファレンス ドキュメントは、pybind11.readthedocs.io で提供されています。マニュアルの PDF 版はここから入手できます。また、ソース コードは github.com/pybind/pybind11 からいつでも入手できます。

コア機能

pybind11 は、次のコア C++ 機能を Python にマップできます。

• 値、参照、またはポインターごとにカスタム データ構造を受け入れ、返す関数
• インスタンスメソッドと静的メソッド
• オーバーロードされた関数
• インスタンス属性と静的属性
• 任意の例外タイプ
• 列挙
• コールバック
• イテレータと範囲
• カスタム演算子
• 単一継承と多重継承
• STLデータ構造
• std::shared_ptrのような参照カウントを備えたスマート ポインター
• 正しい参照カウントによる内部参照
• 仮想 (および純粋仮想) メソッドを備えた C++ クラスは Python で拡張できます
• 統合された NumPy サポート (NumPy 2 には pybind11 2.12+ が必要)

グッズ

核となる機能に加えて、pybind11 はいくつかの追加機能を提供します。

• Python 3.8 以降、および PyPy3 7.3 は、実装に依存しないインターフェイスでサポートされています (pybind11 2.9 は、Python 2 および 3.5 をサポートする最後のバージョンでした)。
• C++11 ラムダ関数をキャプチャされた変数にバインドすることができます。ラムダ キャプチャ データは、結果として得られる Python 関数オブジェクト内に保存されます。
• pybind11 は、カスタム データ型を効率的に転送するために、可能な限り C++11 移動コンストラクターと移動代入演算子を使用します。
• Python のバッファ プロトコルを通じてカスタム データ型の内部ストレージを公開するのは簡単です。これは、コストのかかるコピー操作を行わずに、Eigen と NumPy などの C++ 行列クラス間の高速変換などに便利です。
• pybind11 は関数を自動的にベクトル化して、1 つ以上の NumPy 配列引数のすべてのエントリに関数を透過的に適用できます。
• Python のスライスベースのアクセスおよび割り当て操作は、わずか数行のコードでサポートできます。
• すべてはわずか数個のヘッダー ファイルに含まれています。追加のライブラリに対してリンクする必要はありません。
• バイナリは通常、Boost.Python によって生成された同等のバインディングと比較して、少なくとも 2 倍小さくなります。巨大な Boost.Python バインディング プロジェクトである PyRosetta の最近の pybind11 変換では、バイナリ サイズが5.4 倍削減され、コンパイル時間が5.8 倍削減されたことが報告されました。
• 関数シグネチャはコンパイル時に ( constexpr使用して) 事前に計算されるため、バイナリが小さくなります。
• 追加の労力を少し加えるだけで、C++ 型を通常の Python オブジェクトと同様にピクル化およびアンピクル化できます。

サポートされているコンパイラ

1. Clang/LLVM 3.3 以降 (Apple Xcode の Clang の場合、これは 5.0.0 以降)
2. GCC 4.8以降
3. Microsoft Visual Studio 2017以降
4. Intel クラシック C++ コンパイラー 18 以降 (ICC 20.2 は CI でテスト済み)
5. Cygwin/GCC (以前は 2.5.1 でテスト済み)
6. NVCC (CUDA 11.0 は CI でテスト済み)
7. NVIDIA PGI (20.9 は CI でテスト済み)

について

このプロジェクトは 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 によって提供されました。マビル、トマシュ・ミエンスコ、ディーン・モルドバン、ベンプリチャード、ジェイソン・ラインランダー、ボリス・シェーリング、ピム・シェラート、ヘンリー・シュライナー、イワン・スミルノフ、ボリス・スタレティック、パトリック・スチュワート。

このプロジェクトで使用される継続的インテグレーション インフラストラクチャに対して多大な資金提供をしていただいた Google に感謝いたします。

貢献する

pybind11 の構築とコントリビュートについては、コントリビュート ガイドを参照してください。

ライセンス

pybind11 は、LICENSE ファイルにある BSD スタイルのライセンスに基づいて提供されます。このプロジェクトを使用、配布、または貢献すると、このライセンスの利用規約に同意したことになります。