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 贡献马比尔、托马斯·米亚斯科、迪恩·莫尔多万、本·普里查德、杰森莱茵兰德、鲍里斯·谢林、皮姆·谢拉特、亨利·施赖纳、伊万·斯米尔诺夫、鲍里斯·斯塔莱克和帕特里克·斯图尔特。

我们感谢 Google 为本项目使用的持续集成基础设施提供了慷慨的财政捐助。

贡献

有关构建和贡献 pybind11 的信息，请参阅贡献指南。

执照

pybind11 是根据 BSD 风格的许可证提供的，可以在 LICENSE 文件中找到该许可证。通过使用、分发或为本项目做出贡献，您同意本许可的条款和条件。