pybind11

pybind11 — C++11 和 Python 之間的無縫操作

安裝工具範例 • Scikit-build 範例 • CMake 範例

pybind11是一個輕量級的純頭檔庫，它在 Python 中公開 C++ 類型，反之亦然，主要是為了創建現有 C++ 程式碼的 Python 綁定。它的目標和語法類似於 David Abrahams 的優秀 Boost.Python 函式庫：透過使用編譯時自省推斷類型資訊來最小化傳統擴充模組中的樣板程式碼。

Boost.Python 的主要問題以及創建此類類似專案的原因是 Boost。 Boost 是一套非常龐大且複雜的實用程式函式庫，幾乎可以與現有的所有 C++ 編譯器配合使用。這種相容性是有代價的：需要神秘的模板技巧和解決方法來支援最古老和最有缺陷的編譯器樣本。現在，相容於 C++11 的編譯器已廣泛使用，這種重型機器已成為過大且不必要的依賴項。

將此庫視為 Boost.Python 的一個小型獨立版本，其中剝離了與綁定生成無關的所有內容。如果沒有註釋，核心頭檔只需要約 4K 行程式碼，並依賴 Python（3.8+ 或 PyPy）和 C++ 標準函式庫。這種緊湊的實作得益於一些 C++11 語言功能（特別是：元組、lambda 函式和可變參數模板）。自創建以來，該程式庫在許多方面已經超越了 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 lambda 函數與捕獲的變數綁定。 lambda 擷取資料儲存在產生的 Python 函數物件內。
• pybind11 盡可能使用 C++11 移動建構函式和移動賦值運算子來有效地傳輸自訂資料型別。
• 透過 Python 的緩衝區協定可以輕鬆公開自訂資料類型的內部儲存。這對於例如 Eigen 和 NumPy 等 C++ 矩陣類別之間的快速轉換非常方便，無需昂貴的複製操作。
• pybind11 可以自動向量化函數，以便它們透明地應用於一個或多個 NumPy 陣列參數的所有條目。
• 只需幾行程式碼即可支援Python基於切片的存取和賦值操作。
• 所有內容都包含在幾個頭檔中；無需鏈接任何其他庫。
• 與 Boost.Python 產生的等效綁定相比，二進位檔案通常至少小 2 倍。 PyRosetta（一個巨大的 Boost.Python 綁定專案）最近的 pybind11 轉換報告二進位大小減少了5.4 倍，編譯時間減少了5.8 倍。
• 函數簽章在編譯時預先計算（使用constexpr ），從而產生更小的二進位。
• 只需很少的額外努力，C++ 類型就可以像常規 Python 物件一樣進行 pickle 和 unpickle。

支援的編譯器

1. Clang/LLVM 3.3 或更高版本（對於 Apple Xcode 的 clang，這是 5.0.0 或更高版本）
2. GCC 4.8 或更高版本
3. Microsoft Visual Studio 2017 或更高版本
4. Intel 經典 C++ 編譯器 18 或更高版本（在 CI 中測試 ICC 20.2）
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 貢獻Mabille、Johan Tomasz Miąsko、Dean Moldovan、Ben Pritchard、Jason Rhinelander、Boris Schäling、Pim Schellart、Henry Schreiner、Ivan Smirnov、Boris Staletic 和Patrick Stewart。

我們感謝 Google 為本計畫使用的持續整合基礎設施提供了慷慨的財政捐助。

貢獻

有關構建和貢獻 pybind11 的信息，請參閱貢獻指南。

執照

pybind11 是根據 BSD 風格的許可證提供的，可以在 LICENSE 文件中找到該許可證。透過使用、散佈或為本項目做出貢獻，您同意本授權的條款和條件。