pybind11学习 | 面向对象编程

本文主要记录官方文档中 OBJECT-ORIENTED CODE 一章的学习笔记。

1 自定义类的绑定

在C++中自定义一个数据结构Pet，代码如下：

struct Pet {
    Pet(const std::string &name) : name(name) { }
    void setName(const std::string &name_) { name = name_; }
    const std::string &getName() const { return name; }

    std::string name;
};

绑定代码如下：

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

PYBIND11_MODULE(example, m) {
    py::class_<Pet>(m, "Pet")
        .def(py::init<const std::string &>())
        .def("setName", &Pet::setName)
        .def("getName", &Pet::getName);
}

py::class_用于创建C++ class或 struct的绑定（对应到Python中就是class）。py::class_<Pet>(m, "Pet")实例化模板，尖括号中是需绑定的class或struct，第一个参数是模块变量，用于指定Python class所在的模块；第二个参数是Python class的名称。py::class_::def用于绑定类的成员函数。py::init()方法使用类构造函数的参数类型作为模板参数，并包装相应的构造函数。静态成员函数需要使用py::class_::def_static来绑定。

Python使用：

>>> import example        
>>> example.Pet
<class 'example.Pet'>
>>> cat=example.Pet("eric") 
>>> cat
<example.Pet object at 0x0000023DB7E705F0>
>>> cat.getName() 
'eric'
>>> cat.setName("bob")
>>> cat.getName()
'bob'

2 绑定匿名函数

为了返回具有可读性的对象信息，我们绑定一个函数到__repr__方法，为了方便我们可以使用匿名函数。

py::class_<Pet>(m, "Pet")
    .def(py::init<const std::string &>())
    .def("setName", &Pet::setName)
    .def("getName", &Pet::getName)
    .def("__repr__",
        [](const Pet &a) {
            return "<example.Pet named '" + a.name + "'>";
        });

修改前：

>>> print(cat)
<example.Pet object at 0x0000023DB7E705F0>

修改后：

>>> print(cat)
<example.Pet named 'eric'>

3 成员变量

使用class_::def_readwrite方法可以导出公有成员变量，使用class_::def_readonly方法则可以导出只读成员变量。

py::class_<Pet>(m, "Pet")
    .def(py::init<const std::string &>())
    .def_readwrite("name", &Pet::name)
    // ... remainder ...

Python中使用示例如下：

>>> import example
>>> cat = example.Pet("eric")
>>> cat.name
'eric'
>>> cat.name = 'bob'
>>> cat.name
'bob'

假设Pet::name是一个私有成员变量，向外提供setters（修改变量值）和getters（获取变量值）方法。

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

可以使用class_::def_property()(只读成员使用class_::def_property_readonly())来导出私有成员，并生成相应的setter和getter方法：

py::class_<Pet>(m, "Pet")
    .def(py::init<const std::string &>())
    .def_property("name", &Pet::getName, &Pet::setName)
    // ... remainder ...

Python测试：

>>> import example
>>> example.Pet.name
<property object at 0x000001F7F7B097C0>
>>> cat = example.Pet("eric")
>>> cat.getName()
'eric'
>>> cat.name
'eric'
>>> cat.name = 'bob'
>>> cat.name
'bob'

只写属性通过将read函数定义为nullptr来实现。

class_::def_readwrite_static(), class_::def_readonly_static() class_::def_property_static(), class_::def_property_readonly_static()用于绑定静态变量和属性。

4 动态属性

我们知道，Python原生类可以动态获得新属性。

>>> class Pet:
...    name = "Molly"
...
>>> p = Pet()
>>> p.name = "Charly"  # overwrite existing
>>> p.age = 2  # dynamically add a new attribute

默认情况下，从C++导出的类不支持动态属性，其可写属性必须是通过class_::def_readwrite或class_::def_property定义的。试图设置其他属性将产生错误。为了让C++导出的类也支持动态属性，我们需要在py::class_的构造函数中添加py::dynamic_attr标识：

