C++编写Python扩展，Pybind11实战教程

Pybind11是目前最简洁高效的C++编写Python扩展模块的工具，通过极少量代码即可将C++函数、类、STL容器等暴露给Python。使用PYBIND11_MODULE定义模块，m.def()导出函数，py::class_封装类，配合#include 实现vector、map等自动转换。通过CMake构建生成.so或.pyd文件后，可在Python中如原生模块般调用，显著提升性能，适用于算法加速与C++项目集成。

要用C++编写Python扩展模块，Pybind11 是目前最简洁高效的工具之一。它允许你用极少量的C++代码将C++类、函数、对象暴露给Python，实现高性能混合编程。相比传统的 Python C API 或 Boost.Python，Pybind11 更轻量、易用且功能强大。

安装 Pybind11

Pybind11 可以通过 pip 安装，也可以作为头文件直接集成到项目中：

安装后，你可以包含其头文件来使用。如果你使用 CMake，推荐方式是通过 find_package(pybind11) 集成。

编写第一个 C++ 扩展模块

下面是一个简单的例子，将一个 C++ 函数导出为 Python 模块：

example.cpp:

#include 
int add(int a, int b) {
return a + b;
}
namespace py = pybind11;
PYBIND11_MODULE(example, m) {
m.doc() = "pybind11 example plugin";
m.def("add", &add, "A function that adds two numbers");
}

这里：
- PYBIND11_MODULE 定义了一个名为 example 的 Python 模块。
- m.def() 将 C++ 函数 add 绑定为 Python 可调用函数。

编译生成 Python 模块

有几种方式可以编译这个模块。最简单的是使用 pybind11 提供的工具链。

使用 CMake 编译（推荐）：

CMakeLists.txt:

cmake_minimum_required(VERSION 3.10)
project(example)
find_package(pybind11 REQUIRED)
pybind11_add_module(example example.cpp)

然后执行：

成功后会生成 example.cpython-xxx.so（Linux）或 example.pyd（Windows），可在 Python 中直接 import。

在 Python 中使用扩展模块

编译完成后，在 Python 中像普通模块一样导入：

import example
print(example.add(3, 4))  # 输出: 7

你会发现这个函数和原生 Python 函数一样调用自然，但底层是 C++ 实现，性能更高。

导出 C++ 类到 Python

Pybind11 支持完整封装 C++ 类。例如：

#include 
class MyClass {
public:
MyClass(const std::string &name) : name(name) {}
void set_name(const std::string &n) { name = n; }
std::string get_name() const { return name; }
private:
std::string name;
};
namespace py = pybind11;
PYBIND11MODULE(example, m) {
py::class(m, "MyClass")
.def(py::init())
.def("set_name", &MyClass::set_name)
.def("get_name", &MyClass::get_name);
}

在 Python 中使用：

obj = example.MyClass("test")
print(obj.get_name())  # 输出: test
obj.set_name("hello")
print(obj.get_name())  # 输出: hello

构造函数、成员方法都可直接绑定，支持重载、属性访问等高级特性。

处理复杂类型与 STL 容器

Pybind11 支持自动转换常见 STL 类型。需包含对应头文件：

#include 

之后，C++ 的 std::vector、std::string、std::map 等会自动转换为 Python 的 list、str、dict。

例如：

std::vector get_numbers() {
    return {1, 2, 3, 4};
}
m.def("get_numbers", &get_numbers);

Python 调用时返回的就是 list。

基本上就这些。Pybind11 让 C++ 与 Python 混合编程变得非常直观。只要写好 C++ 逻辑，几行绑定代码就能在 Python 中高速调用，适合算法加速、接口封装、已有 C++ 项目集成等场景。