pybind笔记_入门

1. Header and namespace conventions

假定： 本文及后续pybind11教程中均已经包含如下代码。

#include 

namespace py = pybind11;

pybind11有些特性需要包含其他的头文件，这个视具体情况而定。

2. Creating bindings for a simple function

#include 

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");
}

通常源代码和包裹的代码是放在不同的文件中，这里为了便于展示，放在了同一个文件中。
参数解释说明：

• PYBIND11_MODULE()macro ：creates a function that will be called when an import statement is issued from within Python.
• module name (example): the first macro argument (it should not be in quotes).
• The second argument (m) : defines a variable of type py::module , which is the main interface for creating bindings.
• The method module::def() : generates binding code that exposes the add() function to Python.

构建如上代码会产生动态链接库，如下展示了python如何加载和执行example:

$ 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
>>>

3. Keyword arguments

为函数指定形参名 (“i” and “j” in this case).

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

py::arg ：special tag classes 可以传递metadata给 module::def(). 通过关键字keyword进行传参，可读性增强。

>>> 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);

The _a suffix forms a C++11 literal which is equivalent to arg. Note that the literal operator must first be made visible with the directive using namespace pybind11::literals. This does not bring in anything else from the pybind11 namespace except for literals.

4. Default arguments

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

pybind11 不能自动提取源代码中的默认值，但是通过py::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
The shorthand notation is also available for default arguments:

// 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);

5. Exporting variables

将变量从C++中导出：
如下面代码所示，使用py::moudle::attr() 函数在 module中注册一个变量，内建变量会自动转换到相应的变量上，也可以进行手动类型转换py::cast.

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

python中可以展示相应的py::moudle::attr() 变量

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

Supported data types

A large number of data types are supported out of the box and can be used seamlessly as functions arguments, return values or with py::cast in general. For a full overview, see the Type conversions section.

ref:

https://pybind11.readthedocs.io/en/stable/basics.html#default-arguments