py::class_<Pet>(m, "Pet", py::dynamic_attr())
    .def(py::init<const std::string &>())
    .def_readwrite("name", &Pet::name);
	// ... remainder ...

这样就可以在为导出的类添加动态属性了，Python中测试如下：

>>> import example
>>> cat = example.Pet("eric")
>>> cat.name                  
'eric'
>>> cat.age = 12              
>>> cat.age
12
>>> cat.__dict__
{'age': 12}

5 继承与向下转型

现在有两个具有继承关系的类：

struct Pet {
    Pet(const std::string &name) : name(name) { }
    std::string name;
};

struct Dog : Pet {
    Dog(const std::string &name) : Pet(name) { }
    std::string bark() const { return "woof!"; }
};

pybind11提供了两种方法来指明继承关系：1）将C++基类作为派生类class_的模板参数；2）将基类名作为class_的参数绑定到派生类。两种方法是等效的。

py::class_<Pet>(m, "Pet")
   .def(py::init<const std::string &>())
   .def_readwrite("name", &Pet::name);

// Method 1: template parameter:
py::class_<Dog, Pet /* <- specify C++ parent type */>(m, "Dog")
    .def(py::init<const std::string &>())
    .def("bark", &Dog::bark);

py::class_<Pet> pet(m, "Pet");
pet.def(py::init<const std::string &>())
   .def_readwrite("name", &Pet::name);

// Method 2: pass parent class_ object:
py::class_<Dog>(m, "Dog", pet /* <- specify Python parent type */)
    .def(py::init<const std::string &>())
    .def("bark", &Dog::bark);

指明继承关系后，派生类实例将获得两者的属性和方法：

>>> p = example.Dog("Molly")
>>> p.name
'Molly'
>>> p.bark()
'woof!'

上面的例子是一个常规非多态的继承关系，表现在Python就是：

// 返回一个指向派生类的基类指针
m.def("pet_store", []() { return std::unique_ptr<Pet>(new Dog("Molly")); });

>>> p = example.pet_store()
>>> type(p)  # `Dog` instance behind `Pet` pointer
Pet          # no pointer downcasting for regular non-polymorphic types
>>> p.bark()
AttributeError: 'Pet' object has no attribute 'bark'

pet_store函数返回了一个Dog实例，但由于基类并非多态类型，Python只识别到了Pet。在C++中，一个类至少有一个虚函数才会被视为多态类型。pybind11会自动识别这种多态机制。

struct PolymorphicPet {
    virtual ~PolymorphicPet() = default;
};

struct PolymorphicDog : PolymorphicPet {
    std::string bark() const { return "woof!"; }
};

// Same binding code
py::class_<PolymorphicPet>(m, "PolymorphicPet");
py::class_<PolymorphicDog, PolymorphicPet>(m, "PolymorphicDog")
    .def(py::init<>())
    .def("bark", &PolymorphicDog::bark);

// Again, return a base pointer to a derived instance
m.def("pet_store2", []() { return std::unique_ptr<PolymorphicPet>(new PolymorphicDog); });

>>> p = example.pet_store2()
>>> type(p)
PolymorphicDog  # automatically downcast
>>> p.bark()
u'woof!'

pybind11会自动地将一个指向多态基类的指针，向下转型为实际的派生类类型。这和C++常见的情况不同，我们不仅可以访问基类的虚函数，还能访问派生类的方法和属性。

6 重载方法

重载方法即拥有相同的函数名，但传入参数不一样的函数：

struct Pet {
    Pet(const std::string &name, int age) : name(name), age(age) { }

    void set(int age_) { age = age_; }
    void set(const std::string &name_) { name = name_; }

    std::string name;
    int age;
};

我们在绑定Pet::set时会报错，因为编译器并不知道用户想选择哪个重载方法。我们需要添加具体的函数指针来消除歧义。绑定多个函数到同一个Python名称，将会自动创建函数重载链。Python将会依次匹配，找到最合适的重载函数。

