pybind11: C++ 工程提供 Python 接口的实例代码

下面我将详细讲解如何使用 pybind11 提供 Python 接口的实例代码。

1. 简介

pybind11 是一个用于构建 C++ 中 Python 扩展的库，可以轻松地将 C++ 中的类、函数等封装为 Python 中的模块，方便在 Python 中使用 C++ 的功能。

本文将使用一个简单的示例来展示如何使用 pybind11。

2. 安装 pybind11

首先，我们需要安装 pybind11。可以在其官方网站上下载源码，或通过以下命令行安装：

pip install pybind11

3. 编写 C++ 代码

在本示例中，我们将编写一个 C++ 类和一个函数，并使用 pybind11 将其封装为 Python 模块。

在项目文件夹下，新建一个名为 mylib 的文件夹，用于存放我们的 C++ 代码。在 mylib 文件夹下，新建一个名为 add.h 的文件，用于声明一个函数 add：

#ifndef ADD_H
#define ADD_H

int add(int a, int b);

#endif // ADD_H

在 mylib 文件夹下，新建一个名为 add.cpp 的文件，用于定义函数 add：

#include "add.h"

int add(int a, int b) {
    return a + b;
}

在 mylib 文件夹下，新建一个名为 Vector2.h 的文件，用于声明一个 C++ 类 Vector2：

#ifndef VECTOR2_H
#define VECTOR2_H

class Vector2 {
public:
    double x;
    double y;

    Vector2(double x, double y);
    Vector2 add(const Vector2& other);
};

#endif // VECTOR2_H

在 mylib 文件夹下，新建一个名为 Vector2.cpp 的文件，用于定义类 Vector2：

#include "Vector2.h"

Vector2::Vector2(double x, double y) : x(x), y(y) {}

Vector2 Vector2::add(const Vector2& other) {
    return Vector2(x + other.x, y + other.y);
}

4. 封装 C++ 代码为 Python 模块

在项目文件夹下，新建一个名为 bindings 的文件夹，用于存放我们的 Python 模块代码。在 bindings 文件夹下，新建一个名为 mylib.cpp 的文件，用于封装我们的 C++ 代码：

#include <pybind11/pybind11.h>
#include "add.h"
#include "Vector2.h"

namespace py = pybind11;

PYBIND11_MODULE(mylib, m) {
    m.doc() = "pybind11 example plugin"; // optional module docstring

    // 将函数 add 封装为 Python 的函数 add_func
    m.def("add", &add, "A function which adds two numbers");

    // 将类 Vector2 封装为 Python 的类 Vector2
    py::class_<Vector2>(m, "Vector2")
        .def(py::init<double, double>())
        .def("add", &Vector2::add);
}

在 bindings 文件夹下，新建一个名为 setup.py 的文件，用于打包 Python 模块：

import os
import sys
from setuptools import setup
from setuptools.extension import Extension
from pybind11 import get_include, _setup_helpers

ext_modules = [
    Extension(
        "mylib",
        ["bindings/mylib.cpp", "mylib/add.cpp", "mylib/Vector2.cpp"],
        include_dirs=[get_include()]
    ),
]

setup(
    name='mylib',
    version='0.0.1',
    author='My Name',
    author_email='myemail@example.com',
    description='An example Python extension written with pybind11',
    ext_modules=ext_modules,
    language='c++'
)

5. 打包 Python 模块

在终端中，进入项目文件夹，并执行以下命令：

python setup.py build_ext --inplace

执行后，会生成 mylib.cpython-xx-x.so 文件，其中 xx-x 为 Python 的版本号，例如 cp38 表示 Python 3.8 版本。

6. 使用 Python 模块

在 Python 中，使用以下语句导入生成的 mylib 模块：

import mylib

使用以下语句调用函数 add：

assert mylib.add(1, 2) == 3

使用以下语句创建类 Vector2 的实例，并调用其方法 add：

v1 = mylib.Vector2(1.0, 2.0)
v2 = mylib.Vector2(3.0, 4.0)
v3 = v1.add(v2)
assert v3.x == 4.0 and v3.y == 6.0

7. 示例说明

以下是两个示例，说明如何在 C++ 和 Python 中分别使用 Vector2 类：

示例1：计算两个向量的和

首先，我们需要在 C++ 中定义一个 add 函数，用于计算两个 Vector2 类实例的和。在 mylib 文件夹下的 add.cpp 中，加入以下代码：

#include "Vector2.h"

Vector2 add(const Vector2& lhs, const Vector2& rhs) {
    return lhs.add(rhs);
}

在 bindings 文件夹下的 mylib.cpp 中，加入以下代码：

m.def("add", &add, "Calculate the sum of two Vector2 instances");

在 Python 中，使用以下语句调用函数 add：

v1 = mylib.Vector2(1.0, 2.0)
v2 = mylib.Vector2(3.0, 4.0)
v3 = mylib.add(v1, v2)
assert v3.x == 4.0 and v3.y == 6.0

示例2：计算向量的长度

假设我们想要计算一个向量的长度，我们可以在 Vector2 类中加入以下代码：

double length() {
    return sqrt(x * x + y * y);
}