pybind11 使用教程

项目介绍

pybind11 是一个轻量级的头文件库，旨在实现 C++ 和 Python 之间的无缝操作。它主要用于创建现有 C++ 代码的 Python 绑定。pybind11 的目标和语法与 Boost.Python 库类似，但它的实现更为简洁，不需要链接复杂的 Boost 库。pybind11 支持 Python 3.8+ 和 PyPy3.7+，并且可以绑定带有捕获变量的 C++11 lambda 函数。

项目快速启动

安装

首先，确保你已经安装了 pybind11。你可以通过以下命令安装：

pip install pybind11

编写绑定代码

以下是一个简单的示例，展示如何将一个 C++ 函数绑定到 Python：

#include <pybind11/pybind11.h>

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

PYBIND11_MODULE(example, m) {
    m.def("add", &add, "A function that adds two numbers");
}

编译

使用以下命令编译你的 C++ 代码：

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

在 Python 中使用

编译完成后，你可以在 Python 中导入并使用这个模块：

import example
print(example.add(1, 2))  # 输出: 3

应用案例和最佳实践

案例一：绑定 C++ 类

你可以绑定 C++ 类，使其在 Python 中可用。以下是一个示例：

#include <pybind11/pybind11.h>

class Pet {
public:
    Pet(const std::string &name) : name(name) {}
    void setName(const std::string &name_) { name = name_; }
    const std::string &getName() const { return name; }
private:
    std::string name;
};

PYBIND11_MODULE(pet, m) {
    pybind11::class_<Pet>(m, "Pet")
        .def(pybind11::init<const std::string &>())
        .def("setName", &Pet::setName)
        .def("getName", &Pet::getName);
}

在 Python 中使用：

import pet

my_pet = pet.Pet("Molly")
print(my_pet.getName())  # 输出: Molly
my_pet.setName("Bobby")
print(my_pet.getName())  # 输出: Bobby

最佳实践

• 模块化设计：将不同的功能模块化，便于管理和维护。
• 文档注释：在绑定代码中添加详细的文档注释，方便其他开发者理解和使用。
• 错误处理：在 C++ 代码中添加适当的错误处理，确保 Python 代码的稳定性。

典型生态项目

pybind11_json

pybind11_json 是一个用于将 nlohmann::json 与 pybind11 结合的项目，使得在 C++ 和 Python 之间传递 JSON 数据更加方便。

pybind11_mkdoc

pybind11_mkdoc 是一个用于从 C++ 注释生成 Python 文档字符串的工具，帮助你自动生成文档。

pybind11_benchmark

pybind11_benchmark 是一个简单的基准测试工具，用于跟踪 pybind11 的性能变化。

通过这些生态项目，你可以更高效地使用 pybind11，并扩展其功能。