c++如何为Python编写C++扩展_c++ Pybind11使用指南-C++-PHP中文网

c++如何为Python编写C++扩展_c++ Pybind11使用指南

php中文网

发布： 2025-12-07 13:43:02

原创

534人浏览过

Pybind11可高效将C++代码暴露给Python，提升性能。1. 通过pip或conda安装后包含头文件即可使用；2. 编写C++函数并用PYBIND11_MODULE和m.def导出；3. 用setuptools编译为共享库，Python可直接导入调用；4. 支持类绑定，如封装Person类并暴露构造函数与成员方法；5. 提供默认参数、STL容器转换、异常处理和NumPy支持等高级功能；6. 建议简化接口、明确返回值策略、拆分模块文件并生成类型提示。

c++如何为python编写c++扩展_c++ pybind11使用指南

用C++为Python编写扩展能显著提升性能关键部分的运行速度。Pybind11 是目前最流行、最简洁的工具之一，它允许你用极少量的 C++ 代码将 C++ 类和函数暴露给 Python。相比传统的 Python/C API 或 Boost.Python，Pybind11 更轻量、易用且功能强大。

1. 安装 Pybind11

Pybind11 是一个头文件库，不需要编译，只需包含即可使用。推荐通过包管理器安装：

pip 安装（推荐）： pip install pybind11
conda 安装： conda install pybind11 -c conda-forge
从源码编译： 从 GitHub 克隆并手动引入头文件目录

安装后，在项目中包含 <pybind11></pybind11> 即可开始使用。

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

创建一个简单的 C++ 文件（例如 example.cpp），导出一个加法函数：

立即学习“Python免费学习笔记（深入）”；

美图AI开放平台

美图推出的AI人脸图像处理平台

102

查看详情

#include <pybind11/pybind11.h>
<p>int add(int a, int b) {
return a + b;
}</p><p>PYBIND11_MODULE(example, m) {
m.doc() = "pybind11 example plugin"; // 模块文档
m.def("add", &add, "A function that adds two numbers");
}</p>

登录后复制

说明：

PYBIND11_MODULE 定义一个 Python 可导入的模块，第一个参数是模块名（与编译后的文件名一致），第二个是模块对象 m。
m.def() 将 C++ 函数绑定为 Python 函数。

3. 编译生成 Python 模块

需要将 C++ 代码编译为 Python 可加载的共享库（如 .so 或 .pyd）。推荐使用 setuptools 构建。

创建 setup.py：

from setuptools import setup, Extension
from pybind11.setup_helpers import Pybind11Extension, build_ext
from pybind11 import get_cmake_dir
import pybind11
<p>ext_modules = [
Pybind11Extension(
"example",
["example.cpp"],
),
]</p><p>setup(
name="example",
ext_modules=ext_modules,
cmdclass={"build_ext": build_ext},
zip_safe=False,
)</p>

登录后复制

然后运行：

python setup.py build_ext --inplace

成功后会生成 example.cpython-xxx.so（Linux/macOS）或 example.pyd（Windows），可直接在 Python 中导入：

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

登录后复制

4. 绑定 C++ 类到 Python

Pybind11 支持完整封装 C++ 类。例如定义一个 Person 类：

#include <pybind11/pybind11.h>
#include <string>
<p>class Person {
public:
Person(const std::string &name, int age) : name(name), age(age) {}
void setName(const std::string &name) { this->name = name; }
const std::string &getName() const { return name; }
void setAge(int age) { this->age = age; }
int getAge() const { return age; }</p><p>private:
std::string name;
int age;
};</p><p>PYBIND11<em>MODULE(example, m) {
pybind11::class</em><Person>(m, "Person")
.def(pybind11::init<const std::string&, int>())
.def("setName", &Person::setName)
.def("getName", &Person::getName)
.def("setAge", &Person::setAge)
.def("getAge", &Person::getAge);
}</p>

登录后复制

在 Python 中使用：

p = example.Person("Alice", 30)
print(p.getName())  # Alice
p.setAge(31)
print(p.getAge())   # 31

登录后复制

5. 高级功能简要介绍

默认参数： 直接支持 C++ 函数的默认参数，自动映射到 Python。
STL 容器转换： 包含 <pybind11></pybind11> 后，std::vector、std::map 等可自动转为 Python list/dict。
异常处理： 使用 m.attr("builtins").attr("ValueError") 抛出 Python 异常，或用 py::wrap_exception 包装 C++ 异常。
NumPy 支持： 包含 <pybind11></pybind11> 可传递 NumPy 数组，实现高效数据共享。