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