classes.rst revision 11986
111986Sandreas.sandberg@arm.comClasses 211986Sandreas.sandberg@arm.com####### 311986Sandreas.sandberg@arm.com 411986Sandreas.sandberg@arm.comThis section presents advanced binding code for classes and it is assumed 511986Sandreas.sandberg@arm.comthat you are already familiar with the basics from :doc:`/classes`. 611986Sandreas.sandberg@arm.com 711986Sandreas.sandberg@arm.com.. _overriding_virtuals: 811986Sandreas.sandberg@arm.com 911986Sandreas.sandberg@arm.comOverriding virtual functions in Python 1011986Sandreas.sandberg@arm.com====================================== 1111986Sandreas.sandberg@arm.com 1211986Sandreas.sandberg@arm.comSuppose that a C++ class or interface has a virtual function that we'd like to 1311986Sandreas.sandberg@arm.comto override from within Python (we'll focus on the class ``Animal``; ``Dog`` is 1411986Sandreas.sandberg@arm.comgiven as a specific example of how one would do this with traditional C++ 1511986Sandreas.sandberg@arm.comcode). 1611986Sandreas.sandberg@arm.com 1711986Sandreas.sandberg@arm.com.. code-block:: cpp 1811986Sandreas.sandberg@arm.com 1911986Sandreas.sandberg@arm.com class Animal { 2011986Sandreas.sandberg@arm.com public: 2111986Sandreas.sandberg@arm.com virtual ~Animal() { } 2211986Sandreas.sandberg@arm.com virtual std::string go(int n_times) = 0; 2311986Sandreas.sandberg@arm.com }; 2411986Sandreas.sandberg@arm.com 2511986Sandreas.sandberg@arm.com class Dog : public Animal { 2611986Sandreas.sandberg@arm.com public: 2711986Sandreas.sandberg@arm.com std::string go(int n_times) override { 2811986Sandreas.sandberg@arm.com std::string result; 2911986Sandreas.sandberg@arm.com for (int i=0; i<n_times; ++i) 3011986Sandreas.sandberg@arm.com result += "woof! "; 3111986Sandreas.sandberg@arm.com return result; 3211986Sandreas.sandberg@arm.com } 3311986Sandreas.sandberg@arm.com }; 3411986Sandreas.sandberg@arm.com 3511986Sandreas.sandberg@arm.comLet's also suppose that we are given a plain function which calls the 3611986Sandreas.sandberg@arm.comfunction ``go()`` on an arbitrary ``Animal`` instance. 3711986Sandreas.sandberg@arm.com 3811986Sandreas.sandberg@arm.com.. code-block:: cpp 3911986Sandreas.sandberg@arm.com 4011986Sandreas.sandberg@arm.com std::string call_go(Animal *animal) { 4111986Sandreas.sandberg@arm.com return animal->go(3); 4211986Sandreas.sandberg@arm.com } 4311986Sandreas.sandberg@arm.com 4411986Sandreas.sandberg@arm.comNormally, the binding code for these classes would look as follows: 4511986Sandreas.sandberg@arm.com 4611986Sandreas.sandberg@arm.com.. code-block:: cpp 4711986Sandreas.sandberg@arm.com 4811986Sandreas.sandberg@arm.com PYBIND11_PLUGIN(example) { 4911986Sandreas.sandberg@arm.com py::module m("example", "pybind11 example plugin"); 5011986Sandreas.sandberg@arm.com 5111986Sandreas.sandberg@arm.com py::class_<Animal> animal(m, "Animal"); 5211986Sandreas.sandberg@arm.com animal 5311986Sandreas.sandberg@arm.com .def("go", &Animal::go); 5411986Sandreas.sandberg@arm.com 5511986Sandreas.sandberg@arm.com py::class_<Dog>(m, "Dog", animal) 5611986Sandreas.sandberg@arm.com .def(py::init<>()); 5711986Sandreas.sandberg@arm.com 5811986Sandreas.sandberg@arm.com m.def("call_go", &call_go); 5911986Sandreas.sandberg@arm.com 6011986Sandreas.sandberg@arm.com return m.ptr(); 6111986Sandreas.sandberg@arm.com } 6211986Sandreas.sandberg@arm.com 6311986Sandreas.sandberg@arm.comHowever, these bindings are impossible to extend: ``Animal`` is not 6411986Sandreas.sandberg@arm.comconstructible, and we clearly require some kind of "trampoline" that 6511986Sandreas.sandberg@arm.comredirects virtual calls back to Python. 6611986Sandreas.sandberg@arm.com 6711986Sandreas.sandberg@arm.comDefining a new type of ``Animal`` from within Python is possible but requires a 6811986Sandreas.sandberg@arm.comhelper class that is defined as follows: 6911986Sandreas.sandberg@arm.com 7011986Sandreas.sandberg@arm.com.. code-block:: cpp 7111986Sandreas.sandberg@arm.com 7211986Sandreas.sandberg@arm.com class PyAnimal : public Animal { 7311986Sandreas.sandberg@arm.com public: 7411986Sandreas.sandberg@arm.com /* Inherit the constructors */ 7511986Sandreas.sandberg@arm.com using Animal::Animal; 7611986Sandreas.sandberg@arm.com 7711986Sandreas.sandberg@arm.com /* Trampoline (need one for each virtual function) */ 7811986Sandreas.sandberg@arm.com std::string go(int n_times) override { 7911986Sandreas.sandberg@arm.com PYBIND11_OVERLOAD_PURE( 8011986Sandreas.sandberg@arm.com std::string, /* Return type */ 8111986Sandreas.sandberg@arm.com Animal, /* Parent class */ 8211986Sandreas.sandberg@arm.com go, /* Name of function */ 8311986Sandreas.sandberg@arm.com n_times /* Argument(s) */ 8411986Sandreas.sandberg@arm.com ); 8511986Sandreas.sandberg@arm.com } 8611986Sandreas.sandberg@arm.com }; 8711986Sandreas.sandberg@arm.com 8811986Sandreas.sandberg@arm.comThe macro :func:`PYBIND11_OVERLOAD_PURE` should be used for pure virtual 8911986Sandreas.sandberg@arm.comfunctions, and :func:`PYBIND11_OVERLOAD` should be used for functions which have 9011986Sandreas.sandberg@arm.coma default implementation. There are also two alternate macros 9111986Sandreas.sandberg@arm.com:func:`PYBIND11_OVERLOAD_PURE_NAME` and :func:`PYBIND11_OVERLOAD_NAME` which 9211986Sandreas.sandberg@arm.comtake a string-valued name argument between the *Parent class* and *Name of the 9311986Sandreas.sandberg@arm.comfunction* slots. This is useful when the C++ and Python versions of the 9411986Sandreas.sandberg@arm.comfunction have different names, e.g. ``operator()`` vs ``__call__``. 9511986Sandreas.sandberg@arm.com 9611986Sandreas.sandberg@arm.comThe binding code also needs a few minor adaptations (highlighted): 9711986Sandreas.sandberg@arm.com 9811986Sandreas.sandberg@arm.com.. code-block:: cpp 9911986Sandreas.sandberg@arm.com :emphasize-lines: 4,6,7 10011986Sandreas.sandberg@arm.com 10111986Sandreas.sandberg@arm.com PYBIND11_PLUGIN(example) { 10211986Sandreas.sandberg@arm.com py::module m("example", "pybind11 example plugin"); 10311986Sandreas.sandberg@arm.com 10411986Sandreas.sandberg@arm.com py::class_<Animal, PyAnimal /* <--- trampoline*/> animal(m, "Animal"); 10511986Sandreas.sandberg@arm.com animal 10611986Sandreas.sandberg@arm.com .def(py::init<>()) 10711986Sandreas.sandberg@arm.com .def("go", &Animal::go); 10811986Sandreas.sandberg@arm.com 10911986Sandreas.sandberg@arm.com py::class_<Dog>(m, "Dog", animal) 11011986Sandreas.sandberg@arm.com .def(py::init<>()); 11111986Sandreas.sandberg@arm.com 11211986Sandreas.sandberg@arm.com m.def("call_go", &call_go); 11311986Sandreas.sandberg@arm.com 11411986Sandreas.sandberg@arm.com return m.ptr(); 11511986Sandreas.sandberg@arm.com } 11611986Sandreas.sandberg@arm.com 11711986Sandreas.sandberg@arm.comImportantly, pybind11 is made aware of the trampoline helper class by 11811986Sandreas.sandberg@arm.comspecifying it as an extra template argument to :class:`class_`. (This can also 11911986Sandreas.sandberg@arm.combe combined with other template arguments such as a custom holder type; the 12011986Sandreas.sandberg@arm.comorder of template types does not matter). Following this, we are able to 12111986Sandreas.sandberg@arm.comdefine a constructor as usual. 12211986Sandreas.sandberg@arm.com 12311986Sandreas.sandberg@arm.comNote, however, that the above is sufficient for allowing python classes to 12411986Sandreas.sandberg@arm.comextend ``Animal``, but not ``Dog``: see ref:`virtual_and_inheritance` for the 12511986Sandreas.sandberg@arm.comnecessary steps required to providing proper overload support for inherited 12611986Sandreas.sandberg@arm.comclasses. 12711986Sandreas.sandberg@arm.com 12811986Sandreas.sandberg@arm.comThe Python session below shows how to override ``Animal::go`` and invoke it via 12911986Sandreas.sandberg@arm.coma virtual method call. 13011986Sandreas.sandberg@arm.com 13111986Sandreas.sandberg@arm.com.. code-block:: pycon 13211986Sandreas.sandberg@arm.com 13311986Sandreas.sandberg@arm.com >>> from example import * 13411986Sandreas.sandberg@arm.com >>> d = Dog() 13511986Sandreas.sandberg@arm.com >>> call_go(d) 13611986Sandreas.sandberg@arm.com u'woof! woof! woof! ' 13711986Sandreas.sandberg@arm.com >>> class Cat(Animal): 13811986Sandreas.sandberg@arm.com ... def go(self, n_times): 13911986Sandreas.sandberg@arm.com ... return "meow! " * n_times 14011986Sandreas.sandberg@arm.com ... 14111986Sandreas.sandberg@arm.com >>> c = Cat() 14211986Sandreas.sandberg@arm.com >>> call_go(c) 14311986Sandreas.sandberg@arm.com u'meow! meow! meow! ' 14411986Sandreas.sandberg@arm.com 14511986Sandreas.sandberg@arm.comPlease take a look at the :ref:`macro_notes` before using this feature. 14611986Sandreas.sandberg@arm.com 14711986Sandreas.sandberg@arm.com.. note:: 14811986Sandreas.sandberg@arm.com 14911986Sandreas.sandberg@arm.com When the overridden type returns a reference or pointer to a type that 15011986Sandreas.sandberg@arm.com pybind11 converts from Python (for example, numeric values, std::string, 15111986Sandreas.sandberg@arm.com and other built-in value-converting types), there are some limitations to 15211986Sandreas.sandberg@arm.com be aware of: 15311986Sandreas.sandberg@arm.com 15411986Sandreas.sandberg@arm.com - because in these cases there is no C++ variable to reference (the value 15511986Sandreas.sandberg@arm.com is stored in the referenced Python variable), pybind11 provides one in 15611986Sandreas.sandberg@arm.com the PYBIND11_OVERLOAD macros (when needed) with static storage duration. 15711986Sandreas.sandberg@arm.com Note that this means that invoking the overloaded method on *any* 15811986Sandreas.sandberg@arm.com instance will change the referenced value stored in *all* instances of 15911986Sandreas.sandberg@arm.com that type. 16011986Sandreas.sandberg@arm.com 16111986Sandreas.sandberg@arm.com - Attempts to modify a non-const reference will not have the desired 16211986Sandreas.sandberg@arm.com effect: it will change only the static cache variable, but this change 16311986Sandreas.sandberg@arm.com will not propagate to underlying Python instance, and the change will be 16411986Sandreas.sandberg@arm.com replaced the next time the overload is invoked. 16511986Sandreas.sandberg@arm.com 16611986Sandreas.sandberg@arm.com.. seealso:: 16711986Sandreas.sandberg@arm.com 16811986Sandreas.sandberg@arm.com The file :file:`tests/test_virtual_functions.cpp` contains a complete 16911986Sandreas.sandberg@arm.com example that demonstrates how to override virtual functions using pybind11 17011986Sandreas.sandberg@arm.com in more detail. 17111986Sandreas.sandberg@arm.com 17211986Sandreas.sandberg@arm.com.. _virtual_and_inheritance: 17311986Sandreas.sandberg@arm.com 17411986Sandreas.sandberg@arm.comCombining virtual functions and inheritance 17511986Sandreas.sandberg@arm.com=========================================== 17611986Sandreas.sandberg@arm.com 17711986Sandreas.sandberg@arm.comWhen combining virtual methods with inheritance, you need to be sure to provide 17811986Sandreas.sandberg@arm.coman override for each method for which you want to allow overrides from derived 17911986Sandreas.sandberg@arm.compython classes. For example, suppose we extend the above ``Animal``/``Dog`` 18011986Sandreas.sandberg@arm.comexample as follows: 18111986Sandreas.sandberg@arm.com 18211986Sandreas.sandberg@arm.com.. code-block:: cpp 18311986Sandreas.sandberg@arm.com 18411986Sandreas.sandberg@arm.com class Animal { 18511986Sandreas.sandberg@arm.com public: 18611986Sandreas.sandberg@arm.com virtual std::string go(int n_times) = 0; 18711986Sandreas.sandberg@arm.com virtual std::string name() { return "unknown"; } 18811986Sandreas.sandberg@arm.com }; 18911986Sandreas.sandberg@arm.com class Dog : public class Animal { 19011986Sandreas.sandberg@arm.com public: 19111986Sandreas.sandberg@arm.com std::string go(int n_times) override { 19211986Sandreas.sandberg@arm.com std::string result; 19311986Sandreas.sandberg@arm.com for (int i=0; i<n_times; ++i) 19411986Sandreas.sandberg@arm.com result += bark() + " "; 19511986Sandreas.sandberg@arm.com return result; 19611986Sandreas.sandberg@arm.com } 19711986Sandreas.sandberg@arm.com virtual std::string bark() { return "woof!"; } 19811986Sandreas.sandberg@arm.com }; 19911986Sandreas.sandberg@arm.com 20011986Sandreas.sandberg@arm.comthen the trampoline class for ``Animal`` must, as described in the previous 20111986Sandreas.sandberg@arm.comsection, override ``go()`` and ``name()``, but in order to allow python code to 20211986Sandreas.sandberg@arm.cominherit properly from ``Dog``, we also need a trampoline class for ``Dog`` that 20311986Sandreas.sandberg@arm.comoverrides both the added ``bark()`` method *and* the ``go()`` and ``name()`` 20411986Sandreas.sandberg@arm.commethods inherited from ``Animal`` (even though ``Dog`` doesn't directly 20511986Sandreas.sandberg@arm.comoverride the ``name()`` method): 20611986Sandreas.sandberg@arm.com 20711986Sandreas.sandberg@arm.com.. code-block:: cpp 20811986Sandreas.sandberg@arm.com 20911986Sandreas.sandberg@arm.com class PyAnimal : public Animal { 21011986Sandreas.sandberg@arm.com public: 21111986Sandreas.sandberg@arm.com using Animal::Animal; // Inherit constructors 21211986Sandreas.sandberg@arm.com std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Animal, go, n_times); } 21311986Sandreas.sandberg@arm.com std::string name() override { PYBIND11_OVERLOAD(std::string, Animal, name, ); } 21411986Sandreas.sandberg@arm.com }; 21511986Sandreas.sandberg@arm.com class PyDog : public Dog { 21611986Sandreas.sandberg@arm.com public: 21711986Sandreas.sandberg@arm.com using Dog::Dog; // Inherit constructors 21811986Sandreas.sandberg@arm.com std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Dog, go, n_times); } 21911986Sandreas.sandberg@arm.com std::string name() override { PYBIND11_OVERLOAD(std::string, Dog, name, ); } 22011986Sandreas.sandberg@arm.com std::string bark() override { PYBIND11_OVERLOAD(std::string, Dog, bark, ); } 22111986Sandreas.sandberg@arm.com }; 22211986Sandreas.sandberg@arm.com 22311986Sandreas.sandberg@arm.comA registered class derived from a pybind11-registered class with virtual 22411986Sandreas.sandberg@arm.commethods requires a similar trampoline class, *even if* it doesn't explicitly 22511986Sandreas.sandberg@arm.comdeclare or override any virtual methods itself: 22611986Sandreas.sandberg@arm.com 22711986Sandreas.sandberg@arm.com.. code-block:: cpp 22811986Sandreas.sandberg@arm.com 22911986Sandreas.sandberg@arm.com class Husky : public Dog {}; 23011986Sandreas.sandberg@arm.com class PyHusky : public Husky { 23111986Sandreas.sandberg@arm.com using Dog::Dog; // Inherit constructors 23211986Sandreas.sandberg@arm.com std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Husky, go, n_times); } 23311986Sandreas.sandberg@arm.com std::string name() override { PYBIND11_OVERLOAD(std::string, Husky, name, ); } 23411986Sandreas.sandberg@arm.com std::string bark() override { PYBIND11_OVERLOAD(std::string, Husky, bark, ); } 23511986Sandreas.sandberg@arm.com }; 23611986Sandreas.sandberg@arm.com 23711986Sandreas.sandberg@arm.comThere is, however, a technique that can be used to avoid this duplication 23811986Sandreas.sandberg@arm.com(which can be especially helpful for a base class with several virtual 23911986Sandreas.sandberg@arm.commethods). The technique involves using template trampoline classes, as 24011986Sandreas.sandberg@arm.comfollows: 24111986Sandreas.sandberg@arm.com 24211986Sandreas.sandberg@arm.com.. code-block:: cpp 24311986Sandreas.sandberg@arm.com 24411986Sandreas.sandberg@arm.com template <class AnimalBase = Animal> class PyAnimal : public AnimalBase { 24511986Sandreas.sandberg@arm.com using AnimalBase::AnimalBase; // Inherit constructors 24611986Sandreas.sandberg@arm.com std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, AnimalBase, go, n_times); } 24711986Sandreas.sandberg@arm.com std::string name() override { PYBIND11_OVERLOAD(std::string, AnimalBase, name, ); } 24811986Sandreas.sandberg@arm.com }; 24911986Sandreas.sandberg@arm.com template <class DogBase = Dog> class PyDog : public PyAnimal<DogBase> { 25011986Sandreas.sandberg@arm.com using PyAnimal<DogBase>::PyAnimal; // Inherit constructors 25111986Sandreas.sandberg@arm.com // Override PyAnimal's pure virtual go() with a non-pure one: 25211986Sandreas.sandberg@arm.com std::string go(int n_times) override { PYBIND11_OVERLOAD(std::string, DogBase, go, n_times); } 25311986Sandreas.sandberg@arm.com std::string bark() override { PYBIND11_OVERLOAD(std::string, DogBase, bark, ); } 25411986Sandreas.sandberg@arm.com }; 25511986Sandreas.sandberg@arm.com 25611986Sandreas.sandberg@arm.comThis technique has the advantage of requiring just one trampoline method to be 25711986Sandreas.sandberg@arm.comdeclared per virtual method and pure virtual method override. It does, 25811986Sandreas.sandberg@arm.comhowever, require the compiler to generate at least as many methods (and 25911986Sandreas.sandberg@arm.compossibly more, if both pure virtual and overridden pure virtual methods are 26011986Sandreas.sandberg@arm.comexposed, as above). 26111986Sandreas.sandberg@arm.com 26211986Sandreas.sandberg@arm.comThe classes are then registered with pybind11 using: 26311986Sandreas.sandberg@arm.com 26411986Sandreas.sandberg@arm.com.. code-block:: cpp 26511986Sandreas.sandberg@arm.com 26611986Sandreas.sandberg@arm.com py::class_<Animal, PyAnimal<>> animal(m, "Animal"); 26711986Sandreas.sandberg@arm.com py::class_<Dog, PyDog<>> dog(m, "Dog"); 26811986Sandreas.sandberg@arm.com py::class_<Husky, PyDog<Husky>> husky(m, "Husky"); 26911986Sandreas.sandberg@arm.com // ... add animal, dog, husky definitions 27011986Sandreas.sandberg@arm.com 27111986Sandreas.sandberg@arm.comNote that ``Husky`` did not require a dedicated trampoline template class at 27211986Sandreas.sandberg@arm.comall, since it neither declares any new virtual methods nor provides any pure 27311986Sandreas.sandberg@arm.comvirtual method implementations. 27411986Sandreas.sandberg@arm.com 27511986Sandreas.sandberg@arm.comWith either the repeated-virtuals or templated trampoline methods in place, you 27611986Sandreas.sandberg@arm.comcan now create a python class that inherits from ``Dog``: 27711986Sandreas.sandberg@arm.com 27811986Sandreas.sandberg@arm.com.. code-block:: python 27911986Sandreas.sandberg@arm.com 28011986Sandreas.sandberg@arm.com class ShihTzu(Dog): 28111986Sandreas.sandberg@arm.com def bark(self): 28211986Sandreas.sandberg@arm.com return "yip!" 28311986Sandreas.sandberg@arm.com 28411986Sandreas.sandberg@arm.com.. seealso:: 28511986Sandreas.sandberg@arm.com 28611986Sandreas.sandberg@arm.com See the file :file:`tests/test_virtual_functions.cpp` for complete examples 28711986Sandreas.sandberg@arm.com using both the duplication and templated trampoline approaches. 28811986Sandreas.sandberg@arm.com 28911986Sandreas.sandberg@arm.comExtended trampoline class functionality 29011986Sandreas.sandberg@arm.com======================================= 29111986Sandreas.sandberg@arm.com 29211986Sandreas.sandberg@arm.comThe trampoline classes described in the previous sections are, by default, only 29311986Sandreas.sandberg@arm.cominitialized when needed. More specifically, they are initialized when a python 29411986Sandreas.sandberg@arm.comclass actually inherits from a registered type (instead of merely creating an 29511986Sandreas.sandberg@arm.cominstance of the registered type), or when a registered constructor is only 29611986Sandreas.sandberg@arm.comvalid for the trampoline class but not the registered class. This is primarily 29711986Sandreas.sandberg@arm.comfor performance reasons: when the trampoline class is not needed for anything 29811986Sandreas.sandberg@arm.comexcept virtual method dispatching, not initializing the trampoline class 29911986Sandreas.sandberg@arm.comimproves performance by avoiding needing to do a run-time check to see if the 30011986Sandreas.sandberg@arm.cominheriting python instance has an overloaded method. 30111986Sandreas.sandberg@arm.com 30211986Sandreas.sandberg@arm.comSometimes, however, it is useful to always initialize a trampoline class as an 30311986Sandreas.sandberg@arm.comintermediate class that does more than just handle virtual method dispatching. 30411986Sandreas.sandberg@arm.comFor example, such a class might perform extra class initialization, extra 30511986Sandreas.sandberg@arm.comdestruction operations, and might define new members and methods to enable a 30611986Sandreas.sandberg@arm.commore python-like interface to a class. 30711986Sandreas.sandberg@arm.com 30811986Sandreas.sandberg@arm.comIn order to tell pybind11 that it should *always* initialize the trampoline 30911986Sandreas.sandberg@arm.comclass when creating new instances of a type, the class constructors should be 31011986Sandreas.sandberg@arm.comdeclared using ``py::init_alias<Args, ...>()`` instead of the usual 31111986Sandreas.sandberg@arm.com``py::init<Args, ...>()``. This forces construction via the trampoline class, 31211986Sandreas.sandberg@arm.comensuring member initialization and (eventual) destruction. 31311986Sandreas.sandberg@arm.com 31411986Sandreas.sandberg@arm.com.. seealso:: 31511986Sandreas.sandberg@arm.com 31611986Sandreas.sandberg@arm.com See the file :file:`tests/test_alias_initialization.cpp` for complete examples 31711986Sandreas.sandberg@arm.com showing both normal and forced trampoline instantiation. 31811986Sandreas.sandberg@arm.com 31911986Sandreas.sandberg@arm.com.. _custom_constructors: 32011986Sandreas.sandberg@arm.com 32111986Sandreas.sandberg@arm.comCustom constructors 32211986Sandreas.sandberg@arm.com=================== 32311986Sandreas.sandberg@arm.com 32411986Sandreas.sandberg@arm.comThe syntax for binding constructors was previously introduced, but it only 32511986Sandreas.sandberg@arm.comworks when a constructor with the given parameters actually exists on the C++ 32611986Sandreas.sandberg@arm.comside. To extend this to more general cases, let's take a look at what actually 32711986Sandreas.sandberg@arm.comhappens under the hood: the following statement 32811986Sandreas.sandberg@arm.com 32911986Sandreas.sandberg@arm.com.. code-block:: cpp 33011986Sandreas.sandberg@arm.com 33111986Sandreas.sandberg@arm.com py::class_<Example>(m, "Example") 33211986Sandreas.sandberg@arm.com .def(py::init<int>()); 33311986Sandreas.sandberg@arm.com 33411986Sandreas.sandberg@arm.comis short hand notation for 33511986Sandreas.sandberg@arm.com 33611986Sandreas.sandberg@arm.com.. code-block:: cpp 33711986Sandreas.sandberg@arm.com 33811986Sandreas.sandberg@arm.com py::class_<Example>(m, "Example") 33911986Sandreas.sandberg@arm.com .def("__init__", 34011986Sandreas.sandberg@arm.com [](Example &instance, int arg) { 34111986Sandreas.sandberg@arm.com new (&instance) Example(arg); 34211986Sandreas.sandberg@arm.com } 34311986Sandreas.sandberg@arm.com ); 34411986Sandreas.sandberg@arm.com 34511986Sandreas.sandberg@arm.comIn other words, :func:`init` creates an anonymous function that invokes an 34611986Sandreas.sandberg@arm.comin-place constructor. Memory allocation etc. is already take care of beforehand 34711986Sandreas.sandberg@arm.comwithin pybind11. 34811986Sandreas.sandberg@arm.com 34911986Sandreas.sandberg@arm.com.. _classes_with_non_public_destructors: 35011986Sandreas.sandberg@arm.com 35111986Sandreas.sandberg@arm.comNon-public destructors 35211986Sandreas.sandberg@arm.com====================== 35311986Sandreas.sandberg@arm.com 35411986Sandreas.sandberg@arm.comIf a class has a private or protected destructor (as might e.g. be the case in 35511986Sandreas.sandberg@arm.coma singleton pattern), a compile error will occur when creating bindings via 35611986Sandreas.sandberg@arm.compybind11. The underlying issue is that the ``std::unique_ptr`` holder type that 35711986Sandreas.sandberg@arm.comis responsible for managing the lifetime of instances will reference the 35811986Sandreas.sandberg@arm.comdestructor even if no deallocations ever take place. In order to expose classes 35911986Sandreas.sandberg@arm.comwith private or protected destructors, it is possible to override the holder 36011986Sandreas.sandberg@arm.comtype via a holder type argument to ``class_``. Pybind11 provides a helper class 36111986Sandreas.sandberg@arm.com``py::nodelete`` that disables any destructor invocations. In this case, it is 36211986Sandreas.sandberg@arm.comcrucial that instances are deallocated on the C++ side to avoid memory leaks. 36311986Sandreas.sandberg@arm.com 36411986Sandreas.sandberg@arm.com.. code-block:: cpp 36511986Sandreas.sandberg@arm.com 36611986Sandreas.sandberg@arm.com /* ... definition ... */ 36711986Sandreas.sandberg@arm.com 36811986Sandreas.sandberg@arm.com class MyClass { 36911986Sandreas.sandberg@arm.com private: 37011986Sandreas.sandberg@arm.com ~MyClass() { } 37111986Sandreas.sandberg@arm.com }; 37211986Sandreas.sandberg@arm.com 37311986Sandreas.sandberg@arm.com /* ... binding code ... */ 37411986Sandreas.sandberg@arm.com 37511986Sandreas.sandberg@arm.com py::class_<MyClass, std::unique_ptr<MyClass, py::nodelete>>(m, "MyClass") 37611986Sandreas.sandberg@arm.com .def(py::init<>) 37711986Sandreas.sandberg@arm.com 37811986Sandreas.sandberg@arm.comImplicit conversions 37911986Sandreas.sandberg@arm.com==================== 38011986Sandreas.sandberg@arm.com 38111986Sandreas.sandberg@arm.comSuppose that instances of two types ``A`` and ``B`` are used in a project, and 38211986Sandreas.sandberg@arm.comthat an ``A`` can easily be converted into an instance of type ``B`` (examples of this 38311986Sandreas.sandberg@arm.comcould be a fixed and an arbitrary precision number type). 38411986Sandreas.sandberg@arm.com 38511986Sandreas.sandberg@arm.com.. code-block:: cpp 38611986Sandreas.sandberg@arm.com 38711986Sandreas.sandberg@arm.com py::class_<A>(m, "A") 38811986Sandreas.sandberg@arm.com /// ... members ... 38911986Sandreas.sandberg@arm.com 39011986Sandreas.sandberg@arm.com py::class_<B>(m, "B") 39111986Sandreas.sandberg@arm.com .def(py::init<A>()) 39211986Sandreas.sandberg@arm.com /// ... members ... 39311986Sandreas.sandberg@arm.com 39411986Sandreas.sandberg@arm.com m.def("func", 39511986Sandreas.sandberg@arm.com [](const B &) { /* .... */ } 39611986Sandreas.sandberg@arm.com ); 39711986Sandreas.sandberg@arm.com 39811986Sandreas.sandberg@arm.comTo invoke the function ``func`` using a variable ``a`` containing an ``A`` 39911986Sandreas.sandberg@arm.cominstance, we'd have to write ``func(B(a))`` in Python. On the other hand, C++ 40011986Sandreas.sandberg@arm.comwill automatically apply an implicit type conversion, which makes it possible 40111986Sandreas.sandberg@arm.comto directly write ``func(a)``. 40211986Sandreas.sandberg@arm.com 40311986Sandreas.sandberg@arm.comIn this situation (i.e. where ``B`` has a constructor that converts from 40411986Sandreas.sandberg@arm.com``A``), the following statement enables similar implicit conversions on the 40511986Sandreas.sandberg@arm.comPython side: 40611986Sandreas.sandberg@arm.com 40711986Sandreas.sandberg@arm.com.. code-block:: cpp 40811986Sandreas.sandberg@arm.com 40911986Sandreas.sandberg@arm.com py::implicitly_convertible<A, B>(); 41011986Sandreas.sandberg@arm.com 41111986Sandreas.sandberg@arm.com.. note:: 41211986Sandreas.sandberg@arm.com 41311986Sandreas.sandberg@arm.com Implicit conversions from ``A`` to ``B`` only work when ``B`` is a custom 41411986Sandreas.sandberg@arm.com data type that is exposed to Python via pybind11. 41511986Sandreas.sandberg@arm.com 41611986Sandreas.sandberg@arm.com.. _static_properties: 41711986Sandreas.sandberg@arm.com 41811986Sandreas.sandberg@arm.comStatic properties 41911986Sandreas.sandberg@arm.com================= 42011986Sandreas.sandberg@arm.com 42111986Sandreas.sandberg@arm.comThe section on :ref:`properties` discussed the creation of instance properties 42211986Sandreas.sandberg@arm.comthat are implemented in terms of C++ getters and setters. 42311986Sandreas.sandberg@arm.com 42411986Sandreas.sandberg@arm.comStatic properties can also be created in a similar way to expose getters and 42511986Sandreas.sandberg@arm.comsetters of static class attributes. It is important to note that the implicit 42611986Sandreas.sandberg@arm.com``self`` argument also exists in this case and is used to pass the Python 42711986Sandreas.sandberg@arm.com``type`` subclass instance. This parameter will often not be needed by the C++ 42811986Sandreas.sandberg@arm.comside, and the following example illustrates how to instantiate a lambda getter 42911986Sandreas.sandberg@arm.comfunction that ignores it: 43011986Sandreas.sandberg@arm.com 43111986Sandreas.sandberg@arm.com.. code-block:: cpp 43211986Sandreas.sandberg@arm.com 43311986Sandreas.sandberg@arm.com py::class_<Foo>(m, "Foo") 43411986Sandreas.sandberg@arm.com .def_property_readonly_static("foo", [](py::object /* self */) { return Foo(); }); 43511986Sandreas.sandberg@arm.com 43611986Sandreas.sandberg@arm.comOperator overloading 43711986Sandreas.sandberg@arm.com==================== 43811986Sandreas.sandberg@arm.com 43911986Sandreas.sandberg@arm.comSuppose that we're given the following ``Vector2`` class with a vector addition 44011986Sandreas.sandberg@arm.comand scalar multiplication operation, all implemented using overloaded operators 44111986Sandreas.sandberg@arm.comin C++. 44211986Sandreas.sandberg@arm.com 44311986Sandreas.sandberg@arm.com.. code-block:: cpp 44411986Sandreas.sandberg@arm.com 44511986Sandreas.sandberg@arm.com class Vector2 { 44611986Sandreas.sandberg@arm.com public: 44711986Sandreas.sandberg@arm.com Vector2(float x, float y) : x(x), y(y) { } 44811986Sandreas.sandberg@arm.com 44911986Sandreas.sandberg@arm.com Vector2 operator+(const Vector2 &v) const { return Vector2(x + v.x, y + v.y); } 45011986Sandreas.sandberg@arm.com Vector2 operator*(float value) const { return Vector2(x * value, y * value); } 45111986Sandreas.sandberg@arm.com Vector2& operator+=(const Vector2 &v) { x += v.x; y += v.y; return *this; } 45211986Sandreas.sandberg@arm.com Vector2& operator*=(float v) { x *= v; y *= v; return *this; } 45311986Sandreas.sandberg@arm.com 45411986Sandreas.sandberg@arm.com friend Vector2 operator*(float f, const Vector2 &v) { 45511986Sandreas.sandberg@arm.com return Vector2(f * v.x, f * v.y); 45611986Sandreas.sandberg@arm.com } 45711986Sandreas.sandberg@arm.com 45811986Sandreas.sandberg@arm.com std::string toString() const { 45911986Sandreas.sandberg@arm.com return "[" + std::to_string(x) + ", " + std::to_string(y) + "]"; 46011986Sandreas.sandberg@arm.com } 46111986Sandreas.sandberg@arm.com private: 46211986Sandreas.sandberg@arm.com float x, y; 46311986Sandreas.sandberg@arm.com }; 46411986Sandreas.sandberg@arm.com 46511986Sandreas.sandberg@arm.comThe following snippet shows how the above operators can be conveniently exposed 46611986Sandreas.sandberg@arm.comto Python. 46711986Sandreas.sandberg@arm.com 46811986Sandreas.sandberg@arm.com.. code-block:: cpp 46911986Sandreas.sandberg@arm.com 47011986Sandreas.sandberg@arm.com #include <pybind11/operators.h> 47111986Sandreas.sandberg@arm.com 47211986Sandreas.sandberg@arm.com PYBIND11_PLUGIN(example) { 47311986Sandreas.sandberg@arm.com py::module m("example", "pybind11 example plugin"); 47411986Sandreas.sandberg@arm.com 47511986Sandreas.sandberg@arm.com py::class_<Vector2>(m, "Vector2") 47611986Sandreas.sandberg@arm.com .def(py::init<float, float>()) 47711986Sandreas.sandberg@arm.com .def(py::self + py::self) 47811986Sandreas.sandberg@arm.com .def(py::self += py::self) 47911986Sandreas.sandberg@arm.com .def(py::self *= float()) 48011986Sandreas.sandberg@arm.com .def(float() * py::self) 48111986Sandreas.sandberg@arm.com .def("__repr__", &Vector2::toString); 48211986Sandreas.sandberg@arm.com 48311986Sandreas.sandberg@arm.com return m.ptr(); 48411986Sandreas.sandberg@arm.com } 48511986Sandreas.sandberg@arm.com 48611986Sandreas.sandberg@arm.comNote that a line like 48711986Sandreas.sandberg@arm.com 48811986Sandreas.sandberg@arm.com.. code-block:: cpp 48911986Sandreas.sandberg@arm.com 49011986Sandreas.sandberg@arm.com .def(py::self * float()) 49111986Sandreas.sandberg@arm.com 49211986Sandreas.sandberg@arm.comis really just short hand notation for 49311986Sandreas.sandberg@arm.com 49411986Sandreas.sandberg@arm.com.. code-block:: cpp 49511986Sandreas.sandberg@arm.com 49611986Sandreas.sandberg@arm.com .def("__mul__", [](const Vector2 &a, float b) { 49711986Sandreas.sandberg@arm.com return a * b; 49811986Sandreas.sandberg@arm.com }, py::is_operator()) 49911986Sandreas.sandberg@arm.com 50011986Sandreas.sandberg@arm.comThis can be useful for exposing additional operators that don't exist on the 50111986Sandreas.sandberg@arm.comC++ side, or to perform other types of customization. The ``py::is_operator`` 50211986Sandreas.sandberg@arm.comflag marker is needed to inform pybind11 that this is an operator, which 50311986Sandreas.sandberg@arm.comreturns ``NotImplemented`` when invoked with incompatible arguments rather than 50411986Sandreas.sandberg@arm.comthrowing a type error. 50511986Sandreas.sandberg@arm.com 50611986Sandreas.sandberg@arm.com.. note:: 50711986Sandreas.sandberg@arm.com 50811986Sandreas.sandberg@arm.com To use the more convenient ``py::self`` notation, the additional 50911986Sandreas.sandberg@arm.com header file :file:`pybind11/operators.h` must be included. 51011986Sandreas.sandberg@arm.com 51111986Sandreas.sandberg@arm.com.. seealso:: 51211986Sandreas.sandberg@arm.com 51311986Sandreas.sandberg@arm.com The file :file:`tests/test_operator_overloading.cpp` contains a 51411986Sandreas.sandberg@arm.com complete example that demonstrates how to work with overloaded operators in 51511986Sandreas.sandberg@arm.com more detail. 51611986Sandreas.sandberg@arm.com 51711986Sandreas.sandberg@arm.comPickling support 51811986Sandreas.sandberg@arm.com================ 51911986Sandreas.sandberg@arm.com 52011986Sandreas.sandberg@arm.comPython's ``pickle`` module provides a powerful facility to serialize and 52111986Sandreas.sandberg@arm.comde-serialize a Python object graph into a binary data stream. To pickle and 52211986Sandreas.sandberg@arm.comunpickle C++ classes using pybind11, two additional functions must be provided. 52311986Sandreas.sandberg@arm.comSuppose the class in question has the following signature: 52411986Sandreas.sandberg@arm.com 52511986Sandreas.sandberg@arm.com.. code-block:: cpp 52611986Sandreas.sandberg@arm.com 52711986Sandreas.sandberg@arm.com class Pickleable { 52811986Sandreas.sandberg@arm.com public: 52911986Sandreas.sandberg@arm.com Pickleable(const std::string &value) : m_value(value) { } 53011986Sandreas.sandberg@arm.com const std::string &value() const { return m_value; } 53111986Sandreas.sandberg@arm.com 53211986Sandreas.sandberg@arm.com void setExtra(int extra) { m_extra = extra; } 53311986Sandreas.sandberg@arm.com int extra() const { return m_extra; } 53411986Sandreas.sandberg@arm.com private: 53511986Sandreas.sandberg@arm.com std::string m_value; 53611986Sandreas.sandberg@arm.com int m_extra = 0; 53711986Sandreas.sandberg@arm.com }; 53811986Sandreas.sandberg@arm.com 53911986Sandreas.sandberg@arm.comThe binding code including the requisite ``__setstate__`` and ``__getstate__`` methods [#f3]_ 54011986Sandreas.sandberg@arm.comlooks as follows: 54111986Sandreas.sandberg@arm.com 54211986Sandreas.sandberg@arm.com.. code-block:: cpp 54311986Sandreas.sandberg@arm.com 54411986Sandreas.sandberg@arm.com py::class_<Pickleable>(m, "Pickleable") 54511986Sandreas.sandberg@arm.com .def(py::init<std::string>()) 54611986Sandreas.sandberg@arm.com .def("value", &Pickleable::value) 54711986Sandreas.sandberg@arm.com .def("extra", &Pickleable::extra) 54811986Sandreas.sandberg@arm.com .def("setExtra", &Pickleable::setExtra) 54911986Sandreas.sandberg@arm.com .def("__getstate__", [](const Pickleable &p) { 55011986Sandreas.sandberg@arm.com /* Return a tuple that fully encodes the state of the object */ 55111986Sandreas.sandberg@arm.com return py::make_tuple(p.value(), p.extra()); 55211986Sandreas.sandberg@arm.com }) 55311986Sandreas.sandberg@arm.com .def("__setstate__", [](Pickleable &p, py::tuple t) { 55411986Sandreas.sandberg@arm.com if (t.size() != 2) 55511986Sandreas.sandberg@arm.com throw std::runtime_error("Invalid state!"); 55611986Sandreas.sandberg@arm.com 55711986Sandreas.sandberg@arm.com /* Invoke the in-place constructor. Note that this is needed even 55811986Sandreas.sandberg@arm.com when the object just has a trivial default constructor */ 55911986Sandreas.sandberg@arm.com new (&p) Pickleable(t[0].cast<std::string>()); 56011986Sandreas.sandberg@arm.com 56111986Sandreas.sandberg@arm.com /* Assign any additional state */ 56211986Sandreas.sandberg@arm.com p.setExtra(t[1].cast<int>()); 56311986Sandreas.sandberg@arm.com }); 56411986Sandreas.sandberg@arm.com 56511986Sandreas.sandberg@arm.comAn instance can now be pickled as follows: 56611986Sandreas.sandberg@arm.com 56711986Sandreas.sandberg@arm.com.. code-block:: python 56811986Sandreas.sandberg@arm.com 56911986Sandreas.sandberg@arm.com try: 57011986Sandreas.sandberg@arm.com import cPickle as pickle # Use cPickle on Python 2.7 57111986Sandreas.sandberg@arm.com except ImportError: 57211986Sandreas.sandberg@arm.com import pickle 57311986Sandreas.sandberg@arm.com 57411986Sandreas.sandberg@arm.com p = Pickleable("test_value") 57511986Sandreas.sandberg@arm.com p.setExtra(15) 57611986Sandreas.sandberg@arm.com data = pickle.dumps(p, 2) 57711986Sandreas.sandberg@arm.com 57811986Sandreas.sandberg@arm.comNote that only the cPickle module is supported on Python 2.7. The second 57911986Sandreas.sandberg@arm.comargument to ``dumps`` is also crucial: it selects the pickle protocol version 58011986Sandreas.sandberg@arm.com2, since the older version 1 is not supported. Newer versions are also fine—for 58111986Sandreas.sandberg@arm.cominstance, specify ``-1`` to always use the latest available version. Beware: 58211986Sandreas.sandberg@arm.comfailure to follow these instructions will cause important pybind11 memory 58311986Sandreas.sandberg@arm.comallocation routines to be skipped during unpickling, which will likely lead to 58411986Sandreas.sandberg@arm.commemory corruption and/or segmentation faults. 58511986Sandreas.sandberg@arm.com 58611986Sandreas.sandberg@arm.com.. seealso:: 58711986Sandreas.sandberg@arm.com 58811986Sandreas.sandberg@arm.com The file :file:`tests/test_pickling.cpp` contains a complete example 58911986Sandreas.sandberg@arm.com that demonstrates how to pickle and unpickle types using pybind11 in more 59011986Sandreas.sandberg@arm.com detail. 59111986Sandreas.sandberg@arm.com 59211986Sandreas.sandberg@arm.com.. [#f3] http://docs.python.org/3/library/pickle.html#pickling-class-instances 59311986Sandreas.sandberg@arm.com 59411986Sandreas.sandberg@arm.comMultiple Inheritance 59511986Sandreas.sandberg@arm.com==================== 59611986Sandreas.sandberg@arm.com 59711986Sandreas.sandberg@arm.compybind11 can create bindings for types that derive from multiple base types 59811986Sandreas.sandberg@arm.com(aka. *multiple inheritance*). To do so, specify all bases in the template 59911986Sandreas.sandberg@arm.comarguments of the ``class_`` declaration: 60011986Sandreas.sandberg@arm.com 60111986Sandreas.sandberg@arm.com.. code-block:: cpp 60211986Sandreas.sandberg@arm.com 60311986Sandreas.sandberg@arm.com py::class_<MyType, BaseType1, BaseType2, BaseType3>(m, "MyType") 60411986Sandreas.sandberg@arm.com ... 60511986Sandreas.sandberg@arm.com 60611986Sandreas.sandberg@arm.comThe base types can be specified in arbitrary order, and they can even be 60711986Sandreas.sandberg@arm.cominterspersed with alias types and holder types (discussed earlier in this 60811986Sandreas.sandberg@arm.comdocument)---pybind11 will automatically find out which is which. The only 60911986Sandreas.sandberg@arm.comrequirement is that the first template argument is the type to be declared. 61011986Sandreas.sandberg@arm.com 61111986Sandreas.sandberg@arm.comThere are two caveats regarding the implementation of this feature: 61211986Sandreas.sandberg@arm.com 61311986Sandreas.sandberg@arm.com1. When only one base type is specified for a C++ type that actually has 61411986Sandreas.sandberg@arm.com multiple bases, pybind11 will assume that it does not participate in 61511986Sandreas.sandberg@arm.com multiple inheritance, which can lead to undefined behavior. In such cases, 61611986Sandreas.sandberg@arm.com add the tag ``multiple_inheritance``: 61711986Sandreas.sandberg@arm.com 61811986Sandreas.sandberg@arm.com .. code-block:: cpp 61911986Sandreas.sandberg@arm.com 62011986Sandreas.sandberg@arm.com py::class_<MyType, BaseType2>(m, "MyType", py::multiple_inheritance()); 62111986Sandreas.sandberg@arm.com 62211986Sandreas.sandberg@arm.com The tag is redundant and does not need to be specified when multiple base 62311986Sandreas.sandberg@arm.com types are listed. 62411986Sandreas.sandberg@arm.com 62511986Sandreas.sandberg@arm.com2. As was previously discussed in the section on :ref:`overriding_virtuals`, it 62611986Sandreas.sandberg@arm.com is easy to create Python types that derive from C++ classes. It is even 62711986Sandreas.sandberg@arm.com possible to make use of multiple inheritance to declare a Python class which 62811986Sandreas.sandberg@arm.com has e.g. a C++ and a Python class as bases. However, any attempt to create a 62911986Sandreas.sandberg@arm.com type that has *two or more* C++ classes in its hierarchy of base types will 63011986Sandreas.sandberg@arm.com fail with a fatal error message: ``TypeError: multiple bases have instance 63111986Sandreas.sandberg@arm.com lay-out conflict``. Core Python types that are implemented in C (e.g. 63211986Sandreas.sandberg@arm.com ``dict``, ``list``, ``Exception``, etc.) also fall under this combination 63311986Sandreas.sandberg@arm.com and cannot be combined with C++ types bound using pybind11 via multiple 63411986Sandreas.sandberg@arm.com inheritance. 635