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 4812391Sjason@lowepower.com PYBIND11_MODULE(example, m) { 4914299Sbbruce@ucdavis.edu py::class_<Animal>(m, "Animal") 5011986Sandreas.sandberg@arm.com .def("go", &Animal::go); 5111986Sandreas.sandberg@arm.com 5214299Sbbruce@ucdavis.edu py::class_<Dog, Animal>(m, "Dog") 5311986Sandreas.sandberg@arm.com .def(py::init<>()); 5411986Sandreas.sandberg@arm.com 5511986Sandreas.sandberg@arm.com m.def("call_go", &call_go); 5611986Sandreas.sandberg@arm.com } 5711986Sandreas.sandberg@arm.com 5811986Sandreas.sandberg@arm.comHowever, these bindings are impossible to extend: ``Animal`` is not 5911986Sandreas.sandberg@arm.comconstructible, and we clearly require some kind of "trampoline" that 6011986Sandreas.sandberg@arm.comredirects virtual calls back to Python. 6111986Sandreas.sandberg@arm.com 6211986Sandreas.sandberg@arm.comDefining a new type of ``Animal`` from within Python is possible but requires a 6311986Sandreas.sandberg@arm.comhelper class that is defined as follows: 6411986Sandreas.sandberg@arm.com 6511986Sandreas.sandberg@arm.com.. code-block:: cpp 6611986Sandreas.sandberg@arm.com 6711986Sandreas.sandberg@arm.com class PyAnimal : public Animal { 6811986Sandreas.sandberg@arm.com public: 6911986Sandreas.sandberg@arm.com /* Inherit the constructors */ 7011986Sandreas.sandberg@arm.com using Animal::Animal; 7111986Sandreas.sandberg@arm.com 7211986Sandreas.sandberg@arm.com /* Trampoline (need one for each virtual function) */ 7311986Sandreas.sandberg@arm.com std::string go(int n_times) override { 7411986Sandreas.sandberg@arm.com PYBIND11_OVERLOAD_PURE( 7511986Sandreas.sandberg@arm.com std::string, /* Return type */ 7611986Sandreas.sandberg@arm.com Animal, /* Parent class */ 7712037Sandreas.sandberg@arm.com go, /* Name of function in C++ (must match Python name) */ 7811986Sandreas.sandberg@arm.com n_times /* Argument(s) */ 7911986Sandreas.sandberg@arm.com ); 8011986Sandreas.sandberg@arm.com } 8111986Sandreas.sandberg@arm.com }; 8211986Sandreas.sandberg@arm.com 8314299Sbbruce@ucdavis.eduThe macro :c:macro:`PYBIND11_OVERLOAD_PURE` should be used for pure virtual 8414299Sbbruce@ucdavis.edufunctions, and :c:macro:`PYBIND11_OVERLOAD` should be used for functions which have 8514299Sbbruce@ucdavis.edua default implementation. There are also two alternate macros 8614299Sbbruce@ucdavis.edu:c:macro:`PYBIND11_OVERLOAD_PURE_NAME` and :c:macro:`PYBIND11_OVERLOAD_NAME` which 8711986Sandreas.sandberg@arm.comtake a string-valued name argument between the *Parent class* and *Name of the 8812391Sjason@lowepower.comfunction* slots, which defines the name of function in Python. This is required 8912037Sandreas.sandberg@arm.comwhen the C++ and Python versions of the 9011986Sandreas.sandberg@arm.comfunction have different names, e.g. ``operator()`` vs ``__call__``. 9111986Sandreas.sandberg@arm.com 9211986Sandreas.sandberg@arm.comThe binding code also needs a few minor adaptations (highlighted): 9311986Sandreas.sandberg@arm.com 9411986Sandreas.sandberg@arm.com.. code-block:: cpp 9514299Sbbruce@ucdavis.edu :emphasize-lines: 2,3 9611986Sandreas.sandberg@arm.com 9712391Sjason@lowepower.com PYBIND11_MODULE(example, m) { 9814299Sbbruce@ucdavis.edu py::class_<Animal, PyAnimal /* <--- trampoline*/>(m, "Animal") 9911986Sandreas.sandberg@arm.com .def(py::init<>()) 10011986Sandreas.sandberg@arm.com .def("go", &Animal::go); 10111986Sandreas.sandberg@arm.com 10214299Sbbruce@ucdavis.edu py::class_<Dog, Animal>(m, "Dog") 10311986Sandreas.sandberg@arm.com .def(py::init<>()); 10411986Sandreas.sandberg@arm.com 10511986Sandreas.sandberg@arm.com m.def("call_go", &call_go); 10611986Sandreas.sandberg@arm.com } 10711986Sandreas.sandberg@arm.com 10811986Sandreas.sandberg@arm.comImportantly, pybind11 is made aware of the trampoline helper class by 10912037Sandreas.sandberg@arm.comspecifying it as an extra template argument to :class:`class_`. (This can also 11011986Sandreas.sandberg@arm.combe combined with other template arguments such as a custom holder type; the 11111986Sandreas.sandberg@arm.comorder of template types does not matter). Following this, we are able to 11211986Sandreas.sandberg@arm.comdefine a constructor as usual. 11311986Sandreas.sandberg@arm.com 11412037Sandreas.sandberg@arm.comBindings should be made against the actual class, not the trampoline helper class. 11512037Sandreas.sandberg@arm.com 11612037Sandreas.sandberg@arm.com.. code-block:: cpp 11714299Sbbruce@ucdavis.edu :emphasize-lines: 3 11812037Sandreas.sandberg@arm.com 11914299Sbbruce@ucdavis.edu py::class_<Animal, PyAnimal /* <--- trampoline*/>(m, "Animal"); 12014299Sbbruce@ucdavis.edu .def(py::init<>()) 12114299Sbbruce@ucdavis.edu .def("go", &PyAnimal::go); /* <--- THIS IS WRONG, use &Animal::go */ 12212037Sandreas.sandberg@arm.com 12311986Sandreas.sandberg@arm.comNote, however, that the above is sufficient for allowing python classes to 12412391Sjason@lowepower.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 14512391Sjason@lowepower.comIf you are defining a custom constructor in a derived Python class, you *must* 14612391Sjason@lowepower.comensure that you explicitly call the bound C++ constructor using ``__init__``, 14712391Sjason@lowepower.com*regardless* of whether it is a default constructor or not. Otherwise, the 14812391Sjason@lowepower.commemory for the C++ portion of the instance will be left uninitialized, which 14912391Sjason@lowepower.comwill generally leave the C++ instance in an invalid state and cause undefined 15012391Sjason@lowepower.combehavior if the C++ instance is subsequently used. 15112391Sjason@lowepower.com 15212391Sjason@lowepower.comHere is an example: 15312391Sjason@lowepower.com 15412391Sjason@lowepower.com.. code-block:: python 15512391Sjason@lowepower.com 15614299Sbbruce@ucdavis.edu class Dachshund(Dog): 15712391Sjason@lowepower.com def __init__(self, name): 15814299Sbbruce@ucdavis.edu Dog.__init__(self) # Without this, undefined behavior may occur if the C++ portions are referenced. 15912391Sjason@lowepower.com self.name = name 16012391Sjason@lowepower.com def bark(self): 16112391Sjason@lowepower.com return "yap!" 16212391Sjason@lowepower.com 16312391Sjason@lowepower.comNote that a direct ``__init__`` constructor *should be called*, and ``super()`` 16412391Sjason@lowepower.comshould not be used. For simple cases of linear inheritance, ``super()`` 16512391Sjason@lowepower.commay work, but once you begin mixing Python and C++ multiple inheritance, 16612391Sjason@lowepower.comthings will fall apart due to differences between Python's MRO and C++'s 16712391Sjason@lowepower.commechanisms. 16812391Sjason@lowepower.com 16911986Sandreas.sandberg@arm.comPlease take a look at the :ref:`macro_notes` before using this feature. 17011986Sandreas.sandberg@arm.com 17111986Sandreas.sandberg@arm.com.. note:: 17211986Sandreas.sandberg@arm.com 17311986Sandreas.sandberg@arm.com When the overridden type returns a reference or pointer to a type that 17411986Sandreas.sandberg@arm.com pybind11 converts from Python (for example, numeric values, std::string, 17511986Sandreas.sandberg@arm.com and other built-in value-converting types), there are some limitations to 17611986Sandreas.sandberg@arm.com be aware of: 17711986Sandreas.sandberg@arm.com 17811986Sandreas.sandberg@arm.com - because in these cases there is no C++ variable to reference (the value 17911986Sandreas.sandberg@arm.com is stored in the referenced Python variable), pybind11 provides one in 18011986Sandreas.sandberg@arm.com the PYBIND11_OVERLOAD macros (when needed) with static storage duration. 18111986Sandreas.sandberg@arm.com Note that this means that invoking the overloaded method on *any* 18211986Sandreas.sandberg@arm.com instance will change the referenced value stored in *all* instances of 18311986Sandreas.sandberg@arm.com that type. 18411986Sandreas.sandberg@arm.com 18511986Sandreas.sandberg@arm.com - Attempts to modify a non-const reference will not have the desired 18611986Sandreas.sandberg@arm.com effect: it will change only the static cache variable, but this change 18711986Sandreas.sandberg@arm.com will not propagate to underlying Python instance, and the change will be 18811986Sandreas.sandberg@arm.com replaced the next time the overload is invoked. 18911986Sandreas.sandberg@arm.com 19011986Sandreas.sandberg@arm.com.. seealso:: 19111986Sandreas.sandberg@arm.com 19211986Sandreas.sandberg@arm.com The file :file:`tests/test_virtual_functions.cpp` contains a complete 19311986Sandreas.sandberg@arm.com example that demonstrates how to override virtual functions using pybind11 19411986Sandreas.sandberg@arm.com in more detail. 19511986Sandreas.sandberg@arm.com 19611986Sandreas.sandberg@arm.com.. _virtual_and_inheritance: 19711986Sandreas.sandberg@arm.com 19811986Sandreas.sandberg@arm.comCombining virtual functions and inheritance 19911986Sandreas.sandberg@arm.com=========================================== 20011986Sandreas.sandberg@arm.com 20111986Sandreas.sandberg@arm.comWhen combining virtual methods with inheritance, you need to be sure to provide 20211986Sandreas.sandberg@arm.coman override for each method for which you want to allow overrides from derived 20311986Sandreas.sandberg@arm.compython classes. For example, suppose we extend the above ``Animal``/``Dog`` 20411986Sandreas.sandberg@arm.comexample as follows: 20511986Sandreas.sandberg@arm.com 20611986Sandreas.sandberg@arm.com.. code-block:: cpp 20711986Sandreas.sandberg@arm.com 20811986Sandreas.sandberg@arm.com class Animal { 20911986Sandreas.sandberg@arm.com public: 21011986Sandreas.sandberg@arm.com virtual std::string go(int n_times) = 0; 21111986Sandreas.sandberg@arm.com virtual std::string name() { return "unknown"; } 21211986Sandreas.sandberg@arm.com }; 21312037Sandreas.sandberg@arm.com class Dog : public Animal { 21411986Sandreas.sandberg@arm.com public: 21511986Sandreas.sandberg@arm.com std::string go(int n_times) override { 21611986Sandreas.sandberg@arm.com std::string result; 21711986Sandreas.sandberg@arm.com for (int i=0; i<n_times; ++i) 21811986Sandreas.sandberg@arm.com result += bark() + " "; 21911986Sandreas.sandberg@arm.com return result; 22011986Sandreas.sandberg@arm.com } 22111986Sandreas.sandberg@arm.com virtual std::string bark() { return "woof!"; } 22211986Sandreas.sandberg@arm.com }; 22311986Sandreas.sandberg@arm.com 22411986Sandreas.sandberg@arm.comthen the trampoline class for ``Animal`` must, as described in the previous 22511986Sandreas.sandberg@arm.comsection, override ``go()`` and ``name()``, but in order to allow python code to 22611986Sandreas.sandberg@arm.cominherit properly from ``Dog``, we also need a trampoline class for ``Dog`` that 22711986Sandreas.sandberg@arm.comoverrides both the added ``bark()`` method *and* the ``go()`` and ``name()`` 22811986Sandreas.sandberg@arm.commethods inherited from ``Animal`` (even though ``Dog`` doesn't directly 22911986Sandreas.sandberg@arm.comoverride the ``name()`` method): 23011986Sandreas.sandberg@arm.com 23111986Sandreas.sandberg@arm.com.. code-block:: cpp 23211986Sandreas.sandberg@arm.com 23311986Sandreas.sandberg@arm.com class PyAnimal : public Animal { 23411986Sandreas.sandberg@arm.com public: 23511986Sandreas.sandberg@arm.com using Animal::Animal; // Inherit constructors 23611986Sandreas.sandberg@arm.com std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Animal, go, n_times); } 23711986Sandreas.sandberg@arm.com std::string name() override { PYBIND11_OVERLOAD(std::string, Animal, name, ); } 23811986Sandreas.sandberg@arm.com }; 23911986Sandreas.sandberg@arm.com class PyDog : public Dog { 24011986Sandreas.sandberg@arm.com public: 24111986Sandreas.sandberg@arm.com using Dog::Dog; // Inherit constructors 24214299Sbbruce@ucdavis.edu std::string go(int n_times) override { PYBIND11_OVERLOAD(std::string, Dog, go, n_times); } 24311986Sandreas.sandberg@arm.com std::string name() override { PYBIND11_OVERLOAD(std::string, Dog, name, ); } 24411986Sandreas.sandberg@arm.com std::string bark() override { PYBIND11_OVERLOAD(std::string, Dog, bark, ); } 24511986Sandreas.sandberg@arm.com }; 24611986Sandreas.sandberg@arm.com 24712037Sandreas.sandberg@arm.com.. note:: 24812037Sandreas.sandberg@arm.com 24912037Sandreas.sandberg@arm.com Note the trailing commas in the ``PYBIND11_OVERLOAD`` calls to ``name()`` 25012037Sandreas.sandberg@arm.com and ``bark()``. These are needed to portably implement a trampoline for a 25112037Sandreas.sandberg@arm.com function that does not take any arguments. For functions that take 25212037Sandreas.sandberg@arm.com a nonzero number of arguments, the trailing comma must be omitted. 25312037Sandreas.sandberg@arm.com 25411986Sandreas.sandberg@arm.comA registered class derived from a pybind11-registered class with virtual 25511986Sandreas.sandberg@arm.commethods requires a similar trampoline class, *even if* it doesn't explicitly 25611986Sandreas.sandberg@arm.comdeclare or override any virtual methods itself: 25711986Sandreas.sandberg@arm.com 25811986Sandreas.sandberg@arm.com.. code-block:: cpp 25911986Sandreas.sandberg@arm.com 26011986Sandreas.sandberg@arm.com class Husky : public Dog {}; 26111986Sandreas.sandberg@arm.com class PyHusky : public Husky { 26212037Sandreas.sandberg@arm.com public: 26312037Sandreas.sandberg@arm.com using Husky::Husky; // Inherit constructors 26411986Sandreas.sandberg@arm.com std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Husky, go, n_times); } 26511986Sandreas.sandberg@arm.com std::string name() override { PYBIND11_OVERLOAD(std::string, Husky, name, ); } 26611986Sandreas.sandberg@arm.com std::string bark() override { PYBIND11_OVERLOAD(std::string, Husky, bark, ); } 26711986Sandreas.sandberg@arm.com }; 26811986Sandreas.sandberg@arm.com 26911986Sandreas.sandberg@arm.comThere is, however, a technique that can be used to avoid this duplication 27011986Sandreas.sandberg@arm.com(which can be especially helpful for a base class with several virtual 27111986Sandreas.sandberg@arm.commethods). The technique involves using template trampoline classes, as 27211986Sandreas.sandberg@arm.comfollows: 27311986Sandreas.sandberg@arm.com 27411986Sandreas.sandberg@arm.com.. code-block:: cpp 27511986Sandreas.sandberg@arm.com 27611986Sandreas.sandberg@arm.com template <class AnimalBase = Animal> class PyAnimal : public AnimalBase { 27712037Sandreas.sandberg@arm.com public: 27811986Sandreas.sandberg@arm.com using AnimalBase::AnimalBase; // Inherit constructors 27911986Sandreas.sandberg@arm.com std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, AnimalBase, go, n_times); } 28011986Sandreas.sandberg@arm.com std::string name() override { PYBIND11_OVERLOAD(std::string, AnimalBase, name, ); } 28111986Sandreas.sandberg@arm.com }; 28211986Sandreas.sandberg@arm.com template <class DogBase = Dog> class PyDog : public PyAnimal<DogBase> { 28312037Sandreas.sandberg@arm.com public: 28411986Sandreas.sandberg@arm.com using PyAnimal<DogBase>::PyAnimal; // Inherit constructors 28511986Sandreas.sandberg@arm.com // Override PyAnimal's pure virtual go() with a non-pure one: 28611986Sandreas.sandberg@arm.com std::string go(int n_times) override { PYBIND11_OVERLOAD(std::string, DogBase, go, n_times); } 28711986Sandreas.sandberg@arm.com std::string bark() override { PYBIND11_OVERLOAD(std::string, DogBase, bark, ); } 28811986Sandreas.sandberg@arm.com }; 28911986Sandreas.sandberg@arm.com 29011986Sandreas.sandberg@arm.comThis technique has the advantage of requiring just one trampoline method to be 29111986Sandreas.sandberg@arm.comdeclared per virtual method and pure virtual method override. It does, 29211986Sandreas.sandberg@arm.comhowever, require the compiler to generate at least as many methods (and 29311986Sandreas.sandberg@arm.compossibly more, if both pure virtual and overridden pure virtual methods are 29411986Sandreas.sandberg@arm.comexposed, as above). 29511986Sandreas.sandberg@arm.com 29611986Sandreas.sandberg@arm.comThe classes are then registered with pybind11 using: 29711986Sandreas.sandberg@arm.com 29811986Sandreas.sandberg@arm.com.. code-block:: cpp 29911986Sandreas.sandberg@arm.com 30011986Sandreas.sandberg@arm.com py::class_<Animal, PyAnimal<>> animal(m, "Animal"); 30111986Sandreas.sandberg@arm.com py::class_<Dog, PyDog<>> dog(m, "Dog"); 30211986Sandreas.sandberg@arm.com py::class_<Husky, PyDog<Husky>> husky(m, "Husky"); 30311986Sandreas.sandberg@arm.com // ... add animal, dog, husky definitions 30411986Sandreas.sandberg@arm.com 30511986Sandreas.sandberg@arm.comNote that ``Husky`` did not require a dedicated trampoline template class at 30611986Sandreas.sandberg@arm.comall, since it neither declares any new virtual methods nor provides any pure 30711986Sandreas.sandberg@arm.comvirtual method implementations. 30811986Sandreas.sandberg@arm.com 30911986Sandreas.sandberg@arm.comWith either the repeated-virtuals or templated trampoline methods in place, you 31011986Sandreas.sandberg@arm.comcan now create a python class that inherits from ``Dog``: 31111986Sandreas.sandberg@arm.com 31211986Sandreas.sandberg@arm.com.. code-block:: python 31311986Sandreas.sandberg@arm.com 31411986Sandreas.sandberg@arm.com class ShihTzu(Dog): 31511986Sandreas.sandberg@arm.com def bark(self): 31611986Sandreas.sandberg@arm.com return "yip!" 31711986Sandreas.sandberg@arm.com 31811986Sandreas.sandberg@arm.com.. seealso:: 31911986Sandreas.sandberg@arm.com 32011986Sandreas.sandberg@arm.com See the file :file:`tests/test_virtual_functions.cpp` for complete examples 32111986Sandreas.sandberg@arm.com using both the duplication and templated trampoline approaches. 32211986Sandreas.sandberg@arm.com 32312391Sjason@lowepower.com.. _extended_aliases: 32412391Sjason@lowepower.com 32511986Sandreas.sandberg@arm.comExtended trampoline class functionality 32611986Sandreas.sandberg@arm.com======================================= 32711986Sandreas.sandberg@arm.com 32814299Sbbruce@ucdavis.edu.. _extended_class_functionality_forced_trampoline: 32914299Sbbruce@ucdavis.edu 33014299Sbbruce@ucdavis.eduForced trampoline class initialisation 33114299Sbbruce@ucdavis.edu-------------------------------------- 33211986Sandreas.sandberg@arm.comThe trampoline classes described in the previous sections are, by default, only 33311986Sandreas.sandberg@arm.cominitialized when needed. More specifically, they are initialized when a python 33411986Sandreas.sandberg@arm.comclass actually inherits from a registered type (instead of merely creating an 33511986Sandreas.sandberg@arm.cominstance of the registered type), or when a registered constructor is only 33611986Sandreas.sandberg@arm.comvalid for the trampoline class but not the registered class. This is primarily 33711986Sandreas.sandberg@arm.comfor performance reasons: when the trampoline class is not needed for anything 33811986Sandreas.sandberg@arm.comexcept virtual method dispatching, not initializing the trampoline class 33911986Sandreas.sandberg@arm.comimproves performance by avoiding needing to do a run-time check to see if the 34011986Sandreas.sandberg@arm.cominheriting python instance has an overloaded method. 34111986Sandreas.sandberg@arm.com 34211986Sandreas.sandberg@arm.comSometimes, however, it is useful to always initialize a trampoline class as an 34311986Sandreas.sandberg@arm.comintermediate class that does more than just handle virtual method dispatching. 34411986Sandreas.sandberg@arm.comFor example, such a class might perform extra class initialization, extra 34511986Sandreas.sandberg@arm.comdestruction operations, and might define new members and methods to enable a 34611986Sandreas.sandberg@arm.commore python-like interface to a class. 34711986Sandreas.sandberg@arm.com 34811986Sandreas.sandberg@arm.comIn order to tell pybind11 that it should *always* initialize the trampoline 34911986Sandreas.sandberg@arm.comclass when creating new instances of a type, the class constructors should be 35011986Sandreas.sandberg@arm.comdeclared using ``py::init_alias<Args, ...>()`` instead of the usual 35111986Sandreas.sandberg@arm.com``py::init<Args, ...>()``. This forces construction via the trampoline class, 35211986Sandreas.sandberg@arm.comensuring member initialization and (eventual) destruction. 35311986Sandreas.sandberg@arm.com 35411986Sandreas.sandberg@arm.com.. seealso:: 35511986Sandreas.sandberg@arm.com 35612391Sjason@lowepower.com See the file :file:`tests/test_virtual_functions.cpp` for complete examples 35711986Sandreas.sandberg@arm.com showing both normal and forced trampoline instantiation. 35811986Sandreas.sandberg@arm.com 35914299Sbbruce@ucdavis.eduDifferent method signatures 36014299Sbbruce@ucdavis.edu--------------------------- 36114299Sbbruce@ucdavis.eduThe macro's introduced in :ref:`overriding_virtuals` cover most of the standard 36214299Sbbruce@ucdavis.eduuse cases when exposing C++ classes to Python. Sometimes it is hard or unwieldy 36314299Sbbruce@ucdavis.eduto create a direct one-on-one mapping between the arguments and method return 36414299Sbbruce@ucdavis.edutype. 36514299Sbbruce@ucdavis.edu 36614299Sbbruce@ucdavis.eduAn example would be when the C++ signature contains output arguments using 36714299Sbbruce@ucdavis.edureferences (See also :ref:`faq_reference_arguments`). Another way of solving 36814299Sbbruce@ucdavis.eduthis is to use the method body of the trampoline class to do conversions to the 36914299Sbbruce@ucdavis.eduinput and return of the Python method. 37014299Sbbruce@ucdavis.edu 37114299Sbbruce@ucdavis.eduThe main building block to do so is the :func:`get_overload`, this function 37214299Sbbruce@ucdavis.eduallows retrieving a method implemented in Python from within the trampoline's 37314299Sbbruce@ucdavis.edumethods. Consider for example a C++ method which has the signature 37414299Sbbruce@ucdavis.edu``bool myMethod(int32_t& value)``, where the return indicates whether 37514299Sbbruce@ucdavis.edusomething should be done with the ``value``. This can be made convenient on the 37614299Sbbruce@ucdavis.eduPython side by allowing the Python function to return ``None`` or an ``int``: 37714299Sbbruce@ucdavis.edu 37814299Sbbruce@ucdavis.edu.. code-block:: cpp 37914299Sbbruce@ucdavis.edu 38014299Sbbruce@ucdavis.edu bool MyClass::myMethod(int32_t& value) 38114299Sbbruce@ucdavis.edu { 38214299Sbbruce@ucdavis.edu pybind11::gil_scoped_acquire gil; // Acquire the GIL while in this scope. 38314299Sbbruce@ucdavis.edu // Try to look up the overloaded method on the Python side. 38414299Sbbruce@ucdavis.edu pybind11::function overload = pybind11::get_overload(this, "myMethod"); 38514299Sbbruce@ucdavis.edu if (overload) { // method is found 38614299Sbbruce@ucdavis.edu auto obj = overload(value); // Call the Python function. 38714299Sbbruce@ucdavis.edu if (py::isinstance<py::int_>(obj)) { // check if it returned a Python integer type 38814299Sbbruce@ucdavis.edu value = obj.cast<int32_t>(); // Cast it and assign it to the value. 38914299Sbbruce@ucdavis.edu return true; // Return true; value should be used. 39014299Sbbruce@ucdavis.edu } else { 39114299Sbbruce@ucdavis.edu return false; // Python returned none, return false. 39214299Sbbruce@ucdavis.edu } 39314299Sbbruce@ucdavis.edu } 39414299Sbbruce@ucdavis.edu return false; // Alternatively return MyClass::myMethod(value); 39514299Sbbruce@ucdavis.edu } 39614299Sbbruce@ucdavis.edu 39714299Sbbruce@ucdavis.edu 39811986Sandreas.sandberg@arm.com.. _custom_constructors: 39911986Sandreas.sandberg@arm.com 40011986Sandreas.sandberg@arm.comCustom constructors 40111986Sandreas.sandberg@arm.com=================== 40211986Sandreas.sandberg@arm.com 40311986Sandreas.sandberg@arm.comThe syntax for binding constructors was previously introduced, but it only 40412391Sjason@lowepower.comworks when a constructor of the appropriate arguments actually exists on the 40512391Sjason@lowepower.comC++ side. To extend this to more general cases, pybind11 makes it possible 40612391Sjason@lowepower.comto bind factory functions as constructors. For example, suppose you have a 40712391Sjason@lowepower.comclass like this: 40811986Sandreas.sandberg@arm.com 40911986Sandreas.sandberg@arm.com.. code-block:: cpp 41011986Sandreas.sandberg@arm.com 41112391Sjason@lowepower.com class Example { 41212391Sjason@lowepower.com private: 41312391Sjason@lowepower.com Example(int); // private constructor 41412391Sjason@lowepower.com public: 41512391Sjason@lowepower.com // Factory function: 41612391Sjason@lowepower.com static Example create(int a) { return Example(a); } 41712391Sjason@lowepower.com }; 41812391Sjason@lowepower.com 41911986Sandreas.sandberg@arm.com py::class_<Example>(m, "Example") 42012391Sjason@lowepower.com .def(py::init(&Example::create)); 42111986Sandreas.sandberg@arm.com 42212391Sjason@lowepower.comWhile it is possible to create a straightforward binding of the static 42312391Sjason@lowepower.com``create`` method, it may sometimes be preferable to expose it as a constructor 42412391Sjason@lowepower.comon the Python side. This can be accomplished by calling ``.def(py::init(...))`` 42512391Sjason@lowepower.comwith the function reference returning the new instance passed as an argument. 42612391Sjason@lowepower.comIt is also possible to use this approach to bind a function returning a new 42712391Sjason@lowepower.cominstance by raw pointer or by the holder (e.g. ``std::unique_ptr``). 42812391Sjason@lowepower.com 42912391Sjason@lowepower.comThe following example shows the different approaches: 43011986Sandreas.sandberg@arm.com 43111986Sandreas.sandberg@arm.com.. code-block:: cpp 43211986Sandreas.sandberg@arm.com 43312391Sjason@lowepower.com class Example { 43412391Sjason@lowepower.com private: 43512391Sjason@lowepower.com Example(int); // private constructor 43612391Sjason@lowepower.com public: 43712391Sjason@lowepower.com // Factory function - returned by value: 43812391Sjason@lowepower.com static Example create(int a) { return Example(a); } 43912391Sjason@lowepower.com 44012391Sjason@lowepower.com // These constructors are publicly callable: 44112391Sjason@lowepower.com Example(double); 44212391Sjason@lowepower.com Example(int, int); 44312391Sjason@lowepower.com Example(std::string); 44412391Sjason@lowepower.com }; 44512391Sjason@lowepower.com 44611986Sandreas.sandberg@arm.com py::class_<Example>(m, "Example") 44712391Sjason@lowepower.com // Bind the factory function as a constructor: 44812391Sjason@lowepower.com .def(py::init(&Example::create)) 44912391Sjason@lowepower.com // Bind a lambda function returning a pointer wrapped in a holder: 45012391Sjason@lowepower.com .def(py::init([](std::string arg) { 45112391Sjason@lowepower.com return std::unique_ptr<Example>(new Example(arg)); 45212391Sjason@lowepower.com })) 45312391Sjason@lowepower.com // Return a raw pointer: 45412391Sjason@lowepower.com .def(py::init([](int a, int b) { return new Example(a, b); })) 45512391Sjason@lowepower.com // You can mix the above with regular C++ constructor bindings as well: 45612391Sjason@lowepower.com .def(py::init<double>()) 45712391Sjason@lowepower.com ; 45811986Sandreas.sandberg@arm.com 45912391Sjason@lowepower.comWhen the constructor is invoked from Python, pybind11 will call the factory 46012391Sjason@lowepower.comfunction and store the resulting C++ instance in the Python instance. 46112391Sjason@lowepower.com 46212391Sjason@lowepower.comWhen combining factory functions constructors with :ref:`virtual function 46312391Sjason@lowepower.comtrampolines <overriding_virtuals>` there are two approaches. The first is to 46412391Sjason@lowepower.comadd a constructor to the alias class that takes a base value by 46512391Sjason@lowepower.comrvalue-reference. If such a constructor is available, it will be used to 46612391Sjason@lowepower.comconstruct an alias instance from the value returned by the factory function. 46712391Sjason@lowepower.comThe second option is to provide two factory functions to ``py::init()``: the 46812391Sjason@lowepower.comfirst will be invoked when no alias class is required (i.e. when the class is 46912391Sjason@lowepower.combeing used but not inherited from in Python), and the second will be invoked 47012391Sjason@lowepower.comwhen an alias is required. 47112391Sjason@lowepower.com 47212391Sjason@lowepower.comYou can also specify a single factory function that always returns an alias 47312391Sjason@lowepower.cominstance: this will result in behaviour similar to ``py::init_alias<...>()``, 47412391Sjason@lowepower.comas described in the :ref:`extended trampoline class documentation 47512391Sjason@lowepower.com<extended_aliases>`. 47612391Sjason@lowepower.com 47712391Sjason@lowepower.comThe following example shows the different factory approaches for a class with 47812391Sjason@lowepower.coman alias: 47912391Sjason@lowepower.com 48012391Sjason@lowepower.com.. code-block:: cpp 48112391Sjason@lowepower.com 48212391Sjason@lowepower.com #include <pybind11/factory.h> 48312391Sjason@lowepower.com class Example { 48412391Sjason@lowepower.com public: 48512391Sjason@lowepower.com // ... 48612391Sjason@lowepower.com virtual ~Example() = default; 48712391Sjason@lowepower.com }; 48812391Sjason@lowepower.com class PyExample : public Example { 48912391Sjason@lowepower.com public: 49012391Sjason@lowepower.com using Example::Example; 49112391Sjason@lowepower.com PyExample(Example &&base) : Example(std::move(base)) {} 49212391Sjason@lowepower.com }; 49312391Sjason@lowepower.com py::class_<Example, PyExample>(m, "Example") 49412391Sjason@lowepower.com // Returns an Example pointer. If a PyExample is needed, the Example 49512391Sjason@lowepower.com // instance will be moved via the extra constructor in PyExample, above. 49612391Sjason@lowepower.com .def(py::init([]() { return new Example(); })) 49712391Sjason@lowepower.com // Two callbacks: 49812391Sjason@lowepower.com .def(py::init([]() { return new Example(); } /* no alias needed */, 49912391Sjason@lowepower.com []() { return new PyExample(); } /* alias needed */)) 50012391Sjason@lowepower.com // *Always* returns an alias instance (like py::init_alias<>()) 50112391Sjason@lowepower.com .def(py::init([]() { return new PyExample(); })) 50212391Sjason@lowepower.com ; 50312391Sjason@lowepower.com 50412391Sjason@lowepower.comBrace initialization 50512391Sjason@lowepower.com-------------------- 50612391Sjason@lowepower.com 50712391Sjason@lowepower.com``pybind11::init<>`` internally uses C++11 brace initialization to call the 50812391Sjason@lowepower.comconstructor of the target class. This means that it can be used to bind 50912391Sjason@lowepower.com*implicit* constructors as well: 51012391Sjason@lowepower.com 51112391Sjason@lowepower.com.. code-block:: cpp 51212391Sjason@lowepower.com 51312391Sjason@lowepower.com struct Aggregate { 51412391Sjason@lowepower.com int a; 51512391Sjason@lowepower.com std::string b; 51612391Sjason@lowepower.com }; 51712391Sjason@lowepower.com 51812391Sjason@lowepower.com py::class_<Aggregate>(m, "Aggregate") 51912391Sjason@lowepower.com .def(py::init<int, const std::string &>()); 52012391Sjason@lowepower.com 52112391Sjason@lowepower.com.. note:: 52212391Sjason@lowepower.com 52312391Sjason@lowepower.com Note that brace initialization preferentially invokes constructor overloads 52412391Sjason@lowepower.com taking a ``std::initializer_list``. In the rare event that this causes an 52512391Sjason@lowepower.com issue, you can work around it by using ``py::init(...)`` with a lambda 52612391Sjason@lowepower.com function that constructs the new object as desired. 52711986Sandreas.sandberg@arm.com 52811986Sandreas.sandberg@arm.com.. _classes_with_non_public_destructors: 52911986Sandreas.sandberg@arm.com 53011986Sandreas.sandberg@arm.comNon-public destructors 53111986Sandreas.sandberg@arm.com====================== 53211986Sandreas.sandberg@arm.com 53311986Sandreas.sandberg@arm.comIf a class has a private or protected destructor (as might e.g. be the case in 53411986Sandreas.sandberg@arm.coma singleton pattern), a compile error will occur when creating bindings via 53511986Sandreas.sandberg@arm.compybind11. The underlying issue is that the ``std::unique_ptr`` holder type that 53611986Sandreas.sandberg@arm.comis responsible for managing the lifetime of instances will reference the 53711986Sandreas.sandberg@arm.comdestructor even if no deallocations ever take place. In order to expose classes 53811986Sandreas.sandberg@arm.comwith private or protected destructors, it is possible to override the holder 53911986Sandreas.sandberg@arm.comtype via a holder type argument to ``class_``. Pybind11 provides a helper class 54011986Sandreas.sandberg@arm.com``py::nodelete`` that disables any destructor invocations. In this case, it is 54111986Sandreas.sandberg@arm.comcrucial that instances are deallocated on the C++ side to avoid memory leaks. 54211986Sandreas.sandberg@arm.com 54311986Sandreas.sandberg@arm.com.. code-block:: cpp 54411986Sandreas.sandberg@arm.com 54511986Sandreas.sandberg@arm.com /* ... definition ... */ 54611986Sandreas.sandberg@arm.com 54711986Sandreas.sandberg@arm.com class MyClass { 54811986Sandreas.sandberg@arm.com private: 54911986Sandreas.sandberg@arm.com ~MyClass() { } 55011986Sandreas.sandberg@arm.com }; 55111986Sandreas.sandberg@arm.com 55211986Sandreas.sandberg@arm.com /* ... binding code ... */ 55311986Sandreas.sandberg@arm.com 55411986Sandreas.sandberg@arm.com py::class_<MyClass, std::unique_ptr<MyClass, py::nodelete>>(m, "MyClass") 55512037Sandreas.sandberg@arm.com .def(py::init<>()) 55612037Sandreas.sandberg@arm.com 55712037Sandreas.sandberg@arm.com.. _implicit_conversions: 55811986Sandreas.sandberg@arm.com 55911986Sandreas.sandberg@arm.comImplicit conversions 56011986Sandreas.sandberg@arm.com==================== 56111986Sandreas.sandberg@arm.com 56211986Sandreas.sandberg@arm.comSuppose that instances of two types ``A`` and ``B`` are used in a project, and 56311986Sandreas.sandberg@arm.comthat an ``A`` can easily be converted into an instance of type ``B`` (examples of this 56411986Sandreas.sandberg@arm.comcould be a fixed and an arbitrary precision number type). 56511986Sandreas.sandberg@arm.com 56611986Sandreas.sandberg@arm.com.. code-block:: cpp 56711986Sandreas.sandberg@arm.com 56811986Sandreas.sandberg@arm.com py::class_<A>(m, "A") 56911986Sandreas.sandberg@arm.com /// ... members ... 57011986Sandreas.sandberg@arm.com 57111986Sandreas.sandberg@arm.com py::class_<B>(m, "B") 57211986Sandreas.sandberg@arm.com .def(py::init<A>()) 57311986Sandreas.sandberg@arm.com /// ... members ... 57411986Sandreas.sandberg@arm.com 57511986Sandreas.sandberg@arm.com m.def("func", 57611986Sandreas.sandberg@arm.com [](const B &) { /* .... */ } 57711986Sandreas.sandberg@arm.com ); 57811986Sandreas.sandberg@arm.com 57911986Sandreas.sandberg@arm.comTo invoke the function ``func`` using a variable ``a`` containing an ``A`` 58011986Sandreas.sandberg@arm.cominstance, we'd have to write ``func(B(a))`` in Python. On the other hand, C++ 58111986Sandreas.sandberg@arm.comwill automatically apply an implicit type conversion, which makes it possible 58211986Sandreas.sandberg@arm.comto directly write ``func(a)``. 58311986Sandreas.sandberg@arm.com 58411986Sandreas.sandberg@arm.comIn this situation (i.e. where ``B`` has a constructor that converts from 58511986Sandreas.sandberg@arm.com``A``), the following statement enables similar implicit conversions on the 58611986Sandreas.sandberg@arm.comPython side: 58711986Sandreas.sandberg@arm.com 58811986Sandreas.sandberg@arm.com.. code-block:: cpp 58911986Sandreas.sandberg@arm.com 59011986Sandreas.sandberg@arm.com py::implicitly_convertible<A, B>(); 59111986Sandreas.sandberg@arm.com 59211986Sandreas.sandberg@arm.com.. note:: 59311986Sandreas.sandberg@arm.com 59411986Sandreas.sandberg@arm.com Implicit conversions from ``A`` to ``B`` only work when ``B`` is a custom 59511986Sandreas.sandberg@arm.com data type that is exposed to Python via pybind11. 59611986Sandreas.sandberg@arm.com 59712391Sjason@lowepower.com To prevent runaway recursion, implicit conversions are non-reentrant: an 59812391Sjason@lowepower.com implicit conversion invoked as part of another implicit conversion of the 59912391Sjason@lowepower.com same type (i.e. from ``A`` to ``B``) will fail. 60012391Sjason@lowepower.com 60111986Sandreas.sandberg@arm.com.. _static_properties: 60211986Sandreas.sandberg@arm.com 60311986Sandreas.sandberg@arm.comStatic properties 60411986Sandreas.sandberg@arm.com================= 60511986Sandreas.sandberg@arm.com 60611986Sandreas.sandberg@arm.comThe section on :ref:`properties` discussed the creation of instance properties 60711986Sandreas.sandberg@arm.comthat are implemented in terms of C++ getters and setters. 60811986Sandreas.sandberg@arm.com 60911986Sandreas.sandberg@arm.comStatic properties can also be created in a similar way to expose getters and 61012037Sandreas.sandberg@arm.comsetters of static class attributes. Note that the implicit ``self`` argument 61112037Sandreas.sandberg@arm.comalso exists in this case and is used to pass the Python ``type`` subclass 61212037Sandreas.sandberg@arm.cominstance. This parameter will often not be needed by the C++ side, and the 61312037Sandreas.sandberg@arm.comfollowing example illustrates how to instantiate a lambda getter function 61412037Sandreas.sandberg@arm.comthat ignores it: 61511986Sandreas.sandberg@arm.com 61611986Sandreas.sandberg@arm.com.. code-block:: cpp 61711986Sandreas.sandberg@arm.com 61811986Sandreas.sandberg@arm.com py::class_<Foo>(m, "Foo") 61911986Sandreas.sandberg@arm.com .def_property_readonly_static("foo", [](py::object /* self */) { return Foo(); }); 62011986Sandreas.sandberg@arm.com 62111986Sandreas.sandberg@arm.comOperator overloading 62211986Sandreas.sandberg@arm.com==================== 62311986Sandreas.sandberg@arm.com 62411986Sandreas.sandberg@arm.comSuppose that we're given the following ``Vector2`` class with a vector addition 62511986Sandreas.sandberg@arm.comand scalar multiplication operation, all implemented using overloaded operators 62611986Sandreas.sandberg@arm.comin C++. 62711986Sandreas.sandberg@arm.com 62811986Sandreas.sandberg@arm.com.. code-block:: cpp 62911986Sandreas.sandberg@arm.com 63011986Sandreas.sandberg@arm.com class Vector2 { 63111986Sandreas.sandberg@arm.com public: 63211986Sandreas.sandberg@arm.com Vector2(float x, float y) : x(x), y(y) { } 63311986Sandreas.sandberg@arm.com 63411986Sandreas.sandberg@arm.com Vector2 operator+(const Vector2 &v) const { return Vector2(x + v.x, y + v.y); } 63511986Sandreas.sandberg@arm.com Vector2 operator*(float value) const { return Vector2(x * value, y * value); } 63611986Sandreas.sandberg@arm.com Vector2& operator+=(const Vector2 &v) { x += v.x; y += v.y; return *this; } 63711986Sandreas.sandberg@arm.com Vector2& operator*=(float v) { x *= v; y *= v; return *this; } 63811986Sandreas.sandberg@arm.com 63911986Sandreas.sandberg@arm.com friend Vector2 operator*(float f, const Vector2 &v) { 64011986Sandreas.sandberg@arm.com return Vector2(f * v.x, f * v.y); 64111986Sandreas.sandberg@arm.com } 64211986Sandreas.sandberg@arm.com 64311986Sandreas.sandberg@arm.com std::string toString() const { 64411986Sandreas.sandberg@arm.com return "[" + std::to_string(x) + ", " + std::to_string(y) + "]"; 64511986Sandreas.sandberg@arm.com } 64611986Sandreas.sandberg@arm.com private: 64711986Sandreas.sandberg@arm.com float x, y; 64811986Sandreas.sandberg@arm.com }; 64911986Sandreas.sandberg@arm.com 65011986Sandreas.sandberg@arm.comThe following snippet shows how the above operators can be conveniently exposed 65111986Sandreas.sandberg@arm.comto Python. 65211986Sandreas.sandberg@arm.com 65311986Sandreas.sandberg@arm.com.. code-block:: cpp 65411986Sandreas.sandberg@arm.com 65511986Sandreas.sandberg@arm.com #include <pybind11/operators.h> 65611986Sandreas.sandberg@arm.com 65712391Sjason@lowepower.com PYBIND11_MODULE(example, m) { 65811986Sandreas.sandberg@arm.com py::class_<Vector2>(m, "Vector2") 65911986Sandreas.sandberg@arm.com .def(py::init<float, float>()) 66011986Sandreas.sandberg@arm.com .def(py::self + py::self) 66111986Sandreas.sandberg@arm.com .def(py::self += py::self) 66211986Sandreas.sandberg@arm.com .def(py::self *= float()) 66311986Sandreas.sandberg@arm.com .def(float() * py::self) 66412037Sandreas.sandberg@arm.com .def(py::self * float()) 66514299Sbbruce@ucdavis.edu .def(-py::self) 66611986Sandreas.sandberg@arm.com .def("__repr__", &Vector2::toString); 66711986Sandreas.sandberg@arm.com } 66811986Sandreas.sandberg@arm.com 66911986Sandreas.sandberg@arm.comNote that a line like 67011986Sandreas.sandberg@arm.com 67111986Sandreas.sandberg@arm.com.. code-block:: cpp 67211986Sandreas.sandberg@arm.com 67311986Sandreas.sandberg@arm.com .def(py::self * float()) 67411986Sandreas.sandberg@arm.com 67511986Sandreas.sandberg@arm.comis really just short hand notation for 67611986Sandreas.sandberg@arm.com 67711986Sandreas.sandberg@arm.com.. code-block:: cpp 67811986Sandreas.sandberg@arm.com 67911986Sandreas.sandberg@arm.com .def("__mul__", [](const Vector2 &a, float b) { 68011986Sandreas.sandberg@arm.com return a * b; 68111986Sandreas.sandberg@arm.com }, py::is_operator()) 68211986Sandreas.sandberg@arm.com 68311986Sandreas.sandberg@arm.comThis can be useful for exposing additional operators that don't exist on the 68411986Sandreas.sandberg@arm.comC++ side, or to perform other types of customization. The ``py::is_operator`` 68511986Sandreas.sandberg@arm.comflag marker is needed to inform pybind11 that this is an operator, which 68611986Sandreas.sandberg@arm.comreturns ``NotImplemented`` when invoked with incompatible arguments rather than 68711986Sandreas.sandberg@arm.comthrowing a type error. 68811986Sandreas.sandberg@arm.com 68911986Sandreas.sandberg@arm.com.. note:: 69011986Sandreas.sandberg@arm.com 69111986Sandreas.sandberg@arm.com To use the more convenient ``py::self`` notation, the additional 69211986Sandreas.sandberg@arm.com header file :file:`pybind11/operators.h` must be included. 69311986Sandreas.sandberg@arm.com 69411986Sandreas.sandberg@arm.com.. seealso:: 69511986Sandreas.sandberg@arm.com 69611986Sandreas.sandberg@arm.com The file :file:`tests/test_operator_overloading.cpp` contains a 69711986Sandreas.sandberg@arm.com complete example that demonstrates how to work with overloaded operators in 69811986Sandreas.sandberg@arm.com more detail. 69911986Sandreas.sandberg@arm.com 70012391Sjason@lowepower.com.. _pickling: 70112391Sjason@lowepower.com 70211986Sandreas.sandberg@arm.comPickling support 70311986Sandreas.sandberg@arm.com================ 70411986Sandreas.sandberg@arm.com 70511986Sandreas.sandberg@arm.comPython's ``pickle`` module provides a powerful facility to serialize and 70611986Sandreas.sandberg@arm.comde-serialize a Python object graph into a binary data stream. To pickle and 70712391Sjason@lowepower.comunpickle C++ classes using pybind11, a ``py::pickle()`` definition must be 70812391Sjason@lowepower.comprovided. Suppose the class in question has the following signature: 70911986Sandreas.sandberg@arm.com 71011986Sandreas.sandberg@arm.com.. code-block:: cpp 71111986Sandreas.sandberg@arm.com 71211986Sandreas.sandberg@arm.com class Pickleable { 71311986Sandreas.sandberg@arm.com public: 71411986Sandreas.sandberg@arm.com Pickleable(const std::string &value) : m_value(value) { } 71511986Sandreas.sandberg@arm.com const std::string &value() const { return m_value; } 71611986Sandreas.sandberg@arm.com 71711986Sandreas.sandberg@arm.com void setExtra(int extra) { m_extra = extra; } 71811986Sandreas.sandberg@arm.com int extra() const { return m_extra; } 71911986Sandreas.sandberg@arm.com private: 72011986Sandreas.sandberg@arm.com std::string m_value; 72111986Sandreas.sandberg@arm.com int m_extra = 0; 72211986Sandreas.sandberg@arm.com }; 72311986Sandreas.sandberg@arm.com 72412391Sjason@lowepower.comPickling support in Python is enabled by defining the ``__setstate__`` and 72512391Sjason@lowepower.com``__getstate__`` methods [#f3]_. For pybind11 classes, use ``py::pickle()`` 72612391Sjason@lowepower.comto bind these two functions: 72711986Sandreas.sandberg@arm.com 72811986Sandreas.sandberg@arm.com.. code-block:: cpp 72911986Sandreas.sandberg@arm.com 73011986Sandreas.sandberg@arm.com py::class_<Pickleable>(m, "Pickleable") 73111986Sandreas.sandberg@arm.com .def(py::init<std::string>()) 73211986Sandreas.sandberg@arm.com .def("value", &Pickleable::value) 73311986Sandreas.sandberg@arm.com .def("extra", &Pickleable::extra) 73411986Sandreas.sandberg@arm.com .def("setExtra", &Pickleable::setExtra) 73512391Sjason@lowepower.com .def(py::pickle( 73612391Sjason@lowepower.com [](const Pickleable &p) { // __getstate__ 73712391Sjason@lowepower.com /* Return a tuple that fully encodes the state of the object */ 73812391Sjason@lowepower.com return py::make_tuple(p.value(), p.extra()); 73912391Sjason@lowepower.com }, 74012391Sjason@lowepower.com [](py::tuple t) { // __setstate__ 74112391Sjason@lowepower.com if (t.size() != 2) 74212391Sjason@lowepower.com throw std::runtime_error("Invalid state!"); 74311986Sandreas.sandberg@arm.com 74412391Sjason@lowepower.com /* Create a new C++ instance */ 74512391Sjason@lowepower.com Pickleable p(t[0].cast<std::string>()); 74611986Sandreas.sandberg@arm.com 74712391Sjason@lowepower.com /* Assign any additional state */ 74812391Sjason@lowepower.com p.setExtra(t[1].cast<int>()); 74912391Sjason@lowepower.com 75012391Sjason@lowepower.com return p; 75112391Sjason@lowepower.com } 75212391Sjason@lowepower.com )); 75312391Sjason@lowepower.com 75412391Sjason@lowepower.comThe ``__setstate__`` part of the ``py::picke()`` definition follows the same 75512391Sjason@lowepower.comrules as the single-argument version of ``py::init()``. The return type can be 75612391Sjason@lowepower.coma value, pointer or holder type. See :ref:`custom_constructors` for details. 75711986Sandreas.sandberg@arm.com 75811986Sandreas.sandberg@arm.comAn instance can now be pickled as follows: 75911986Sandreas.sandberg@arm.com 76011986Sandreas.sandberg@arm.com.. code-block:: python 76111986Sandreas.sandberg@arm.com 76211986Sandreas.sandberg@arm.com try: 76311986Sandreas.sandberg@arm.com import cPickle as pickle # Use cPickle on Python 2.7 76411986Sandreas.sandberg@arm.com except ImportError: 76511986Sandreas.sandberg@arm.com import pickle 76611986Sandreas.sandberg@arm.com 76711986Sandreas.sandberg@arm.com p = Pickleable("test_value") 76811986Sandreas.sandberg@arm.com p.setExtra(15) 76911986Sandreas.sandberg@arm.com data = pickle.dumps(p, 2) 77011986Sandreas.sandberg@arm.com 77111986Sandreas.sandberg@arm.comNote that only the cPickle module is supported on Python 2.7. The second 77211986Sandreas.sandberg@arm.comargument to ``dumps`` is also crucial: it selects the pickle protocol version 77311986Sandreas.sandberg@arm.com2, since the older version 1 is not supported. Newer versions are also fine—for 77411986Sandreas.sandberg@arm.cominstance, specify ``-1`` to always use the latest available version. Beware: 77511986Sandreas.sandberg@arm.comfailure to follow these instructions will cause important pybind11 memory 77611986Sandreas.sandberg@arm.comallocation routines to be skipped during unpickling, which will likely lead to 77711986Sandreas.sandberg@arm.commemory corruption and/or segmentation faults. 77811986Sandreas.sandberg@arm.com 77911986Sandreas.sandberg@arm.com.. seealso:: 78011986Sandreas.sandberg@arm.com 78111986Sandreas.sandberg@arm.com The file :file:`tests/test_pickling.cpp` contains a complete example 78211986Sandreas.sandberg@arm.com that demonstrates how to pickle and unpickle types using pybind11 in more 78311986Sandreas.sandberg@arm.com detail. 78411986Sandreas.sandberg@arm.com 78511986Sandreas.sandberg@arm.com.. [#f3] http://docs.python.org/3/library/pickle.html#pickling-class-instances 78611986Sandreas.sandberg@arm.com 78711986Sandreas.sandberg@arm.comMultiple Inheritance 78811986Sandreas.sandberg@arm.com==================== 78911986Sandreas.sandberg@arm.com 79011986Sandreas.sandberg@arm.compybind11 can create bindings for types that derive from multiple base types 79111986Sandreas.sandberg@arm.com(aka. *multiple inheritance*). To do so, specify all bases in the template 79211986Sandreas.sandberg@arm.comarguments of the ``class_`` declaration: 79311986Sandreas.sandberg@arm.com 79411986Sandreas.sandberg@arm.com.. code-block:: cpp 79511986Sandreas.sandberg@arm.com 79611986Sandreas.sandberg@arm.com py::class_<MyType, BaseType1, BaseType2, BaseType3>(m, "MyType") 79711986Sandreas.sandberg@arm.com ... 79811986Sandreas.sandberg@arm.com 79911986Sandreas.sandberg@arm.comThe base types can be specified in arbitrary order, and they can even be 80011986Sandreas.sandberg@arm.cominterspersed with alias types and holder types (discussed earlier in this 80111986Sandreas.sandberg@arm.comdocument)---pybind11 will automatically find out which is which. The only 80211986Sandreas.sandberg@arm.comrequirement is that the first template argument is the type to be declared. 80311986Sandreas.sandberg@arm.com 80412391Sjason@lowepower.comIt is also permitted to inherit multiply from exported C++ classes in Python, 80514299Sbbruce@ucdavis.eduas well as inheriting from multiple Python and/or pybind11-exported classes. 80611986Sandreas.sandberg@arm.com 80712391Sjason@lowepower.comThere is one caveat regarding the implementation of this feature: 80811986Sandreas.sandberg@arm.com 80912391Sjason@lowepower.comWhen only one base type is specified for a C++ type that actually has multiple 81012391Sjason@lowepower.combases, pybind11 will assume that it does not participate in multiple 81112391Sjason@lowepower.cominheritance, which can lead to undefined behavior. In such cases, add the tag 81212391Sjason@lowepower.com``multiple_inheritance`` to the class constructor: 81311986Sandreas.sandberg@arm.com 81412391Sjason@lowepower.com.. code-block:: cpp 81511986Sandreas.sandberg@arm.com 81612391Sjason@lowepower.com py::class_<MyType, BaseType2>(m, "MyType", py::multiple_inheritance()); 81711986Sandreas.sandberg@arm.com 81812391Sjason@lowepower.comThe tag is redundant and does not need to be specified when multiple base types 81912391Sjason@lowepower.comare listed. 82012391Sjason@lowepower.com 82112391Sjason@lowepower.com.. _module_local: 82212391Sjason@lowepower.com 82312391Sjason@lowepower.comModule-local class bindings 82412391Sjason@lowepower.com=========================== 82512391Sjason@lowepower.com 82614299Sbbruce@ucdavis.eduWhen creating a binding for a class, pybind11 by default makes that binding 82712391Sjason@lowepower.com"global" across modules. What this means is that a type defined in one module 82812391Sjason@lowepower.comcan be returned from any module resulting in the same Python type. For 82912391Sjason@lowepower.comexample, this allows the following: 83012391Sjason@lowepower.com 83112391Sjason@lowepower.com.. code-block:: cpp 83212391Sjason@lowepower.com 83312391Sjason@lowepower.com // In the module1.cpp binding code for module1: 83412391Sjason@lowepower.com py::class_<Pet>(m, "Pet") 83512391Sjason@lowepower.com .def(py::init<std::string>()) 83612391Sjason@lowepower.com .def_readonly("name", &Pet::name); 83712391Sjason@lowepower.com 83812391Sjason@lowepower.com.. code-block:: cpp 83912391Sjason@lowepower.com 84012391Sjason@lowepower.com // In the module2.cpp binding code for module2: 84112391Sjason@lowepower.com m.def("create_pet", [](std::string name) { return new Pet(name); }); 84212391Sjason@lowepower.com 84312391Sjason@lowepower.com.. code-block:: pycon 84412391Sjason@lowepower.com 84512391Sjason@lowepower.com >>> from module1 import Pet 84612391Sjason@lowepower.com >>> from module2 import create_pet 84712391Sjason@lowepower.com >>> pet1 = Pet("Kitty") 84812391Sjason@lowepower.com >>> pet2 = create_pet("Doggy") 84912391Sjason@lowepower.com >>> pet2.name() 85012391Sjason@lowepower.com 'Doggy' 85112391Sjason@lowepower.com 85212391Sjason@lowepower.comWhen writing binding code for a library, this is usually desirable: this 85312391Sjason@lowepower.comallows, for example, splitting up a complex library into multiple Python 85412391Sjason@lowepower.commodules. 85512391Sjason@lowepower.com 85612391Sjason@lowepower.comIn some cases, however, this can cause conflicts. For example, suppose two 85712391Sjason@lowepower.comunrelated modules make use of an external C++ library and each provide custom 85812391Sjason@lowepower.combindings for one of that library's classes. This will result in an error when 85912391Sjason@lowepower.coma Python program attempts to import both modules (directly or indirectly) 86012391Sjason@lowepower.combecause of conflicting definitions on the external type: 86112391Sjason@lowepower.com 86212391Sjason@lowepower.com.. code-block:: cpp 86312391Sjason@lowepower.com 86412391Sjason@lowepower.com // dogs.cpp 86512391Sjason@lowepower.com 86612391Sjason@lowepower.com // Binding for external library class: 86712391Sjason@lowepower.com py::class<pets::Pet>(m, "Pet") 86812391Sjason@lowepower.com .def("name", &pets::Pet::name); 86912391Sjason@lowepower.com 87012391Sjason@lowepower.com // Binding for local extension class: 87112391Sjason@lowepower.com py::class<Dog, pets::Pet>(m, "Dog") 87212391Sjason@lowepower.com .def(py::init<std::string>()); 87312391Sjason@lowepower.com 87412391Sjason@lowepower.com.. code-block:: cpp 87512391Sjason@lowepower.com 87612391Sjason@lowepower.com // cats.cpp, in a completely separate project from the above dogs.cpp. 87712391Sjason@lowepower.com 87812391Sjason@lowepower.com // Binding for external library class: 87912391Sjason@lowepower.com py::class<pets::Pet>(m, "Pet") 88012391Sjason@lowepower.com .def("get_name", &pets::Pet::name); 88112391Sjason@lowepower.com 88212391Sjason@lowepower.com // Binding for local extending class: 88312391Sjason@lowepower.com py::class<Cat, pets::Pet>(m, "Cat") 88412391Sjason@lowepower.com .def(py::init<std::string>()); 88512391Sjason@lowepower.com 88612391Sjason@lowepower.com.. code-block:: pycon 88712391Sjason@lowepower.com 88812391Sjason@lowepower.com >>> import cats 88912391Sjason@lowepower.com >>> import dogs 89012391Sjason@lowepower.com Traceback (most recent call last): 89112391Sjason@lowepower.com File "<stdin>", line 1, in <module> 89212391Sjason@lowepower.com ImportError: generic_type: type "Pet" is already registered! 89312391Sjason@lowepower.com 89412391Sjason@lowepower.comTo get around this, you can tell pybind11 to keep the external class binding 89512391Sjason@lowepower.comlocalized to the module by passing the ``py::module_local()`` attribute into 89612391Sjason@lowepower.comthe ``py::class_`` constructor: 89712391Sjason@lowepower.com 89812391Sjason@lowepower.com.. code-block:: cpp 89912391Sjason@lowepower.com 90012391Sjason@lowepower.com // Pet binding in dogs.cpp: 90112391Sjason@lowepower.com py::class<pets::Pet>(m, "Pet", py::module_local()) 90212391Sjason@lowepower.com .def("name", &pets::Pet::name); 90312391Sjason@lowepower.com 90412391Sjason@lowepower.com.. code-block:: cpp 90512391Sjason@lowepower.com 90612391Sjason@lowepower.com // Pet binding in cats.cpp: 90712391Sjason@lowepower.com py::class<pets::Pet>(m, "Pet", py::module_local()) 90812391Sjason@lowepower.com .def("get_name", &pets::Pet::name); 90912391Sjason@lowepower.com 91012391Sjason@lowepower.comThis makes the Python-side ``dogs.Pet`` and ``cats.Pet`` into distinct classes, 91112391Sjason@lowepower.comavoiding the conflict and allowing both modules to be loaded. C++ code in the 91212391Sjason@lowepower.com``dogs`` module that casts or returns a ``Pet`` instance will result in a 91312391Sjason@lowepower.com``dogs.Pet`` Python instance, while C++ code in the ``cats`` module will result 91412391Sjason@lowepower.comin a ``cats.Pet`` Python instance. 91512391Sjason@lowepower.com 91612391Sjason@lowepower.comThis does come with two caveats, however: First, external modules cannot return 91712391Sjason@lowepower.comor cast a ``Pet`` instance to Python (unless they also provide their own local 91812391Sjason@lowepower.combindings). Second, from the Python point of view they are two distinct classes. 91912391Sjason@lowepower.com 92012391Sjason@lowepower.comNote that the locality only applies in the C++ -> Python direction. When 92112391Sjason@lowepower.compassing such a ``py::module_local`` type into a C++ function, the module-local 92212391Sjason@lowepower.comclasses are still considered. This means that if the following function is 92312391Sjason@lowepower.comadded to any module (including but not limited to the ``cats`` and ``dogs`` 92412391Sjason@lowepower.commodules above) it will be callable with either a ``dogs.Pet`` or ``cats.Pet`` 92512391Sjason@lowepower.comargument: 92612391Sjason@lowepower.com 92712391Sjason@lowepower.com.. code-block:: cpp 92812391Sjason@lowepower.com 92912391Sjason@lowepower.com m.def("pet_name", [](const pets::Pet &pet) { return pet.name(); }); 93012391Sjason@lowepower.com 93112391Sjason@lowepower.comFor example, suppose the above function is added to each of ``cats.cpp``, 93212391Sjason@lowepower.com``dogs.cpp`` and ``frogs.cpp`` (where ``frogs.cpp`` is some other module that 93312391Sjason@lowepower.comdoes *not* bind ``Pets`` at all). 93412391Sjason@lowepower.com 93512391Sjason@lowepower.com.. code-block:: pycon 93612391Sjason@lowepower.com 93712391Sjason@lowepower.com >>> import cats, dogs, frogs # No error because of the added py::module_local() 93812391Sjason@lowepower.com >>> mycat, mydog = cats.Cat("Fluffy"), dogs.Dog("Rover") 93912391Sjason@lowepower.com >>> (cats.pet_name(mycat), dogs.pet_name(mydog)) 94012391Sjason@lowepower.com ('Fluffy', 'Rover') 94112391Sjason@lowepower.com >>> (cats.pet_name(mydog), dogs.pet_name(mycat), frogs.pet_name(mycat)) 94212391Sjason@lowepower.com ('Rover', 'Fluffy', 'Fluffy') 94312391Sjason@lowepower.com 94412391Sjason@lowepower.comIt is possible to use ``py::module_local()`` registrations in one module even 94512391Sjason@lowepower.comif another module registers the same type globally: within the module with the 94612391Sjason@lowepower.commodule-local definition, all C++ instances will be cast to the associated bound 94712391Sjason@lowepower.comPython type. In other modules any such values are converted to the global 94812391Sjason@lowepower.comPython type created elsewhere. 94912391Sjason@lowepower.com 95012391Sjason@lowepower.com.. note:: 95112391Sjason@lowepower.com 95212391Sjason@lowepower.com STL bindings (as provided via the optional :file:`pybind11/stl_bind.h` 95312391Sjason@lowepower.com header) apply ``py::module_local`` by default when the bound type might 95412391Sjason@lowepower.com conflict with other modules; see :ref:`stl_bind` for details. 95512391Sjason@lowepower.com 95612391Sjason@lowepower.com.. note:: 95712391Sjason@lowepower.com 95812391Sjason@lowepower.com The localization of the bound types is actually tied to the shared object 95912391Sjason@lowepower.com or binary generated by the compiler/linker. For typical modules created 96012391Sjason@lowepower.com with ``PYBIND11_MODULE()``, this distinction is not significant. It is 96112391Sjason@lowepower.com possible, however, when :ref:`embedding` to embed multiple modules in the 96212391Sjason@lowepower.com same binary (see :ref:`embedding_modules`). In such a case, the 96312391Sjason@lowepower.com localization will apply across all embedded modules within the same binary. 96412391Sjason@lowepower.com 96512391Sjason@lowepower.com.. seealso:: 96612391Sjason@lowepower.com 96712391Sjason@lowepower.com The file :file:`tests/test_local_bindings.cpp` contains additional examples 96812391Sjason@lowepower.com that demonstrate how ``py::module_local()`` works. 96912391Sjason@lowepower.com 97012391Sjason@lowepower.comBinding protected member functions 97112391Sjason@lowepower.com================================== 97212391Sjason@lowepower.com 97312391Sjason@lowepower.comIt's normally not possible to expose ``protected`` member functions to Python: 97412391Sjason@lowepower.com 97512391Sjason@lowepower.com.. code-block:: cpp 97612391Sjason@lowepower.com 97712391Sjason@lowepower.com class A { 97812391Sjason@lowepower.com protected: 97912391Sjason@lowepower.com int foo() const { return 42; } 98012391Sjason@lowepower.com }; 98112391Sjason@lowepower.com 98212391Sjason@lowepower.com py::class_<A>(m, "A") 98312391Sjason@lowepower.com .def("foo", &A::foo); // error: 'foo' is a protected member of 'A' 98412391Sjason@lowepower.com 98512391Sjason@lowepower.comOn one hand, this is good because non-``public`` members aren't meant to be 98612391Sjason@lowepower.comaccessed from the outside. But we may want to make use of ``protected`` 98712391Sjason@lowepower.comfunctions in derived Python classes. 98812391Sjason@lowepower.com 98912391Sjason@lowepower.comThe following pattern makes this possible: 99012391Sjason@lowepower.com 99112391Sjason@lowepower.com.. code-block:: cpp 99212391Sjason@lowepower.com 99312391Sjason@lowepower.com class A { 99412391Sjason@lowepower.com protected: 99512391Sjason@lowepower.com int foo() const { return 42; } 99612391Sjason@lowepower.com }; 99712391Sjason@lowepower.com 99812391Sjason@lowepower.com class Publicist : public A { // helper type for exposing protected functions 99912391Sjason@lowepower.com public: 100012391Sjason@lowepower.com using A::foo; // inherited with different access modifier 100112391Sjason@lowepower.com }; 100212391Sjason@lowepower.com 100312391Sjason@lowepower.com py::class_<A>(m, "A") // bind the primary class 100412391Sjason@lowepower.com .def("foo", &Publicist::foo); // expose protected methods via the publicist 100512391Sjason@lowepower.com 100612391Sjason@lowepower.comThis works because ``&Publicist::foo`` is exactly the same function as 100712391Sjason@lowepower.com``&A::foo`` (same signature and address), just with a different access 100812391Sjason@lowepower.commodifier. The only purpose of the ``Publicist`` helper class is to make 100912391Sjason@lowepower.comthe function name ``public``. 101012391Sjason@lowepower.com 101112391Sjason@lowepower.comIf the intent is to expose ``protected`` ``virtual`` functions which can be 101212391Sjason@lowepower.comoverridden in Python, the publicist pattern can be combined with the previously 101312391Sjason@lowepower.comdescribed trampoline: 101412391Sjason@lowepower.com 101512391Sjason@lowepower.com.. code-block:: cpp 101612391Sjason@lowepower.com 101712391Sjason@lowepower.com class A { 101812391Sjason@lowepower.com public: 101912391Sjason@lowepower.com virtual ~A() = default; 102012391Sjason@lowepower.com 102112391Sjason@lowepower.com protected: 102212391Sjason@lowepower.com virtual int foo() const { return 42; } 102312391Sjason@lowepower.com }; 102412391Sjason@lowepower.com 102512391Sjason@lowepower.com class Trampoline : public A { 102612391Sjason@lowepower.com public: 102712391Sjason@lowepower.com int foo() const override { PYBIND11_OVERLOAD(int, A, foo, ); } 102812391Sjason@lowepower.com }; 102912391Sjason@lowepower.com 103012391Sjason@lowepower.com class Publicist : public A { 103112391Sjason@lowepower.com public: 103212391Sjason@lowepower.com using A::foo; 103312391Sjason@lowepower.com }; 103412391Sjason@lowepower.com 103512391Sjason@lowepower.com py::class_<A, Trampoline>(m, "A") // <-- `Trampoline` here 103612391Sjason@lowepower.com .def("foo", &Publicist::foo); // <-- `Publicist` here, not `Trampoline`! 103712391Sjason@lowepower.com 103812391Sjason@lowepower.com.. note:: 103912391Sjason@lowepower.com 104012391Sjason@lowepower.com MSVC 2015 has a compiler bug (fixed in version 2017) which 104112391Sjason@lowepower.com requires a more explicit function binding in the form of 104212391Sjason@lowepower.com ``.def("foo", static_cast<int (A::*)() const>(&Publicist::foo));`` 104312391Sjason@lowepower.com where ``int (A::*)() const`` is the type of ``A::foo``. 104414299Sbbruce@ucdavis.edu 104514299Sbbruce@ucdavis.eduCustom automatic downcasters 104614299Sbbruce@ucdavis.edu============================ 104714299Sbbruce@ucdavis.edu 104814299Sbbruce@ucdavis.eduAs explained in :ref:`inheritance`, pybind11 comes with built-in 104914299Sbbruce@ucdavis.eduunderstanding of the dynamic type of polymorphic objects in C++; that 105014299Sbbruce@ucdavis.eduis, returning a Pet to Python produces a Python object that knows it's 105114299Sbbruce@ucdavis.eduwrapping a Dog, if Pet has virtual methods and pybind11 knows about 105214299Sbbruce@ucdavis.eduDog and this Pet is in fact a Dog. Sometimes, you might want to 105314299Sbbruce@ucdavis.eduprovide this automatic downcasting behavior when creating bindings for 105414299Sbbruce@ucdavis.edua class hierarchy that does not use standard C++ polymorphism, such as 105514299Sbbruce@ucdavis.eduLLVM [#f4]_. As long as there's some way to determine at runtime 105614299Sbbruce@ucdavis.eduwhether a downcast is safe, you can proceed by specializing the 105714299Sbbruce@ucdavis.edu``pybind11::polymorphic_type_hook`` template: 105814299Sbbruce@ucdavis.edu 105914299Sbbruce@ucdavis.edu.. code-block:: cpp 106014299Sbbruce@ucdavis.edu 106114299Sbbruce@ucdavis.edu enum class PetKind { Cat, Dog, Zebra }; 106214299Sbbruce@ucdavis.edu struct Pet { // Not polymorphic: has no virtual methods 106314299Sbbruce@ucdavis.edu const PetKind kind; 106414299Sbbruce@ucdavis.edu int age = 0; 106514299Sbbruce@ucdavis.edu protected: 106614299Sbbruce@ucdavis.edu Pet(PetKind _kind) : kind(_kind) {} 106714299Sbbruce@ucdavis.edu }; 106814299Sbbruce@ucdavis.edu struct Dog : Pet { 106914299Sbbruce@ucdavis.edu Dog() : Pet(PetKind::Dog) {} 107014299Sbbruce@ucdavis.edu std::string sound = "woof!"; 107114299Sbbruce@ucdavis.edu std::string bark() const { return sound; } 107214299Sbbruce@ucdavis.edu }; 107314299Sbbruce@ucdavis.edu 107414299Sbbruce@ucdavis.edu namespace pybind11 { 107514299Sbbruce@ucdavis.edu template<> struct polymorphic_type_hook<Pet> { 107614299Sbbruce@ucdavis.edu static const void *get(const Pet *src, const std::type_info*& type) { 107714299Sbbruce@ucdavis.edu // note that src may be nullptr 107814299Sbbruce@ucdavis.edu if (src && src->kind == PetKind::Dog) { 107914299Sbbruce@ucdavis.edu type = &typeid(Dog); 108014299Sbbruce@ucdavis.edu return static_cast<const Dog*>(src); 108114299Sbbruce@ucdavis.edu } 108214299Sbbruce@ucdavis.edu return src; 108314299Sbbruce@ucdavis.edu } 108414299Sbbruce@ucdavis.edu }; 108514299Sbbruce@ucdavis.edu } // namespace pybind11 108614299Sbbruce@ucdavis.edu 108714299Sbbruce@ucdavis.eduWhen pybind11 wants to convert a C++ pointer of type ``Base*`` to a 108814299Sbbruce@ucdavis.eduPython object, it calls ``polymorphic_type_hook<Base>::get()`` to 108914299Sbbruce@ucdavis.edudetermine if a downcast is possible. The ``get()`` function should use 109014299Sbbruce@ucdavis.eduwhatever runtime information is available to determine if its ``src`` 109114299Sbbruce@ucdavis.eduparameter is in fact an instance of some class ``Derived`` that 109214299Sbbruce@ucdavis.eduinherits from ``Base``. If it finds such a ``Derived``, it sets ``type 109314299Sbbruce@ucdavis.edu= &typeid(Derived)`` and returns a pointer to the ``Derived`` object 109414299Sbbruce@ucdavis.eduthat contains ``src``. Otherwise, it just returns ``src``, leaving 109514299Sbbruce@ucdavis.edu``type`` at its default value of nullptr. If you set ``type`` to a 109614299Sbbruce@ucdavis.edutype that pybind11 doesn't know about, no downcasting will occur, and 109714299Sbbruce@ucdavis.eduthe original ``src`` pointer will be used with its static type 109814299Sbbruce@ucdavis.edu``Base*``. 109914299Sbbruce@ucdavis.edu 110014299Sbbruce@ucdavis.eduIt is critical that the returned pointer and ``type`` argument of 110114299Sbbruce@ucdavis.edu``get()`` agree with each other: if ``type`` is set to something 110214299Sbbruce@ucdavis.edunon-null, the returned pointer must point to the start of an object 110314299Sbbruce@ucdavis.eduwhose type is ``type``. If the hierarchy being exposed uses only 110414299Sbbruce@ucdavis.edusingle inheritance, a simple ``return src;`` will achieve this just 110514299Sbbruce@ucdavis.edufine, but in the general case, you must cast ``src`` to the 110614299Sbbruce@ucdavis.eduappropriate derived-class pointer (e.g. using 110714299Sbbruce@ucdavis.edu``static_cast<Derived>(src)``) before allowing it to be returned as a 110814299Sbbruce@ucdavis.edu``void*``. 110914299Sbbruce@ucdavis.edu 111014299Sbbruce@ucdavis.edu.. [#f4] https://llvm.org/docs/HowToSetUpLLVMStyleRTTI.html 111114299Sbbruce@ucdavis.edu 111214299Sbbruce@ucdavis.edu.. note:: 111314299Sbbruce@ucdavis.edu 111414299Sbbruce@ucdavis.edu pybind11's standard support for downcasting objects whose types 111514299Sbbruce@ucdavis.edu have virtual methods is implemented using 111614299Sbbruce@ucdavis.edu ``polymorphic_type_hook`` too, using the standard C++ ability to 111714299Sbbruce@ucdavis.edu determine the most-derived type of a polymorphic object using 111814299Sbbruce@ucdavis.edu ``typeid()`` and to cast a base pointer to that most-derived type 111914299Sbbruce@ucdavis.edu (even if you don't know what it is) using ``dynamic_cast<void*>``. 112014299Sbbruce@ucdavis.edu 112114299Sbbruce@ucdavis.edu.. seealso:: 112214299Sbbruce@ucdavis.edu 112314299Sbbruce@ucdavis.edu The file :file:`tests/test_tagbased_polymorphic.cpp` contains a 112414299Sbbruce@ucdavis.edu more complete example, including a demonstration of how to provide 112514299Sbbruce@ucdavis.edu automatic downcasting for an entire class hierarchy without 112614299Sbbruce@ucdavis.edu writing one get() function for each class. 1127