pybind11：为 C++ 代码创建 Python 绑定

pybind11 是一个轻量级、纯头文件的 C++ 库，用于在 C++ 和 Python 之间创建高性能的绑定（bindings）。它是 Boost.Python 库的现代且更易用的替代方案。核心思想是：您使用 pybind11 的宏和模板编写一小段 C++“胶水”代码，将其编译为动态库（.so 或 .pyd 文件），然后就可以像普通 Python 模块一样导入使用。

为什么要这么做？在实际项目中，我们常常需要将 C++ 的高性能、底层控制能力与 Python 的灵活性、丰富生态结合起来。您可以用 C++ 编写对速度要求极高的代码（如数值算法、图像处理、硬件交互），然后在 Python 中调用，同时保留原型设计和数据分析的便利性。pybind11 让这一过程变得极其简单直观，自动处理类型转换、内存管理和异常调用。

pybind11 的核心优势：函数调用开销极低（overhead 极小）、全面支持现代 C++（C++11 及以上）、自动将标准容器（如 std::vector、std::map）转换为 Python 列表和字典，以及简洁易用的类、方法和属性注册系统。该库正在积极开发中，并被 PyTorch、TensorFlow 和 Open3D 等大型项目所采用。

安装

pybind11 是一个头文件库，因此安装只需将头文件复制到您的项目中。最简单且推荐的方式是使用 pip 包管理器，它会将库安装到系统中，并提供 pybind11-config 工具来获取编译路径：

pip install pybind11

安装后，您可以运行以下命令验证是否成功：

pybind11-config --includes

该命令会输出编译所需的编译器标志，用于包含 pybind11 头文件。编译模块还需要 C++ 编译器（g++、clang、MSVC）和 Python 头文件（通常随 Python 一起安装）。以下是使用 CMake 或直接通过 g++ 编译的示例：

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

快速入门：最小工作示例

创建一个名为 example.cpp 的文件，内容如下：

#include <pybind11/pybind11.h>

namespace py = pybind11;

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

PYBIND11_MODULE(example, m) {
    m.doc() = "pybind11 示例插件";
    m.def("add", &add, "一个将两个数相加的函数");
}

编译它（将 python3 替换为您的解释器）：

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

现在您可以在 Python 中使用该模块：

import example
result = example.add(3, 4)
print(result)  # 输出：7
print(example.__doc__)  # 输出：pybind11 示例插件

pybind11 核心方法与类

以下是用于创建绑定的关键函数和类。

1. PYBIND11_MODULE(name, variable)

签名： PYBIND11_MODULE(name, variable)（宏）

功能： 定义 Python 模块的入口点。创建一个初始化函数，该函数会在 Python 导入模块时自动调用。