classes.rst revision 14299
111986Sandreas.sandberg@arm.com.. _classes: 211986Sandreas.sandberg@arm.com 311986Sandreas.sandberg@arm.comObject-oriented code 411986Sandreas.sandberg@arm.com#################### 511986Sandreas.sandberg@arm.com 611986Sandreas.sandberg@arm.comCreating bindings for a custom type 711986Sandreas.sandberg@arm.com=================================== 811986Sandreas.sandberg@arm.com 911986Sandreas.sandberg@arm.comLet's now look at a more complex example where we'll create bindings for a 1011986Sandreas.sandberg@arm.comcustom C++ data structure named ``Pet``. Its definition is given below: 1111986Sandreas.sandberg@arm.com 1211986Sandreas.sandberg@arm.com.. code-block:: cpp 1311986Sandreas.sandberg@arm.com 1411986Sandreas.sandberg@arm.com struct Pet { 1511986Sandreas.sandberg@arm.com Pet(const std::string &name) : name(name) { } 1611986Sandreas.sandberg@arm.com void setName(const std::string &name_) { name = name_; } 1711986Sandreas.sandberg@arm.com const std::string &getName() const { return name; } 1811986Sandreas.sandberg@arm.com 1911986Sandreas.sandberg@arm.com std::string name; 2011986Sandreas.sandberg@arm.com }; 2111986Sandreas.sandberg@arm.com 2211986Sandreas.sandberg@arm.comThe binding code for ``Pet`` looks as follows: 2311986Sandreas.sandberg@arm.com 2411986Sandreas.sandberg@arm.com.. code-block:: cpp 2511986Sandreas.sandberg@arm.com 2611986Sandreas.sandberg@arm.com #include <pybind11/pybind11.h> 2711986Sandreas.sandberg@arm.com 2811986Sandreas.sandberg@arm.com namespace py = pybind11; 2911986Sandreas.sandberg@arm.com 3012391Sjason@lowepower.com PYBIND11_MODULE(example, m) { 3111986Sandreas.sandberg@arm.com py::class_<Pet>(m, "Pet") 3211986Sandreas.sandberg@arm.com .def(py::init<const std::string &>()) 3311986Sandreas.sandberg@arm.com .def("setName", &Pet::setName) 3411986Sandreas.sandberg@arm.com .def("getName", &Pet::getName); 3511986Sandreas.sandberg@arm.com } 3611986Sandreas.sandberg@arm.com 3712037Sandreas.sandberg@arm.com:class:`class_` creates bindings for a C++ *class* or *struct*-style data 3811986Sandreas.sandberg@arm.comstructure. :func:`init` is a convenience function that takes the types of a 3911986Sandreas.sandberg@arm.comconstructor's parameters as template arguments and wraps the corresponding 4011986Sandreas.sandberg@arm.comconstructor (see the :ref:`custom_constructors` section for details). An 4111986Sandreas.sandberg@arm.cominteractive Python session demonstrating this example is shown below: 4211986Sandreas.sandberg@arm.com 4311986Sandreas.sandberg@arm.com.. code-block:: pycon 4411986Sandreas.sandberg@arm.com 4511986Sandreas.sandberg@arm.com % python 4611986Sandreas.sandberg@arm.com >>> import example 4711986Sandreas.sandberg@arm.com >>> p = example.Pet('Molly') 4811986Sandreas.sandberg@arm.com >>> print(p) 4911986Sandreas.sandberg@arm.com <example.Pet object at 0x10cd98060> 5011986Sandreas.sandberg@arm.com >>> p.getName() 5111986Sandreas.sandberg@arm.com u'Molly' 5211986Sandreas.sandberg@arm.com >>> p.setName('Charly') 5311986Sandreas.sandberg@arm.com >>> p.getName() 5411986Sandreas.sandberg@arm.com u'Charly' 5511986Sandreas.sandberg@arm.com 5611986Sandreas.sandberg@arm.com.. seealso:: 5711986Sandreas.sandberg@arm.com 5811986Sandreas.sandberg@arm.com Static member functions can be bound in the same way using 5911986Sandreas.sandberg@arm.com :func:`class_::def_static`. 6011986Sandreas.sandberg@arm.com 6111986Sandreas.sandberg@arm.comKeyword and default arguments 6211986Sandreas.sandberg@arm.com============================= 6311986Sandreas.sandberg@arm.comIt is possible to specify keyword and default arguments using the syntax 6411986Sandreas.sandberg@arm.comdiscussed in the previous chapter. Refer to the sections :ref:`keyword_args` 6511986Sandreas.sandberg@arm.comand :ref:`default_args` for details. 6611986Sandreas.sandberg@arm.com 6711986Sandreas.sandberg@arm.comBinding lambda functions 6811986Sandreas.sandberg@arm.com======================== 6911986Sandreas.sandberg@arm.com 7011986Sandreas.sandberg@arm.comNote how ``print(p)`` produced a rather useless summary of our data structure in the example above: 7111986Sandreas.sandberg@arm.com 7211986Sandreas.sandberg@arm.com.. code-block:: pycon 7311986Sandreas.sandberg@arm.com 7411986Sandreas.sandberg@arm.com >>> print(p) 7511986Sandreas.sandberg@arm.com <example.Pet object at 0x10cd98060> 7611986Sandreas.sandberg@arm.com 7711986Sandreas.sandberg@arm.comTo address this, we could bind an utility function that returns a human-readable 7811986Sandreas.sandberg@arm.comsummary to the special method slot named ``__repr__``. Unfortunately, there is no 7911986Sandreas.sandberg@arm.comsuitable functionality in the ``Pet`` data structure, and it would be nice if 8011986Sandreas.sandberg@arm.comwe did not have to change it. This can easily be accomplished by binding a 8111986Sandreas.sandberg@arm.comLambda function instead: 8211986Sandreas.sandberg@arm.com 8311986Sandreas.sandberg@arm.com.. code-block:: cpp 8411986Sandreas.sandberg@arm.com 8511986Sandreas.sandberg@arm.com py::class_<Pet>(m, "Pet") 8611986Sandreas.sandberg@arm.com .def(py::init<const std::string &>()) 8711986Sandreas.sandberg@arm.com .def("setName", &Pet::setName) 8811986Sandreas.sandberg@arm.com .def("getName", &Pet::getName) 8911986Sandreas.sandberg@arm.com .def("__repr__", 9011986Sandreas.sandberg@arm.com [](const Pet &a) { 9111986Sandreas.sandberg@arm.com return "<example.Pet named '" + a.name + "'>"; 9211986Sandreas.sandberg@arm.com } 9311986Sandreas.sandberg@arm.com ); 9411986Sandreas.sandberg@arm.com 9511986Sandreas.sandberg@arm.comBoth stateless [#f1]_ and stateful lambda closures are supported by pybind11. 9611986Sandreas.sandberg@arm.comWith the above change, the same Python code now produces the following output: 9711986Sandreas.sandberg@arm.com 9811986Sandreas.sandberg@arm.com.. code-block:: pycon 9911986Sandreas.sandberg@arm.com 10011986Sandreas.sandberg@arm.com >>> print(p) 10111986Sandreas.sandberg@arm.com <example.Pet named 'Molly'> 10211986Sandreas.sandberg@arm.com 10311986Sandreas.sandberg@arm.com.. [#f1] Stateless closures are those with an empty pair of brackets ``[]`` as the capture object. 10411986Sandreas.sandberg@arm.com 10511986Sandreas.sandberg@arm.com.. _properties: 10611986Sandreas.sandberg@arm.com 10711986Sandreas.sandberg@arm.comInstance and static fields 10811986Sandreas.sandberg@arm.com========================== 10911986Sandreas.sandberg@arm.com 11011986Sandreas.sandberg@arm.comWe can also directly expose the ``name`` field using the 11111986Sandreas.sandberg@arm.com:func:`class_::def_readwrite` method. A similar :func:`class_::def_readonly` 11211986Sandreas.sandberg@arm.commethod also exists for ``const`` fields. 11311986Sandreas.sandberg@arm.com 11411986Sandreas.sandberg@arm.com.. code-block:: cpp 11511986Sandreas.sandberg@arm.com 11611986Sandreas.sandberg@arm.com py::class_<Pet>(m, "Pet") 11711986Sandreas.sandberg@arm.com .def(py::init<const std::string &>()) 11811986Sandreas.sandberg@arm.com .def_readwrite("name", &Pet::name) 11911986Sandreas.sandberg@arm.com // ... remainder ... 12011986Sandreas.sandberg@arm.com 12111986Sandreas.sandberg@arm.comThis makes it possible to write 12211986Sandreas.sandberg@arm.com 12311986Sandreas.sandberg@arm.com.. code-block:: pycon 12411986Sandreas.sandberg@arm.com 12511986Sandreas.sandberg@arm.com >>> p = example.Pet('Molly') 12611986Sandreas.sandberg@arm.com >>> p.name 12711986Sandreas.sandberg@arm.com u'Molly' 12811986Sandreas.sandberg@arm.com >>> p.name = 'Charly' 12911986Sandreas.sandberg@arm.com >>> p.name 13011986Sandreas.sandberg@arm.com u'Charly' 13111986Sandreas.sandberg@arm.com 13211986Sandreas.sandberg@arm.comNow suppose that ``Pet::name`` was a private internal variable 13311986Sandreas.sandberg@arm.comthat can only be accessed via setters and getters. 13411986Sandreas.sandberg@arm.com 13511986Sandreas.sandberg@arm.com.. code-block:: cpp 13611986Sandreas.sandberg@arm.com 13711986Sandreas.sandberg@arm.com class Pet { 13811986Sandreas.sandberg@arm.com public: 13911986Sandreas.sandberg@arm.com Pet(const std::string &name) : name(name) { } 14011986Sandreas.sandberg@arm.com void setName(const std::string &name_) { name = name_; } 14111986Sandreas.sandberg@arm.com const std::string &getName() const { return name; } 14211986Sandreas.sandberg@arm.com private: 14311986Sandreas.sandberg@arm.com std::string name; 14411986Sandreas.sandberg@arm.com }; 14511986Sandreas.sandberg@arm.com 14611986Sandreas.sandberg@arm.comIn this case, the method :func:`class_::def_property` 14711986Sandreas.sandberg@arm.com(:func:`class_::def_property_readonly` for read-only data) can be used to 14811986Sandreas.sandberg@arm.comprovide a field-like interface within Python that will transparently call 14911986Sandreas.sandberg@arm.comthe setter and getter functions: 15011986Sandreas.sandberg@arm.com 15111986Sandreas.sandberg@arm.com.. code-block:: cpp 15211986Sandreas.sandberg@arm.com 15311986Sandreas.sandberg@arm.com py::class_<Pet>(m, "Pet") 15411986Sandreas.sandberg@arm.com .def(py::init<const std::string &>()) 15511986Sandreas.sandberg@arm.com .def_property("name", &Pet::getName, &Pet::setName) 15611986Sandreas.sandberg@arm.com // ... remainder ... 15711986Sandreas.sandberg@arm.com 15814299Sbbruce@ucdavis.eduWrite only properties can be defined by passing ``nullptr`` as the 15914299Sbbruce@ucdavis.eduinput for the read function. 16014299Sbbruce@ucdavis.edu 16111986Sandreas.sandberg@arm.com.. seealso:: 16211986Sandreas.sandberg@arm.com 16311986Sandreas.sandberg@arm.com Similar functions :func:`class_::def_readwrite_static`, 16411986Sandreas.sandberg@arm.com :func:`class_::def_readonly_static` :func:`class_::def_property_static`, 16511986Sandreas.sandberg@arm.com and :func:`class_::def_property_readonly_static` are provided for binding 16611986Sandreas.sandberg@arm.com static variables and properties. Please also see the section on 16711986Sandreas.sandberg@arm.com :ref:`static_properties` in the advanced part of the documentation. 16811986Sandreas.sandberg@arm.com 16911986Sandreas.sandberg@arm.comDynamic attributes 17011986Sandreas.sandberg@arm.com================== 17111986Sandreas.sandberg@arm.com 17211986Sandreas.sandberg@arm.comNative Python classes can pick up new attributes dynamically: 17311986Sandreas.sandberg@arm.com 17411986Sandreas.sandberg@arm.com.. code-block:: pycon 17511986Sandreas.sandberg@arm.com 17611986Sandreas.sandberg@arm.com >>> class Pet: 17711986Sandreas.sandberg@arm.com ... name = 'Molly' 17811986Sandreas.sandberg@arm.com ... 17911986Sandreas.sandberg@arm.com >>> p = Pet() 18011986Sandreas.sandberg@arm.com >>> p.name = 'Charly' # overwrite existing 18111986Sandreas.sandberg@arm.com >>> p.age = 2 # dynamically add a new attribute 18211986Sandreas.sandberg@arm.com 18311986Sandreas.sandberg@arm.comBy default, classes exported from C++ do not support this and the only writable 18411986Sandreas.sandberg@arm.comattributes are the ones explicitly defined using :func:`class_::def_readwrite` 18511986Sandreas.sandberg@arm.comor :func:`class_::def_property`. 18611986Sandreas.sandberg@arm.com 18711986Sandreas.sandberg@arm.com.. code-block:: cpp 18811986Sandreas.sandberg@arm.com 18911986Sandreas.sandberg@arm.com py::class_<Pet>(m, "Pet") 19011986Sandreas.sandberg@arm.com .def(py::init<>()) 19111986Sandreas.sandberg@arm.com .def_readwrite("name", &Pet::name); 19211986Sandreas.sandberg@arm.com 19311986Sandreas.sandberg@arm.comTrying to set any other attribute results in an error: 19411986Sandreas.sandberg@arm.com 19511986Sandreas.sandberg@arm.com.. code-block:: pycon 19611986Sandreas.sandberg@arm.com 19711986Sandreas.sandberg@arm.com >>> p = example.Pet() 19811986Sandreas.sandberg@arm.com >>> p.name = 'Charly' # OK, attribute defined in C++ 19911986Sandreas.sandberg@arm.com >>> p.age = 2 # fail 20011986Sandreas.sandberg@arm.com AttributeError: 'Pet' object has no attribute 'age' 20111986Sandreas.sandberg@arm.com 20211986Sandreas.sandberg@arm.comTo enable dynamic attributes for C++ classes, the :class:`py::dynamic_attr` tag 20311986Sandreas.sandberg@arm.commust be added to the :class:`py::class_` constructor: 20411986Sandreas.sandberg@arm.com 20511986Sandreas.sandberg@arm.com.. code-block:: cpp 20611986Sandreas.sandberg@arm.com 20711986Sandreas.sandberg@arm.com py::class_<Pet>(m, "Pet", py::dynamic_attr()) 20811986Sandreas.sandberg@arm.com .def(py::init<>()) 20911986Sandreas.sandberg@arm.com .def_readwrite("name", &Pet::name); 21011986Sandreas.sandberg@arm.com 21111986Sandreas.sandberg@arm.comNow everything works as expected: 21211986Sandreas.sandberg@arm.com 21311986Sandreas.sandberg@arm.com.. code-block:: pycon 21411986Sandreas.sandberg@arm.com 21511986Sandreas.sandberg@arm.com >>> p = example.Pet() 21611986Sandreas.sandberg@arm.com >>> p.name = 'Charly' # OK, overwrite value in C++ 21711986Sandreas.sandberg@arm.com >>> p.age = 2 # OK, dynamically add a new attribute 21811986Sandreas.sandberg@arm.com >>> p.__dict__ # just like a native Python class 21911986Sandreas.sandberg@arm.com {'age': 2} 22011986Sandreas.sandberg@arm.com 22111986Sandreas.sandberg@arm.comNote that there is a small runtime cost for a class with dynamic attributes. 22211986Sandreas.sandberg@arm.comNot only because of the addition of a ``__dict__``, but also because of more 22311986Sandreas.sandberg@arm.comexpensive garbage collection tracking which must be activated to resolve 22411986Sandreas.sandberg@arm.compossible circular references. Native Python classes incur this same cost by 22511986Sandreas.sandberg@arm.comdefault, so this is not anything to worry about. By default, pybind11 classes 22611986Sandreas.sandberg@arm.comare more efficient than native Python classes. Enabling dynamic attributes 22711986Sandreas.sandberg@arm.comjust brings them on par. 22811986Sandreas.sandberg@arm.com 22911986Sandreas.sandberg@arm.com.. _inheritance: 23011986Sandreas.sandberg@arm.com 23114299Sbbruce@ucdavis.eduInheritance and automatic downcasting 23214299Sbbruce@ucdavis.edu===================================== 23311986Sandreas.sandberg@arm.com 23411986Sandreas.sandberg@arm.comSuppose now that the example consists of two data structures with an 23511986Sandreas.sandberg@arm.cominheritance relationship: 23611986Sandreas.sandberg@arm.com 23711986Sandreas.sandberg@arm.com.. code-block:: cpp 23811986Sandreas.sandberg@arm.com 23911986Sandreas.sandberg@arm.com struct Pet { 24011986Sandreas.sandberg@arm.com Pet(const std::string &name) : name(name) { } 24111986Sandreas.sandberg@arm.com std::string name; 24211986Sandreas.sandberg@arm.com }; 24311986Sandreas.sandberg@arm.com 24411986Sandreas.sandberg@arm.com struct Dog : Pet { 24511986Sandreas.sandberg@arm.com Dog(const std::string &name) : Pet(name) { } 24611986Sandreas.sandberg@arm.com std::string bark() const { return "woof!"; } 24711986Sandreas.sandberg@arm.com }; 24811986Sandreas.sandberg@arm.com 24911986Sandreas.sandberg@arm.comThere are two different ways of indicating a hierarchical relationship to 25011986Sandreas.sandberg@arm.compybind11: the first specifies the C++ base class as an extra template 25111986Sandreas.sandberg@arm.comparameter of the :class:`class_`: 25211986Sandreas.sandberg@arm.com 25311986Sandreas.sandberg@arm.com.. code-block:: cpp 25411986Sandreas.sandberg@arm.com 25511986Sandreas.sandberg@arm.com py::class_<Pet>(m, "Pet") 25611986Sandreas.sandberg@arm.com .def(py::init<const std::string &>()) 25711986Sandreas.sandberg@arm.com .def_readwrite("name", &Pet::name); 25811986Sandreas.sandberg@arm.com 25911986Sandreas.sandberg@arm.com // Method 1: template parameter: 26011986Sandreas.sandberg@arm.com py::class_<Dog, Pet /* <- specify C++ parent type */>(m, "Dog") 26111986Sandreas.sandberg@arm.com .def(py::init<const std::string &>()) 26211986Sandreas.sandberg@arm.com .def("bark", &Dog::bark); 26311986Sandreas.sandberg@arm.com 26411986Sandreas.sandberg@arm.comAlternatively, we can also assign a name to the previously bound ``Pet`` 26511986Sandreas.sandberg@arm.com:class:`class_` object and reference it when binding the ``Dog`` class: 26611986Sandreas.sandberg@arm.com 26711986Sandreas.sandberg@arm.com.. code-block:: cpp 26811986Sandreas.sandberg@arm.com 26911986Sandreas.sandberg@arm.com py::class_<Pet> pet(m, "Pet"); 27011986Sandreas.sandberg@arm.com pet.def(py::init<const std::string &>()) 27111986Sandreas.sandberg@arm.com .def_readwrite("name", &Pet::name); 27211986Sandreas.sandberg@arm.com 27311986Sandreas.sandberg@arm.com // Method 2: pass parent class_ object: 27411986Sandreas.sandberg@arm.com py::class_<Dog>(m, "Dog", pet /* <- specify Python parent type */) 27511986Sandreas.sandberg@arm.com .def(py::init<const std::string &>()) 27611986Sandreas.sandberg@arm.com .def("bark", &Dog::bark); 27711986Sandreas.sandberg@arm.com 27811986Sandreas.sandberg@arm.comFunctionality-wise, both approaches are equivalent. Afterwards, instances will 27911986Sandreas.sandberg@arm.comexpose fields and methods of both types: 28011986Sandreas.sandberg@arm.com 28111986Sandreas.sandberg@arm.com.. code-block:: pycon 28211986Sandreas.sandberg@arm.com 28311986Sandreas.sandberg@arm.com >>> p = example.Dog('Molly') 28411986Sandreas.sandberg@arm.com >>> p.name 28511986Sandreas.sandberg@arm.com u'Molly' 28611986Sandreas.sandberg@arm.com >>> p.bark() 28711986Sandreas.sandberg@arm.com u'woof!' 28811986Sandreas.sandberg@arm.com 28912391Sjason@lowepower.comThe C++ classes defined above are regular non-polymorphic types with an 29012391Sjason@lowepower.cominheritance relationship. This is reflected in Python: 29112391Sjason@lowepower.com 29212391Sjason@lowepower.com.. code-block:: cpp 29312391Sjason@lowepower.com 29412391Sjason@lowepower.com // Return a base pointer to a derived instance 29512391Sjason@lowepower.com m.def("pet_store", []() { return std::unique_ptr<Pet>(new Dog("Molly")); }); 29612391Sjason@lowepower.com 29712391Sjason@lowepower.com.. code-block:: pycon 29812391Sjason@lowepower.com 29912391Sjason@lowepower.com >>> p = example.pet_store() 30012391Sjason@lowepower.com >>> type(p) # `Dog` instance behind `Pet` pointer 30114299Sbbruce@ucdavis.edu Pet # no pointer downcasting for regular non-polymorphic types 30212391Sjason@lowepower.com >>> p.bark() 30312391Sjason@lowepower.com AttributeError: 'Pet' object has no attribute 'bark' 30412391Sjason@lowepower.com 30512391Sjason@lowepower.comThe function returned a ``Dog`` instance, but because it's a non-polymorphic 30612391Sjason@lowepower.comtype behind a base pointer, Python only sees a ``Pet``. In C++, a type is only 30712391Sjason@lowepower.comconsidered polymorphic if it has at least one virtual function and pybind11 30812391Sjason@lowepower.comwill automatically recognize this: 30912391Sjason@lowepower.com 31012391Sjason@lowepower.com.. code-block:: cpp 31112391Sjason@lowepower.com 31212391Sjason@lowepower.com struct PolymorphicPet { 31312391Sjason@lowepower.com virtual ~PolymorphicPet() = default; 31412391Sjason@lowepower.com }; 31512391Sjason@lowepower.com 31612391Sjason@lowepower.com struct PolymorphicDog : PolymorphicPet { 31712391Sjason@lowepower.com std::string bark() const { return "woof!"; } 31812391Sjason@lowepower.com }; 31912391Sjason@lowepower.com 32012391Sjason@lowepower.com // Same binding code 32112391Sjason@lowepower.com py::class_<PolymorphicPet>(m, "PolymorphicPet"); 32212391Sjason@lowepower.com py::class_<PolymorphicDog, PolymorphicPet>(m, "PolymorphicDog") 32312391Sjason@lowepower.com .def(py::init<>()) 32412391Sjason@lowepower.com .def("bark", &PolymorphicDog::bark); 32512391Sjason@lowepower.com 32612391Sjason@lowepower.com // Again, return a base pointer to a derived instance 32712391Sjason@lowepower.com m.def("pet_store2", []() { return std::unique_ptr<PolymorphicPet>(new PolymorphicDog); }); 32812391Sjason@lowepower.com 32912391Sjason@lowepower.com.. code-block:: pycon 33012391Sjason@lowepower.com 33112391Sjason@lowepower.com >>> p = example.pet_store2() 33212391Sjason@lowepower.com >>> type(p) 33314299Sbbruce@ucdavis.edu PolymorphicDog # automatically downcast 33412391Sjason@lowepower.com >>> p.bark() 33512391Sjason@lowepower.com u'woof!' 33612391Sjason@lowepower.com 33714299Sbbruce@ucdavis.eduGiven a pointer to a polymorphic base, pybind11 performs automatic downcasting 33812391Sjason@lowepower.comto the actual derived type. Note that this goes beyond the usual situation in 33912391Sjason@lowepower.comC++: we don't just get access to the virtual functions of the base, we get the 34012391Sjason@lowepower.comconcrete derived type including functions and attributes that the base type may 34112391Sjason@lowepower.comnot even be aware of. 34212391Sjason@lowepower.com 34312391Sjason@lowepower.com.. seealso:: 34412391Sjason@lowepower.com 34512391Sjason@lowepower.com For more information about polymorphic behavior see :ref:`overriding_virtuals`. 34612391Sjason@lowepower.com 34712391Sjason@lowepower.com 34811986Sandreas.sandberg@arm.comOverloaded methods 34911986Sandreas.sandberg@arm.com================== 35011986Sandreas.sandberg@arm.com 35111986Sandreas.sandberg@arm.comSometimes there are several overloaded C++ methods with the same name taking 35211986Sandreas.sandberg@arm.comdifferent kinds of input arguments: 35311986Sandreas.sandberg@arm.com 35411986Sandreas.sandberg@arm.com.. code-block:: cpp 35511986Sandreas.sandberg@arm.com 35611986Sandreas.sandberg@arm.com struct Pet { 35711986Sandreas.sandberg@arm.com Pet(const std::string &name, int age) : name(name), age(age) { } 35811986Sandreas.sandberg@arm.com 35912037Sandreas.sandberg@arm.com void set(int age_) { age = age_; } 36012037Sandreas.sandberg@arm.com void set(const std::string &name_) { name = name_; } 36111986Sandreas.sandberg@arm.com 36211986Sandreas.sandberg@arm.com std::string name; 36311986Sandreas.sandberg@arm.com int age; 36411986Sandreas.sandberg@arm.com }; 36511986Sandreas.sandberg@arm.com 36611986Sandreas.sandberg@arm.comAttempting to bind ``Pet::set`` will cause an error since the compiler does not 36711986Sandreas.sandberg@arm.comknow which method the user intended to select. We can disambiguate by casting 36811986Sandreas.sandberg@arm.comthem to function pointers. Binding multiple functions to the same Python name 36911986Sandreas.sandberg@arm.comautomatically creates a chain of function overloads that will be tried in 37011986Sandreas.sandberg@arm.comsequence. 37111986Sandreas.sandberg@arm.com 37211986Sandreas.sandberg@arm.com.. code-block:: cpp 37311986Sandreas.sandberg@arm.com 37411986Sandreas.sandberg@arm.com py::class_<Pet>(m, "Pet") 37511986Sandreas.sandberg@arm.com .def(py::init<const std::string &, int>()) 37611986Sandreas.sandberg@arm.com .def("set", (void (Pet::*)(int)) &Pet::set, "Set the pet's age") 37711986Sandreas.sandberg@arm.com .def("set", (void (Pet::*)(const std::string &)) &Pet::set, "Set the pet's name"); 37811986Sandreas.sandberg@arm.com 37911986Sandreas.sandberg@arm.comThe overload signatures are also visible in the method's docstring: 38011986Sandreas.sandberg@arm.com 38111986Sandreas.sandberg@arm.com.. code-block:: pycon 38211986Sandreas.sandberg@arm.com 38311986Sandreas.sandberg@arm.com >>> help(example.Pet) 38411986Sandreas.sandberg@arm.com 38511986Sandreas.sandberg@arm.com class Pet(__builtin__.object) 38611986Sandreas.sandberg@arm.com | Methods defined here: 38711986Sandreas.sandberg@arm.com | 38811986Sandreas.sandberg@arm.com | __init__(...) 38911986Sandreas.sandberg@arm.com | Signature : (Pet, str, int) -> NoneType 39011986Sandreas.sandberg@arm.com | 39111986Sandreas.sandberg@arm.com | set(...) 39211986Sandreas.sandberg@arm.com | 1. Signature : (Pet, int) -> NoneType 39311986Sandreas.sandberg@arm.com | 39411986Sandreas.sandberg@arm.com | Set the pet's age 39511986Sandreas.sandberg@arm.com | 39611986Sandreas.sandberg@arm.com | 2. Signature : (Pet, str) -> NoneType 39711986Sandreas.sandberg@arm.com | 39811986Sandreas.sandberg@arm.com | Set the pet's name 39911986Sandreas.sandberg@arm.com 40011986Sandreas.sandberg@arm.comIf you have a C++14 compatible compiler [#cpp14]_, you can use an alternative 40111986Sandreas.sandberg@arm.comsyntax to cast the overloaded function: 40211986Sandreas.sandberg@arm.com 40311986Sandreas.sandberg@arm.com.. code-block:: cpp 40411986Sandreas.sandberg@arm.com 40511986Sandreas.sandberg@arm.com py::class_<Pet>(m, "Pet") 40611986Sandreas.sandberg@arm.com .def("set", py::overload_cast<int>(&Pet::set), "Set the pet's age") 40711986Sandreas.sandberg@arm.com .def("set", py::overload_cast<const std::string &>(&Pet::set), "Set the pet's name"); 40811986Sandreas.sandberg@arm.com 40911986Sandreas.sandberg@arm.comHere, ``py::overload_cast`` only requires the parameter types to be specified. 41011986Sandreas.sandberg@arm.comThe return type and class are deduced. This avoids the additional noise of 41111986Sandreas.sandberg@arm.com``void (Pet::*)()`` as seen in the raw cast. If a function is overloaded based 41211986Sandreas.sandberg@arm.comon constness, the ``py::const_`` tag should be used: 41311986Sandreas.sandberg@arm.com 41411986Sandreas.sandberg@arm.com.. code-block:: cpp 41511986Sandreas.sandberg@arm.com 41611986Sandreas.sandberg@arm.com struct Widget { 41711986Sandreas.sandberg@arm.com int foo(int x, float y); 41811986Sandreas.sandberg@arm.com int foo(int x, float y) const; 41911986Sandreas.sandberg@arm.com }; 42011986Sandreas.sandberg@arm.com 42111986Sandreas.sandberg@arm.com py::class_<Widget>(m, "Widget") 42211986Sandreas.sandberg@arm.com .def("foo_mutable", py::overload_cast<int, float>(&Widget::foo)) 42311986Sandreas.sandberg@arm.com .def("foo_const", py::overload_cast<int, float>(&Widget::foo, py::const_)); 42411986Sandreas.sandberg@arm.com 42514299Sbbruce@ucdavis.eduIf you prefer the ``py::overload_cast`` syntax but have a C++11 compatible compiler only, 42614299Sbbruce@ucdavis.eduyou can use ``py::detail::overload_cast_impl`` with an additional set of parentheses: 42714299Sbbruce@ucdavis.edu 42814299Sbbruce@ucdavis.edu.. code-block:: cpp 42914299Sbbruce@ucdavis.edu 43014299Sbbruce@ucdavis.edu template <typename... Args> 43114299Sbbruce@ucdavis.edu using overload_cast_ = pybind11::detail::overload_cast_impl<Args...>; 43214299Sbbruce@ucdavis.edu 43314299Sbbruce@ucdavis.edu py::class_<Pet>(m, "Pet") 43414299Sbbruce@ucdavis.edu .def("set", overload_cast_<int>()(&Pet::set), "Set the pet's age") 43514299Sbbruce@ucdavis.edu .def("set", overload_cast_<const std::string &>()(&Pet::set), "Set the pet's name"); 43611986Sandreas.sandberg@arm.com 43711986Sandreas.sandberg@arm.com.. [#cpp14] A compiler which supports the ``-std=c++14`` flag 43811986Sandreas.sandberg@arm.com or Visual Studio 2015 Update 2 and newer. 43911986Sandreas.sandberg@arm.com 44011986Sandreas.sandberg@arm.com.. note:: 44111986Sandreas.sandberg@arm.com 44211986Sandreas.sandberg@arm.com To define multiple overloaded constructors, simply declare one after the 44311986Sandreas.sandberg@arm.com other using the ``.def(py::init<...>())`` syntax. The existing machinery 44411986Sandreas.sandberg@arm.com for specifying keyword and default arguments also works. 44511986Sandreas.sandberg@arm.com 44611986Sandreas.sandberg@arm.comEnumerations and internal types 44711986Sandreas.sandberg@arm.com=============================== 44811986Sandreas.sandberg@arm.com 44911986Sandreas.sandberg@arm.comLet's now suppose that the example class contains an internal enumeration type, 45011986Sandreas.sandberg@arm.come.g.: 45111986Sandreas.sandberg@arm.com 45211986Sandreas.sandberg@arm.com.. code-block:: cpp 45311986Sandreas.sandberg@arm.com 45411986Sandreas.sandberg@arm.com struct Pet { 45511986Sandreas.sandberg@arm.com enum Kind { 45611986Sandreas.sandberg@arm.com Dog = 0, 45711986Sandreas.sandberg@arm.com Cat 45811986Sandreas.sandberg@arm.com }; 45911986Sandreas.sandberg@arm.com 46011986Sandreas.sandberg@arm.com Pet(const std::string &name, Kind type) : name(name), type(type) { } 46111986Sandreas.sandberg@arm.com 46211986Sandreas.sandberg@arm.com std::string name; 46311986Sandreas.sandberg@arm.com Kind type; 46411986Sandreas.sandberg@arm.com }; 46511986Sandreas.sandberg@arm.com 46611986Sandreas.sandberg@arm.comThe binding code for this example looks as follows: 46711986Sandreas.sandberg@arm.com 46811986Sandreas.sandberg@arm.com.. code-block:: cpp 46911986Sandreas.sandberg@arm.com 47011986Sandreas.sandberg@arm.com py::class_<Pet> pet(m, "Pet"); 47111986Sandreas.sandberg@arm.com 47211986Sandreas.sandberg@arm.com pet.def(py::init<const std::string &, Pet::Kind>()) 47311986Sandreas.sandberg@arm.com .def_readwrite("name", &Pet::name) 47411986Sandreas.sandberg@arm.com .def_readwrite("type", &Pet::type); 47511986Sandreas.sandberg@arm.com 47611986Sandreas.sandberg@arm.com py::enum_<Pet::Kind>(pet, "Kind") 47711986Sandreas.sandberg@arm.com .value("Dog", Pet::Kind::Dog) 47811986Sandreas.sandberg@arm.com .value("Cat", Pet::Kind::Cat) 47911986Sandreas.sandberg@arm.com .export_values(); 48011986Sandreas.sandberg@arm.com 48111986Sandreas.sandberg@arm.comTo ensure that the ``Kind`` type is created within the scope of ``Pet``, the 48211986Sandreas.sandberg@arm.com``pet`` :class:`class_` instance must be supplied to the :class:`enum_`. 48311986Sandreas.sandberg@arm.comconstructor. The :func:`enum_::export_values` function exports the enum entries 48411986Sandreas.sandberg@arm.cominto the parent scope, which should be skipped for newer C++11-style strongly 48511986Sandreas.sandberg@arm.comtyped enums. 48611986Sandreas.sandberg@arm.com 48711986Sandreas.sandberg@arm.com.. code-block:: pycon 48811986Sandreas.sandberg@arm.com 48911986Sandreas.sandberg@arm.com >>> p = Pet('Lucy', Pet.Cat) 49011986Sandreas.sandberg@arm.com >>> p.type 49111986Sandreas.sandberg@arm.com Kind.Cat 49211986Sandreas.sandberg@arm.com >>> int(p.type) 49311986Sandreas.sandberg@arm.com 1L 49411986Sandreas.sandberg@arm.com 49512037Sandreas.sandberg@arm.comThe entries defined by the enumeration type are exposed in the ``__members__`` property: 49612037Sandreas.sandberg@arm.com 49712037Sandreas.sandberg@arm.com.. code-block:: pycon 49812037Sandreas.sandberg@arm.com 49912037Sandreas.sandberg@arm.com >>> Pet.Kind.__members__ 50012037Sandreas.sandberg@arm.com {'Dog': Kind.Dog, 'Cat': Kind.Cat} 50111986Sandreas.sandberg@arm.com 50214299Sbbruce@ucdavis.eduThe ``name`` property returns the name of the enum value as a unicode string. 50314299Sbbruce@ucdavis.edu 50414299Sbbruce@ucdavis.edu.. note:: 50514299Sbbruce@ucdavis.edu 50614299Sbbruce@ucdavis.edu It is also possible to use ``str(enum)``, however these accomplish different 50714299Sbbruce@ucdavis.edu goals. The following shows how these two approaches differ. 50814299Sbbruce@ucdavis.edu 50914299Sbbruce@ucdavis.edu .. code-block:: pycon 51014299Sbbruce@ucdavis.edu 51114299Sbbruce@ucdavis.edu >>> p = Pet( "Lucy", Pet.Cat ) 51214299Sbbruce@ucdavis.edu >>> pet_type = p.type 51314299Sbbruce@ucdavis.edu >>> pet_type 51414299Sbbruce@ucdavis.edu Pet.Cat 51514299Sbbruce@ucdavis.edu >>> str(pet_type) 51614299Sbbruce@ucdavis.edu 'Pet.Cat' 51714299Sbbruce@ucdavis.edu >>> pet_type.name 51814299Sbbruce@ucdavis.edu 'Cat' 51914299Sbbruce@ucdavis.edu 52011986Sandreas.sandberg@arm.com.. note:: 52111986Sandreas.sandberg@arm.com 52211986Sandreas.sandberg@arm.com When the special tag ``py::arithmetic()`` is specified to the ``enum_`` 52311986Sandreas.sandberg@arm.com constructor, pybind11 creates an enumeration that also supports rudimentary 52411986Sandreas.sandberg@arm.com arithmetic and bit-level operations like comparisons, and, or, xor, negation, 52511986Sandreas.sandberg@arm.com etc. 52611986Sandreas.sandberg@arm.com 52711986Sandreas.sandberg@arm.com .. code-block:: cpp 52811986Sandreas.sandberg@arm.com 52911986Sandreas.sandberg@arm.com py::enum_<Pet::Kind>(pet, "Kind", py::arithmetic()) 53011986Sandreas.sandberg@arm.com ... 53111986Sandreas.sandberg@arm.com 53211986Sandreas.sandberg@arm.com By default, these are omitted to conserve space. 533