py::class_<Pet>(m, "Pet")
   .def(py::init<const std::string &, int>())
   .def("set", static_cast<void (Pet::*)(int)>(&Pet::set), "Set the pet's age")
   .def("set", static_cast<void (Pet::*)(const std::string &)>(&Pet::set), "Set the pet's name");

如果编译器支持C++14，也可以使用下面的语法来转换重载函数：

py::class_<Pet>(m, "Pet")
    .def("set", py::overload_cast<int>(&Pet::set), "Set the pet's age")
    .def("set", py::overload_cast<const std::string &>(&Pet::set), "Set the pet's name");

这里，py::overload_cast仅需指定函数类型，不用给出返回值类型，以避免原语法带来的不必要的干扰(void (Pet::*))。如果是基于const的重载，需要使用py::const_标识。

struct Widget {
    int foo(int x, float y);
    int foo(int x, float y) const;
};

py::class_<Widget>(m, "Widget")
   .def("foo_mutable", py::overload_cast<int, float>(&Widget::foo))
   .def("foo_const",   py::overload_cast<int, float>(&Widget::foo, py::const_));

如果想在仅支持C++11的编译器上使用py::overload_cast语法，可以使用py::detail::overload_cast_impl来代替：

template <typename... Args>
using overload_cast_ = pybind11::detail::overload_cast_impl<Args...>;

py::class_<Pet>(m, "Pet")
    .def("set", overload_cast_<int>()(&Pet::set), "Set the pet's age")
    .def("set", overload_cast_<const std::string &>()(&Pet::set), "Set the pet's name");

Note: 如果想定义多个重载的构造函数，使用.def(py::init<...>())语法依次定义就好，指定关键字和默认参数的机制也还是生效的。

7 枚举类型

现在有一个含有枚举和内部类型的类：

struct Pet {
    enum Kind {
        Dog = 0,
        Cat
    };

    struct Attributes {
        float age = 0;
    };

    Pet(const std::string &name, Kind type) : name(name), type(type) { }

    std::string name;
    Kind type;
    Attributes attr;
};

绑定代码如下所示：

py::class_<Pet> pet(m, "Pet");

pet.def(py::init<const std::string &, Pet::Kind>())
    .def_readwrite("name", &Pet::name)
    .def_readwrite("type", &Pet::type)
    .def_readwrite("attr", &Pet::attr);

py::enum_<Pet::Kind>(pet, "Kind")
    .value("Dog", Pet::Kind::Dog)
    .value("Cat", Pet::Kind::Cat)
    .export_values();

py::class_<Pet::Attributes>(pet, "Attributes")
    .def(py::init<>())
    .def_readwrite("age", &Pet::Attributes::age);

为确保嵌套类型Kind和Attributes在Pet的作用域中创建，我们必须向enum_和class_的构造函数提供class_实例pet 。enum_::export_values()用来导出枚举项到父作用域，C++11的强枚举类型需要跳过这点。

>>> p = Pet("Lucy", Pet.Cat)
>>> p.type
Kind.Cat
>>> int(p.type)
1

枚举类型的枚举项会被导出到类的__members__属性中：

>>> Pet.Kind.__members__
{'Dog': Kind.Dog, 'Cat': Kind.Cat}

name属性可以返回枚举值的名称的unicode字符串，str(enum)也可以做到，但两者的实现目标不同。下面的例子展示了两者的差异：

>>> p = Pet("Lucy", Pet.Cat)
>>> pet_type = p.type
>>> pet_type
Pet.Cat
>>> str(pet_type)
'Pet.Cat'
>>> pet_type.name
'Cat'

Note: 当我们给enum_的构造函数增加py::arithmetic()标识时，pybind11将创建一个支持基本算术运算和位运算（如比较、或、异或、取反等）的枚举类型。

py::enum_<Pet::Kind>(pet, "Kind", py::arithmetic())
...

默认情况下，省略这些可以节省内存空间。

8 总结

• 默认情况下，pybind11导出的类比原生Python类效率更高。

参考

[1] 官方文档：pybind11 documentation

[2] 官方文档中文翻译：pybind11-Chinese-docs: pybind11中文文档