classes.rst revision 11986
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 3011986Sandreas.sandberg@arm.com PYBIND11_PLUGIN(example) { 3111986Sandreas.sandberg@arm.com py::module m("example", "pybind11 example plugin"); 3211986Sandreas.sandberg@arm.com 3311986Sandreas.sandberg@arm.com py::class_<Pet>(m, "Pet") 3411986Sandreas.sandberg@arm.com .def(py::init<const std::string &>()) 3511986Sandreas.sandberg@arm.com .def("setName", &Pet::setName) 3611986Sandreas.sandberg@arm.com .def("getName", &Pet::getName); 3711986Sandreas.sandberg@arm.com 3811986Sandreas.sandberg@arm.com return m.ptr(); 3911986Sandreas.sandberg@arm.com } 4011986Sandreas.sandberg@arm.com 4111986Sandreas.sandberg@arm.com:class:`class_` creates bindings for a C++ `class` or `struct`-style data 4211986Sandreas.sandberg@arm.comstructure. :func:`init` is a convenience function that takes the types of a 4311986Sandreas.sandberg@arm.comconstructor's parameters as template arguments and wraps the corresponding 4411986Sandreas.sandberg@arm.comconstructor (see the :ref:`custom_constructors` section for details). An 4511986Sandreas.sandberg@arm.cominteractive Python session demonstrating this example is shown below: 4611986Sandreas.sandberg@arm.com 4711986Sandreas.sandberg@arm.com.. code-block:: pycon 4811986Sandreas.sandberg@arm.com 4911986Sandreas.sandberg@arm.com % python 5011986Sandreas.sandberg@arm.com >>> import example 5111986Sandreas.sandberg@arm.com >>> p = example.Pet('Molly') 5211986Sandreas.sandberg@arm.com >>> print(p) 5311986Sandreas.sandberg@arm.com <example.Pet object at 0x10cd98060> 5411986Sandreas.sandberg@arm.com >>> p.getName() 5511986Sandreas.sandberg@arm.com u'Molly' 5611986Sandreas.sandberg@arm.com >>> p.setName('Charly') 5711986Sandreas.sandberg@arm.com >>> p.getName() 5811986Sandreas.sandberg@arm.com u'Charly' 5911986Sandreas.sandberg@arm.com 6011986Sandreas.sandberg@arm.com.. seealso:: 6111986Sandreas.sandberg@arm.com 6211986Sandreas.sandberg@arm.com Static member functions can be bound in the same way using 6311986Sandreas.sandberg@arm.com :func:`class_::def_static`. 6411986Sandreas.sandberg@arm.com 6511986Sandreas.sandberg@arm.comKeyword and default arguments 6611986Sandreas.sandberg@arm.com============================= 6711986Sandreas.sandberg@arm.comIt is possible to specify keyword and default arguments using the syntax 6811986Sandreas.sandberg@arm.comdiscussed in the previous chapter. Refer to the sections :ref:`keyword_args` 6911986Sandreas.sandberg@arm.comand :ref:`default_args` for details. 7011986Sandreas.sandberg@arm.com 7111986Sandreas.sandberg@arm.comBinding lambda functions 7211986Sandreas.sandberg@arm.com======================== 7311986Sandreas.sandberg@arm.com 7411986Sandreas.sandberg@arm.comNote how ``print(p)`` produced a rather useless summary of our data structure in the example above: 7511986Sandreas.sandberg@arm.com 7611986Sandreas.sandberg@arm.com.. code-block:: pycon 7711986Sandreas.sandberg@arm.com 7811986Sandreas.sandberg@arm.com >>> print(p) 7911986Sandreas.sandberg@arm.com <example.Pet object at 0x10cd98060> 8011986Sandreas.sandberg@arm.com 8111986Sandreas.sandberg@arm.comTo address this, we could bind an utility function that returns a human-readable 8211986Sandreas.sandberg@arm.comsummary to the special method slot named ``__repr__``. Unfortunately, there is no 8311986Sandreas.sandberg@arm.comsuitable functionality in the ``Pet`` data structure, and it would be nice if 8411986Sandreas.sandberg@arm.comwe did not have to change it. This can easily be accomplished by binding a 8511986Sandreas.sandberg@arm.comLambda function instead: 8611986Sandreas.sandberg@arm.com 8711986Sandreas.sandberg@arm.com.. code-block:: cpp 8811986Sandreas.sandberg@arm.com 8911986Sandreas.sandberg@arm.com py::class_<Pet>(m, "Pet") 9011986Sandreas.sandberg@arm.com .def(py::init<const std::string &>()) 9111986Sandreas.sandberg@arm.com .def("setName", &Pet::setName) 9211986Sandreas.sandberg@arm.com .def("getName", &Pet::getName) 9311986Sandreas.sandberg@arm.com .def("__repr__", 9411986Sandreas.sandberg@arm.com [](const Pet &a) { 9511986Sandreas.sandberg@arm.com return "<example.Pet named '" + a.name + "'>"; 9611986Sandreas.sandberg@arm.com } 9711986Sandreas.sandberg@arm.com ); 9811986Sandreas.sandberg@arm.com 9911986Sandreas.sandberg@arm.comBoth stateless [#f1]_ and stateful lambda closures are supported by pybind11. 10011986Sandreas.sandberg@arm.comWith the above change, the same Python code now produces the following output: 10111986Sandreas.sandberg@arm.com 10211986Sandreas.sandberg@arm.com.. code-block:: pycon 10311986Sandreas.sandberg@arm.com 10411986Sandreas.sandberg@arm.com >>> print(p) 10511986Sandreas.sandberg@arm.com <example.Pet named 'Molly'> 10611986Sandreas.sandberg@arm.com 10711986Sandreas.sandberg@arm.com.. [#f1] Stateless closures are those with an empty pair of brackets ``[]`` as the capture object. 10811986Sandreas.sandberg@arm.com 10911986Sandreas.sandberg@arm.com.. _properties: 11011986Sandreas.sandberg@arm.com 11111986Sandreas.sandberg@arm.comInstance and static fields 11211986Sandreas.sandberg@arm.com========================== 11311986Sandreas.sandberg@arm.com 11411986Sandreas.sandberg@arm.comWe can also directly expose the ``name`` field using the 11511986Sandreas.sandberg@arm.com:func:`class_::def_readwrite` method. A similar :func:`class_::def_readonly` 11611986Sandreas.sandberg@arm.commethod also exists for ``const`` fields. 11711986Sandreas.sandberg@arm.com 11811986Sandreas.sandberg@arm.com.. code-block:: cpp 11911986Sandreas.sandberg@arm.com 12011986Sandreas.sandberg@arm.com py::class_<Pet>(m, "Pet") 12111986Sandreas.sandberg@arm.com .def(py::init<const std::string &>()) 12211986Sandreas.sandberg@arm.com .def_readwrite("name", &Pet::name) 12311986Sandreas.sandberg@arm.com // ... remainder ... 12411986Sandreas.sandberg@arm.com 12511986Sandreas.sandberg@arm.comThis makes it possible to write 12611986Sandreas.sandberg@arm.com 12711986Sandreas.sandberg@arm.com.. code-block:: pycon 12811986Sandreas.sandberg@arm.com 12911986Sandreas.sandberg@arm.com >>> p = example.Pet('Molly') 13011986Sandreas.sandberg@arm.com >>> p.name 13111986Sandreas.sandberg@arm.com u'Molly' 13211986Sandreas.sandberg@arm.com >>> p.name = 'Charly' 13311986Sandreas.sandberg@arm.com >>> p.name 13411986Sandreas.sandberg@arm.com u'Charly' 13511986Sandreas.sandberg@arm.com 13611986Sandreas.sandberg@arm.comNow suppose that ``Pet::name`` was a private internal variable 13711986Sandreas.sandberg@arm.comthat can only be accessed via setters and getters. 13811986Sandreas.sandberg@arm.com 13911986Sandreas.sandberg@arm.com.. code-block:: cpp 14011986Sandreas.sandberg@arm.com 14111986Sandreas.sandberg@arm.com class Pet { 14211986Sandreas.sandberg@arm.com public: 14311986Sandreas.sandberg@arm.com Pet(const std::string &name) : name(name) { } 14411986Sandreas.sandberg@arm.com void setName(const std::string &name_) { name = name_; } 14511986Sandreas.sandberg@arm.com const std::string &getName() const { return name; } 14611986Sandreas.sandberg@arm.com private: 14711986Sandreas.sandberg@arm.com std::string name; 14811986Sandreas.sandberg@arm.com }; 14911986Sandreas.sandberg@arm.com 15011986Sandreas.sandberg@arm.comIn this case, the method :func:`class_::def_property` 15111986Sandreas.sandberg@arm.com(:func:`class_::def_property_readonly` for read-only data) can be used to 15211986Sandreas.sandberg@arm.comprovide a field-like interface within Python that will transparently call 15311986Sandreas.sandberg@arm.comthe setter and getter functions: 15411986Sandreas.sandberg@arm.com 15511986Sandreas.sandberg@arm.com.. code-block:: cpp 15611986Sandreas.sandberg@arm.com 15711986Sandreas.sandberg@arm.com py::class_<Pet>(m, "Pet") 15811986Sandreas.sandberg@arm.com .def(py::init<const std::string &>()) 15911986Sandreas.sandberg@arm.com .def_property("name", &Pet::getName, &Pet::setName) 16011986Sandreas.sandberg@arm.com // ... remainder ... 16111986Sandreas.sandberg@arm.com 16211986Sandreas.sandberg@arm.com.. seealso:: 16311986Sandreas.sandberg@arm.com 16411986Sandreas.sandberg@arm.com Similar functions :func:`class_::def_readwrite_static`, 16511986Sandreas.sandberg@arm.com :func:`class_::def_readonly_static` :func:`class_::def_property_static`, 16611986Sandreas.sandberg@arm.com and :func:`class_::def_property_readonly_static` are provided for binding 16711986Sandreas.sandberg@arm.com static variables and properties. Please also see the section on 16811986Sandreas.sandberg@arm.com :ref:`static_properties` in the advanced part of the documentation. 16911986Sandreas.sandberg@arm.com 17011986Sandreas.sandberg@arm.comDynamic attributes 17111986Sandreas.sandberg@arm.com================== 17211986Sandreas.sandberg@arm.com 17311986Sandreas.sandberg@arm.comNative Python classes can pick up new attributes dynamically: 17411986Sandreas.sandberg@arm.com 17511986Sandreas.sandberg@arm.com.. code-block:: pycon 17611986Sandreas.sandberg@arm.com 17711986Sandreas.sandberg@arm.com >>> class Pet: 17811986Sandreas.sandberg@arm.com ... name = 'Molly' 17911986Sandreas.sandberg@arm.com ... 18011986Sandreas.sandberg@arm.com >>> p = Pet() 18111986Sandreas.sandberg@arm.com >>> p.name = 'Charly' # overwrite existing 18211986Sandreas.sandberg@arm.com >>> p.age = 2 # dynamically add a new attribute 18311986Sandreas.sandberg@arm.com 18411986Sandreas.sandberg@arm.comBy default, classes exported from C++ do not support this and the only writable 18511986Sandreas.sandberg@arm.comattributes are the ones explicitly defined using :func:`class_::def_readwrite` 18611986Sandreas.sandberg@arm.comor :func:`class_::def_property`. 18711986Sandreas.sandberg@arm.com 18811986Sandreas.sandberg@arm.com.. code-block:: cpp 18911986Sandreas.sandberg@arm.com 19011986Sandreas.sandberg@arm.com py::class_<Pet>(m, "Pet") 19111986Sandreas.sandberg@arm.com .def(py::init<>()) 19211986Sandreas.sandberg@arm.com .def_readwrite("name", &Pet::name); 19311986Sandreas.sandberg@arm.com 19411986Sandreas.sandberg@arm.comTrying to set any other attribute results in an error: 19511986Sandreas.sandberg@arm.com 19611986Sandreas.sandberg@arm.com.. code-block:: pycon 19711986Sandreas.sandberg@arm.com 19811986Sandreas.sandberg@arm.com >>> p = example.Pet() 19911986Sandreas.sandberg@arm.com >>> p.name = 'Charly' # OK, attribute defined in C++ 20011986Sandreas.sandberg@arm.com >>> p.age = 2 # fail 20111986Sandreas.sandberg@arm.com AttributeError: 'Pet' object has no attribute 'age' 20211986Sandreas.sandberg@arm.com 20311986Sandreas.sandberg@arm.comTo enable dynamic attributes for C++ classes, the :class:`py::dynamic_attr` tag 20411986Sandreas.sandberg@arm.commust be added to the :class:`py::class_` constructor: 20511986Sandreas.sandberg@arm.com 20611986Sandreas.sandberg@arm.com.. code-block:: cpp 20711986Sandreas.sandberg@arm.com 20811986Sandreas.sandberg@arm.com py::class_<Pet>(m, "Pet", py::dynamic_attr()) 20911986Sandreas.sandberg@arm.com .def(py::init<>()) 21011986Sandreas.sandberg@arm.com .def_readwrite("name", &Pet::name); 21111986Sandreas.sandberg@arm.com 21211986Sandreas.sandberg@arm.comNow everything works as expected: 21311986Sandreas.sandberg@arm.com 21411986Sandreas.sandberg@arm.com.. code-block:: pycon 21511986Sandreas.sandberg@arm.com 21611986Sandreas.sandberg@arm.com >>> p = example.Pet() 21711986Sandreas.sandberg@arm.com >>> p.name = 'Charly' # OK, overwrite value in C++ 21811986Sandreas.sandberg@arm.com >>> p.age = 2 # OK, dynamically add a new attribute 21911986Sandreas.sandberg@arm.com >>> p.__dict__ # just like a native Python class 22011986Sandreas.sandberg@arm.com {'age': 2} 22111986Sandreas.sandberg@arm.com 22211986Sandreas.sandberg@arm.comNote that there is a small runtime cost for a class with dynamic attributes. 22311986Sandreas.sandberg@arm.comNot only because of the addition of a ``__dict__``, but also because of more 22411986Sandreas.sandberg@arm.comexpensive garbage collection tracking which must be activated to resolve 22511986Sandreas.sandberg@arm.compossible circular references. Native Python classes incur this same cost by 22611986Sandreas.sandberg@arm.comdefault, so this is not anything to worry about. By default, pybind11 classes 22711986Sandreas.sandberg@arm.comare more efficient than native Python classes. Enabling dynamic attributes 22811986Sandreas.sandberg@arm.comjust brings them on par. 22911986Sandreas.sandberg@arm.com 23011986Sandreas.sandberg@arm.com.. _inheritance: 23111986Sandreas.sandberg@arm.com 23211986Sandreas.sandberg@arm.comInheritance 23311986Sandreas.sandberg@arm.com=========== 23411986Sandreas.sandberg@arm.com 23511986Sandreas.sandberg@arm.comSuppose now that the example consists of two data structures with an 23611986Sandreas.sandberg@arm.cominheritance relationship: 23711986Sandreas.sandberg@arm.com 23811986Sandreas.sandberg@arm.com.. code-block:: cpp 23911986Sandreas.sandberg@arm.com 24011986Sandreas.sandberg@arm.com struct Pet { 24111986Sandreas.sandberg@arm.com Pet(const std::string &name) : name(name) { } 24211986Sandreas.sandberg@arm.com std::string name; 24311986Sandreas.sandberg@arm.com }; 24411986Sandreas.sandberg@arm.com 24511986Sandreas.sandberg@arm.com struct Dog : Pet { 24611986Sandreas.sandberg@arm.com Dog(const std::string &name) : Pet(name) { } 24711986Sandreas.sandberg@arm.com std::string bark() const { return "woof!"; } 24811986Sandreas.sandberg@arm.com }; 24911986Sandreas.sandberg@arm.com 25011986Sandreas.sandberg@arm.comThere are two different ways of indicating a hierarchical relationship to 25111986Sandreas.sandberg@arm.compybind11: the first specifies the C++ base class as an extra template 25211986Sandreas.sandberg@arm.comparameter of the :class:`class_`: 25311986Sandreas.sandberg@arm.com 25411986Sandreas.sandberg@arm.com.. code-block:: cpp 25511986Sandreas.sandberg@arm.com 25611986Sandreas.sandberg@arm.com py::class_<Pet>(m, "Pet") 25711986Sandreas.sandberg@arm.com .def(py::init<const std::string &>()) 25811986Sandreas.sandberg@arm.com .def_readwrite("name", &Pet::name); 25911986Sandreas.sandberg@arm.com 26011986Sandreas.sandberg@arm.com // Method 1: template parameter: 26111986Sandreas.sandberg@arm.com py::class_<Dog, Pet /* <- specify C++ parent type */>(m, "Dog") 26211986Sandreas.sandberg@arm.com .def(py::init<const std::string &>()) 26311986Sandreas.sandberg@arm.com .def("bark", &Dog::bark); 26411986Sandreas.sandberg@arm.com 26511986Sandreas.sandberg@arm.comAlternatively, we can also assign a name to the previously bound ``Pet`` 26611986Sandreas.sandberg@arm.com:class:`class_` object and reference it when binding the ``Dog`` class: 26711986Sandreas.sandberg@arm.com 26811986Sandreas.sandberg@arm.com.. code-block:: cpp 26911986Sandreas.sandberg@arm.com 27011986Sandreas.sandberg@arm.com py::class_<Pet> pet(m, "Pet"); 27111986Sandreas.sandberg@arm.com pet.def(py::init<const std::string &>()) 27211986Sandreas.sandberg@arm.com .def_readwrite("name", &Pet::name); 27311986Sandreas.sandberg@arm.com 27411986Sandreas.sandberg@arm.com // Method 2: pass parent class_ object: 27511986Sandreas.sandberg@arm.com py::class_<Dog>(m, "Dog", pet /* <- specify Python parent type */) 27611986Sandreas.sandberg@arm.com .def(py::init<const std::string &>()) 27711986Sandreas.sandberg@arm.com .def("bark", &Dog::bark); 27811986Sandreas.sandberg@arm.com 27911986Sandreas.sandberg@arm.comFunctionality-wise, both approaches are equivalent. Afterwards, instances will 28011986Sandreas.sandberg@arm.comexpose fields and methods of both types: 28111986Sandreas.sandberg@arm.com 28211986Sandreas.sandberg@arm.com.. code-block:: pycon 28311986Sandreas.sandberg@arm.com 28411986Sandreas.sandberg@arm.com >>> p = example.Dog('Molly') 28511986Sandreas.sandberg@arm.com >>> p.name 28611986Sandreas.sandberg@arm.com u'Molly' 28711986Sandreas.sandberg@arm.com >>> p.bark() 28811986Sandreas.sandberg@arm.com u'woof!' 28911986Sandreas.sandberg@arm.com 29011986Sandreas.sandberg@arm.comOverloaded methods 29111986Sandreas.sandberg@arm.com================== 29211986Sandreas.sandberg@arm.com 29311986Sandreas.sandberg@arm.comSometimes there are several overloaded C++ methods with the same name taking 29411986Sandreas.sandberg@arm.comdifferent kinds of input arguments: 29511986Sandreas.sandberg@arm.com 29611986Sandreas.sandberg@arm.com.. code-block:: cpp 29711986Sandreas.sandberg@arm.com 29811986Sandreas.sandberg@arm.com struct Pet { 29911986Sandreas.sandberg@arm.com Pet(const std::string &name, int age) : name(name), age(age) { } 30011986Sandreas.sandberg@arm.com 30111986Sandreas.sandberg@arm.com void set(int age) { age = age; } 30211986Sandreas.sandberg@arm.com void set(const std::string &name) { name = name; } 30311986Sandreas.sandberg@arm.com 30411986Sandreas.sandberg@arm.com std::string name; 30511986Sandreas.sandberg@arm.com int age; 30611986Sandreas.sandberg@arm.com }; 30711986Sandreas.sandberg@arm.com 30811986Sandreas.sandberg@arm.comAttempting to bind ``Pet::set`` will cause an error since the compiler does not 30911986Sandreas.sandberg@arm.comknow which method the user intended to select. We can disambiguate by casting 31011986Sandreas.sandberg@arm.comthem to function pointers. Binding multiple functions to the same Python name 31111986Sandreas.sandberg@arm.comautomatically creates a chain of function overloads that will be tried in 31211986Sandreas.sandberg@arm.comsequence. 31311986Sandreas.sandberg@arm.com 31411986Sandreas.sandberg@arm.com.. code-block:: cpp 31511986Sandreas.sandberg@arm.com 31611986Sandreas.sandberg@arm.com py::class_<Pet>(m, "Pet") 31711986Sandreas.sandberg@arm.com .def(py::init<const std::string &, int>()) 31811986Sandreas.sandberg@arm.com .def("set", (void (Pet::*)(int)) &Pet::set, "Set the pet's age") 31911986Sandreas.sandberg@arm.com .def("set", (void (Pet::*)(const std::string &)) &Pet::set, "Set the pet's name"); 32011986Sandreas.sandberg@arm.com 32111986Sandreas.sandberg@arm.comThe overload signatures are also visible in the method's docstring: 32211986Sandreas.sandberg@arm.com 32311986Sandreas.sandberg@arm.com.. code-block:: pycon 32411986Sandreas.sandberg@arm.com 32511986Sandreas.sandberg@arm.com >>> help(example.Pet) 32611986Sandreas.sandberg@arm.com 32711986Sandreas.sandberg@arm.com class Pet(__builtin__.object) 32811986Sandreas.sandberg@arm.com | Methods defined here: 32911986Sandreas.sandberg@arm.com | 33011986Sandreas.sandberg@arm.com | __init__(...) 33111986Sandreas.sandberg@arm.com | Signature : (Pet, str, int) -> NoneType 33211986Sandreas.sandberg@arm.com | 33311986Sandreas.sandberg@arm.com | set(...) 33411986Sandreas.sandberg@arm.com | 1. Signature : (Pet, int) -> NoneType 33511986Sandreas.sandberg@arm.com | 33611986Sandreas.sandberg@arm.com | Set the pet's age 33711986Sandreas.sandberg@arm.com | 33811986Sandreas.sandberg@arm.com | 2. Signature : (Pet, str) -> NoneType 33911986Sandreas.sandberg@arm.com | 34011986Sandreas.sandberg@arm.com | Set the pet's name 34111986Sandreas.sandberg@arm.com 34211986Sandreas.sandberg@arm.comIf you have a C++14 compatible compiler [#cpp14]_, you can use an alternative 34311986Sandreas.sandberg@arm.comsyntax to cast the overloaded function: 34411986Sandreas.sandberg@arm.com 34511986Sandreas.sandberg@arm.com.. code-block:: cpp 34611986Sandreas.sandberg@arm.com 34711986Sandreas.sandberg@arm.com py::class_<Pet>(m, "Pet") 34811986Sandreas.sandberg@arm.com .def("set", py::overload_cast<int>(&Pet::set), "Set the pet's age") 34911986Sandreas.sandberg@arm.com .def("set", py::overload_cast<const std::string &>(&Pet::set), "Set the pet's name"); 35011986Sandreas.sandberg@arm.com 35111986Sandreas.sandberg@arm.comHere, ``py::overload_cast`` only requires the parameter types to be specified. 35211986Sandreas.sandberg@arm.comThe return type and class are deduced. This avoids the additional noise of 35311986Sandreas.sandberg@arm.com``void (Pet::*)()`` as seen in the raw cast. If a function is overloaded based 35411986Sandreas.sandberg@arm.comon constness, the ``py::const_`` tag should be used: 35511986Sandreas.sandberg@arm.com 35611986Sandreas.sandberg@arm.com.. code-block:: cpp 35711986Sandreas.sandberg@arm.com 35811986Sandreas.sandberg@arm.com struct Widget { 35911986Sandreas.sandberg@arm.com int foo(int x, float y); 36011986Sandreas.sandberg@arm.com int foo(int x, float y) const; 36111986Sandreas.sandberg@arm.com }; 36211986Sandreas.sandberg@arm.com 36311986Sandreas.sandberg@arm.com py::class_<Widget>(m, "Widget") 36411986Sandreas.sandberg@arm.com .def("foo_mutable", py::overload_cast<int, float>(&Widget::foo)) 36511986Sandreas.sandberg@arm.com .def("foo_const", py::overload_cast<int, float>(&Widget::foo, py::const_)); 36611986Sandreas.sandberg@arm.com 36711986Sandreas.sandberg@arm.com 36811986Sandreas.sandberg@arm.com.. [#cpp14] A compiler which supports the ``-std=c++14`` flag 36911986Sandreas.sandberg@arm.com or Visual Studio 2015 Update 2 and newer. 37011986Sandreas.sandberg@arm.com 37111986Sandreas.sandberg@arm.com.. note:: 37211986Sandreas.sandberg@arm.com 37311986Sandreas.sandberg@arm.com To define multiple overloaded constructors, simply declare one after the 37411986Sandreas.sandberg@arm.com other using the ``.def(py::init<...>())`` syntax. The existing machinery 37511986Sandreas.sandberg@arm.com for specifying keyword and default arguments also works. 37611986Sandreas.sandberg@arm.com 37711986Sandreas.sandberg@arm.comEnumerations and internal types 37811986Sandreas.sandberg@arm.com=============================== 37911986Sandreas.sandberg@arm.com 38011986Sandreas.sandberg@arm.comLet's now suppose that the example class contains an internal enumeration type, 38111986Sandreas.sandberg@arm.come.g.: 38211986Sandreas.sandberg@arm.com 38311986Sandreas.sandberg@arm.com.. code-block:: cpp 38411986Sandreas.sandberg@arm.com 38511986Sandreas.sandberg@arm.com struct Pet { 38611986Sandreas.sandberg@arm.com enum Kind { 38711986Sandreas.sandberg@arm.com Dog = 0, 38811986Sandreas.sandberg@arm.com Cat 38911986Sandreas.sandberg@arm.com }; 39011986Sandreas.sandberg@arm.com 39111986Sandreas.sandberg@arm.com Pet(const std::string &name, Kind type) : name(name), type(type) { } 39211986Sandreas.sandberg@arm.com 39311986Sandreas.sandberg@arm.com std::string name; 39411986Sandreas.sandberg@arm.com Kind type; 39511986Sandreas.sandberg@arm.com }; 39611986Sandreas.sandberg@arm.com 39711986Sandreas.sandberg@arm.comThe binding code for this example looks as follows: 39811986Sandreas.sandberg@arm.com 39911986Sandreas.sandberg@arm.com.. code-block:: cpp 40011986Sandreas.sandberg@arm.com 40111986Sandreas.sandberg@arm.com py::class_<Pet> pet(m, "Pet"); 40211986Sandreas.sandberg@arm.com 40311986Sandreas.sandberg@arm.com pet.def(py::init<const std::string &, Pet::Kind>()) 40411986Sandreas.sandberg@arm.com .def_readwrite("name", &Pet::name) 40511986Sandreas.sandberg@arm.com .def_readwrite("type", &Pet::type); 40611986Sandreas.sandberg@arm.com 40711986Sandreas.sandberg@arm.com py::enum_<Pet::Kind>(pet, "Kind") 40811986Sandreas.sandberg@arm.com .value("Dog", Pet::Kind::Dog) 40911986Sandreas.sandberg@arm.com .value("Cat", Pet::Kind::Cat) 41011986Sandreas.sandberg@arm.com .export_values(); 41111986Sandreas.sandberg@arm.com 41211986Sandreas.sandberg@arm.comTo ensure that the ``Kind`` type is created within the scope of ``Pet``, the 41311986Sandreas.sandberg@arm.com``pet`` :class:`class_` instance must be supplied to the :class:`enum_`. 41411986Sandreas.sandberg@arm.comconstructor. The :func:`enum_::export_values` function exports the enum entries 41511986Sandreas.sandberg@arm.cominto the parent scope, which should be skipped for newer C++11-style strongly 41611986Sandreas.sandberg@arm.comtyped enums. 41711986Sandreas.sandberg@arm.com 41811986Sandreas.sandberg@arm.com.. code-block:: pycon 41911986Sandreas.sandberg@arm.com 42011986Sandreas.sandberg@arm.com >>> p = Pet('Lucy', Pet.Cat) 42111986Sandreas.sandberg@arm.com >>> p.type 42211986Sandreas.sandberg@arm.com Kind.Cat 42311986Sandreas.sandberg@arm.com >>> int(p.type) 42411986Sandreas.sandberg@arm.com 1L 42511986Sandreas.sandberg@arm.com 42611986Sandreas.sandberg@arm.com 42711986Sandreas.sandberg@arm.com.. note:: 42811986Sandreas.sandberg@arm.com 42911986Sandreas.sandberg@arm.com When the special tag ``py::arithmetic()`` is specified to the ``enum_`` 43011986Sandreas.sandberg@arm.com constructor, pybind11 creates an enumeration that also supports rudimentary 43111986Sandreas.sandberg@arm.com arithmetic and bit-level operations like comparisons, and, or, xor, negation, 43211986Sandreas.sandberg@arm.com etc. 43311986Sandreas.sandberg@arm.com 43411986Sandreas.sandberg@arm.com .. code-block:: cpp 43511986Sandreas.sandberg@arm.com 43611986Sandreas.sandberg@arm.com py::enum_<Pet::Kind>(pet, "Kind", py::arithmetic()) 43711986Sandreas.sandberg@arm.com ... 43811986Sandreas.sandberg@arm.com 43911986Sandreas.sandberg@arm.com By default, these are omitted to conserve space. 440