Pybind11使用详解（从零开始掌握Python与C++混合编程）

什么是 pybind11？

pybind11 是一个开源的 C++ 库，仅需包含头文件即可使用，无需额外依赖。它允许开发者将 C++ 函数、类、变量等暴露给 Python，从而在保留 Python 简洁语法的同时，利用 C++ 的高性能计算能力。

对于希望进行 Python扩展开发 的工程师来说，pybind11 比传统的 Boost.Python 更轻量、更易用，且支持现代 C++ 特性（如 C++11/14/17）。

安装 pybind11

你可以通过 pip 安装 pybind11：

pip install pybind11

此外，你还需要安装 C++ 编译器（如 GCC 或 MSVC）和 CMake（用于构建项目）。

第一个 pybind11 示例：Hello World

让我们从一个最简单的例子开始：编写一个 C++ 函数，并在 Python 中调用它。

首先，创建一个名为 example.cpp 的文件：

#include <pybind11/pybind11.h>int add(int i, int j) {    return i + j;}PYBIND11_MODULE(example, m) {    m.doc() = "pybind11 example plugin"; // 可选模块文档字符串    m.def("add", &add, "A function that adds two numbers");}

接下来，我们需要编译这个 C++ 文件为 Python 可导入的模块。创建一个 setup.py 文件：

from setuptools import setup, Extensionfrom pybind11.setup_helpers import Pybind11Extension, build_extfrom pybind11 import get_cmake_dirimport pybind11ext_modules = [    Pybind11Extension(        "example",        ["example.cpp"],    ),]setup(    name="example",    ext_modules=ext_modules,    cmdclass={"build_ext": build_ext},    zip_safe=False,)

然后在终端运行以下命令进行编译：

python setup.py build_ext --inplace

编译成功后，你会看到生成了一个 example.cpython-xxx.so（Linux/macOS）或 example.pyd（Windows）文件。

现在可以在 Python 中导入并使用它：

import exampleprint(example.add(3, 5))  # 输出: 8

绑定 C++ 类到 Python

除了函数，pybind11 还能绑定整个 C++ 类。例如：

#include <pybind11/pybind11.h>#include <string>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_module, m) {    pybind11::class_<Pet>(m, "Pet")        .def(pybind11::init<const std::string &>())        .def("setName", &Pet::setName)        .def("getName", &Pet::getName);}

编译后，在 Python 中可以像使用原生类一样操作：

import pet_modulep = pet_module.Pet("Fluffy")print(p.getName())  # 输出: Fluffyp.setName("Buddy")print(p.getName())  # 输出: Buddy

常见问题与最佳实践

• 内存管理：pybind11 自动处理 Python 与 C++ 之间的对象生命周期，通常无需手动干预。
• 类型转换：支持 STL 容器（如 std::vector、std::map）与 Python 列表、字典的自动转换。
• 异常处理：C++ 异常可自动转换为 Python 异常。

总结

通过本 pybind11教程，你应该已经掌握了如何使用 pybind11 将 C++ 代码集成到 Python 项目中。无论是加速数值计算、封装底层库，还是进行 Python扩展开发，pybind11 都是一个强大而简洁的工具。

建议初学者从简单函数绑定开始，逐步尝试类、模板、STL 容器等高级功能。官方文档（https://pybind11.readthedocs.io）提供了非常详尽的示例和说明。

希望这篇 pybind11入门 教程能帮助你顺利踏上 Python C++混合编程 的旅程！