pybind11中文资料(第四章第一步）

古城微笑少年丶 2021-05-17 14:07 402阅读 0赞

在此我要特别感谢pybind11项目创立者 [Wenzel Jakob][]以及众多项目参与者

# 4 第一步 #

本节演示了pybind11的基本功能。在开始之前，请确保已设置开发环境并编译测试用例集。

## **4.1 编译测试用例** ##

### 4.1.1Linux/MacOS ###

Linux系统，需要安装**python-dev**或**python3-dev**软件包以及**cmake**。Mac OS，包含的python版本可直接使用，但仍然必须安装**cmake**。

安装必备组件后，执行

mkdir build
    
    cd build
    
    cmake ..
    
    make check -j 4

最后一行将编译并且运行测试

### 4.1.2windows ###

Windows上，仅支持**Visual Studio 2015**及更高版本，因为pybind11依赖于各种C ++ 11语言功能，而这些特性会破坏旧版本的**Visual Studio**。

编译并运行测试

mkdir build
    
    cd build
    
    cmake ..
    
    cmake --build . --config Release --target check

这将完全用命令行，创建一个Visual Studio项目，编译并运行目标。

**Note:**

如果所有测试都失败，请确保python二进制文件和测试用例在相同的处理器类型和系统位宽（**i386**或**x86\_64****）**编译。你可用cmake -A x64 .. 命令指定**x86\_64**作为Visual Studio项目的体系结构。

See also:

熟悉Boost.Python的高级用户可能希望跳过教程并查看test目录中的测试用例，该测试用例运用了pybind11的所有特性。

## **4.2头文件和命名空间约定** ##

**为简洁起见，所有代码示例都假定存在以下两行：**

#include <pybind11/pybind11.h>
    namespace py = pybind11;

某些功能可能需要其他头文件，但会根据需要指定。

## **4.3为简单函数创建绑定** ##

首先从为一个简单的函数创建Python绑定开始，函数计算两个数字之和并返回的结果：

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

为简单起见[\[1\]][1]，这个函数和绑定代码放在example.cpp文件中，文件内容如下：

#include <pybind11/pybind11.h>
    
    int add(int i, int j) {
    
    return i + j;
    
    }
    
    PYBIND11_MODULE(example, m) {
    
    m.doc() = "pybind11 example plugin"; // optional module docstring
    
    m.def("add", &add, "A function which adds two numbers");
    
    }

\[1\]实际上，实现和绑定代码通常位于单独的文件中。

**PYBIND11\_MODULE()**宏创建了一个函数，当Python代码import相应模块时将调用该函数。模块名（example）作为第一个宏参数给出（不需要用引号包含）。第二个参数（m）定义了一个py::module类型的变量，它是创建绑定的主要接口。方法module::def()将生成add()函数的Python的绑定代码。

Note：

注意到只要少量的代码就可以将函数暴露给Python：所有跟函数入参和返回值的细节由模板元编程自动推断。这种方法和语法是从Boost.Python中借用的，尽管底层实现是完全不同的。

pybind11是一个只有头文件的库，因此没有必要链接任何特殊的库，也没有中间转换步骤。在Linux系统中，可以使用以下命令编译上面的示例：

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

如果需要更多有关于Linux和MacOS上所需编译标志的详细信息，请参阅[手动构建][Link 1]。有关完整的跨平台编译说明，请参阅 [构建系统][Link 2] 页面。

该[python\_example][python_example]和[cmake\_example][cmake_example]库也是很适合初学者的。它们都是具有跨平台构建系统的完整项目示例。两者之间的唯一区别是[python\_example][python_example]使用Python的setuptools构建模块，而[cmake\_example][cmake_example]使用CMake（这应该是已有的C ++项目的首选）。

构建上述C ++代码将生成可导入Python的二进制模块文件。假设已编译的模块位于当前目录中，以下交互式Python会话将显示如何加载和执行该示例：

$ python
    Python 2.7.10 (default, Aug 22 2015, 20:33:39)
    [GCC 4.2.1 Compatible Apple LLVM 7.0.0 (clang-700.0.59.1)] on darwin
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import example
    >>> example.add(1, 2)
    3L
    >>>

## **4.4关键字参数** ##

只要对代码稍加改动，就可以通知Python有关参数的名称（例如本例中的“i”和“j”）。

m.def("add", &add, "A function which adds two numbers",
          py::arg("i"), py::arg("j"));

`arg是可用于将元数据传递到module::def()的几个特殊标记类之一。使用这个修改后的绑定代码，我们可以使用关键字参数来调用函数，这更具可读性，特别是带有许多参数的函数。`

>>> import example
    >>> example.add(i=1, j=2)
    3L

`关键字名称也出现在文档中的函数签名中。`

>>> help(example)
    ....
    
    FUNCTIONS
        add(...)
            Signature : (i: int, j: int) -> int
    
            A function which adds two numbers

`还可以使用较短的命名参数表示法：`

// regular notation
    m.def("add1", &add, py::arg("i"), py::arg("j"));
    // shorthand
    using namespace pybind11::literals;
    m.def("add2", &add, "i"_a, "j"_a);

`_a后缀形成C++11字面量就相当于arg。请注意，这种操作必须首先声明using namespace pybind11::literals。除了literals，这不会从命名空间内引入其他内容。`

## **4.5默认参数** ##

现在假设要绑定的函数具有默认参数，例如：

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

不巧的是，pybind11无法自动提取这些参数，因为它们不是函数类型信息的一部分。但是，使用以下arg来指定它们：

m.def("add", &add, "A function which adds two numbers",
          py::arg("i") = 1, py::arg("j") = 2);

`默认值也出现在文档中。`

>>> help(example)
    ....
    
    FUNCTIONS
        add(...)
            Signature : (i: int = 1, j: int = 2) -> int
    
            A function which adds two numbers

简写符号也可用于默认参数：

// regular notation
    m.def("add1", &add, py::arg("i") = 1, py::arg("j") = 2);
    // shorthand
    m.def("add2", &add, "i"_a=1, "j"_a=2);

## **4.6导出变量** ##

为了暴露C++变量，需要使用attr函数在模块中注册它，做法如下。内置类型和常规对象（稍后将详细介绍）在分配为属性时会自动转换，并且可以使用py::cast函数显式转换。

PYBIND11_MODULE(example, m) {
        m.attr("the_answer") = 42;
        py::object world = py::cast("World");
        m.attr("what") = world;
    }

`然后可以从Python访问这些变量`

>>> import example
    >>> example.the_answer
    42
    >>> example.what
    'World'

## **4.7支持的数据类型** ##

`原生支持大量数据类型，可以无缝地用作函数参数，通常直接返回值或者经过py::cast处理再返回。有关完整概述，请参阅类型转换部分。`

[Wenzel Jakob]: http://rgl.epfl.ch/people/wjakob
[1]: https://pybind11.readthedocs.io/en/latest/basics.html#f1
[Link 1]: https://pybind11.readthedocs.io/en/latest/compiling.html#building-manually
[Link 2]: https://pybind11.readthedocs.io/en/latest/compiling.html#compiling
[python_example]: https://github.com/pybind/python_example
[cmake_example]: https://github.com/pybind/cmake_example