classes.rst revision 14299
112037Sandreas.sandberg@arm.comClasses 212037Sandreas.sandberg@arm.com####### 312037Sandreas.sandberg@arm.com 412037Sandreas.sandberg@arm.comThis section presents advanced binding code for classes and it is assumed 512037Sandreas.sandberg@arm.comthat you are already familiar with the basics from :doc:`/classes`. 612391Sjason@lowepower.com 712391Sjason@lowepower.com.. _overriding_virtuals: 812391Sjason@lowepower.com 912391Sjason@lowepower.comOverriding virtual functions in Python 1012391Sjason@lowepower.com====================================== 1112037Sandreas.sandberg@arm.com 1212037Sandreas.sandberg@arm.comSuppose that a C++ class or interface has a virtual function that we'd like to 1312037Sandreas.sandberg@arm.comto override from within Python (we'll focus on the class ``Animal``; ``Dog`` is 1412037Sandreas.sandberg@arm.comgiven as a specific example of how one would do this with traditional C++ 1512391Sjason@lowepower.comcode). 1612391Sjason@lowepower.com 1712391Sjason@lowepower.com.. code-block:: cpp 1812391Sjason@lowepower.com 1912037Sandreas.sandberg@arm.com class Animal { 2012391Sjason@lowepower.com public: 2112391Sjason@lowepower.com virtual ~Animal() { } 2212391Sjason@lowepower.com virtual std::string go(int n_times) = 0; 2312037Sandreas.sandberg@arm.com }; 2412037Sandreas.sandberg@arm.com 2512037Sandreas.sandberg@arm.com class Dog : public Animal { 2612037Sandreas.sandberg@arm.com public: 2712037Sandreas.sandberg@arm.com std::string go(int n_times) override { 2812037Sandreas.sandberg@arm.com std::string result; 2912037Sandreas.sandberg@arm.com for (int i=0; i<n_times; ++i) 3012037Sandreas.sandberg@arm.com result += "woof! "; 3112037Sandreas.sandberg@arm.com return result; 3212037Sandreas.sandberg@arm.com } 3312037Sandreas.sandberg@arm.com }; 3412037Sandreas.sandberg@arm.com 3512037Sandreas.sandberg@arm.comLet's also suppose that we are given a plain function which calls the 3612037Sandreas.sandberg@arm.comfunction ``go()`` on an arbitrary ``Animal`` instance. 3712037Sandreas.sandberg@arm.com 3812037Sandreas.sandberg@arm.com.. code-block:: cpp 3912037Sandreas.sandberg@arm.com 4012037Sandreas.sandberg@arm.com std::string call_go(Animal *animal) { 4112037Sandreas.sandberg@arm.com return animal->go(3); 4212037Sandreas.sandberg@arm.com } 4312037Sandreas.sandberg@arm.com 4412037Sandreas.sandberg@arm.comNormally, the binding code for these classes would look as follows: 4512037Sandreas.sandberg@arm.com 4612037Sandreas.sandberg@arm.com.. code-block:: cpp 4712037Sandreas.sandberg@arm.com 4812037Sandreas.sandberg@arm.com PYBIND11_MODULE(example, m) { 4912037Sandreas.sandberg@arm.com py::class_<Animal>(m, "Animal") 5012037Sandreas.sandberg@arm.com .def("go", &Animal::go); 5112391Sjason@lowepower.com 5212391Sjason@lowepower.com py::class_<Dog, Animal>(m, "Dog") 5312037Sandreas.sandberg@arm.com .def(py::init<>()); 5412391Sjason@lowepower.com 5512391Sjason@lowepower.com m.def("call_go", &call_go); 5612037Sandreas.sandberg@arm.com } 5712037Sandreas.sandberg@arm.com 5812037Sandreas.sandberg@arm.comHowever, these bindings are impossible to extend: ``Animal`` is not 5912037Sandreas.sandberg@arm.comconstructible, and we clearly require some kind of "trampoline" that 6012391Sjason@lowepower.comredirects virtual calls back to Python. 6114299Sbbruce@ucdavis.edu 6214299Sbbruce@ucdavis.eduDefining a new type of ``Animal`` from within Python is possible but requires a 6314299Sbbruce@ucdavis.eduhelper class that is defined as follows: 6412037Sandreas.sandberg@arm.com 6512037Sandreas.sandberg@arm.com.. code-block:: cpp 6612037Sandreas.sandberg@arm.com 6712037Sandreas.sandberg@arm.com class PyAnimal : public Animal { 6812037Sandreas.sandberg@arm.com public: 6912391Sjason@lowepower.com /* Inherit the constructors */ 7012391Sjason@lowepower.com using Animal::Animal; 7112391Sjason@lowepower.com 7212391Sjason@lowepower.com /* Trampoline (need one for each virtual function) */ 7312391Sjason@lowepower.com std::string go(int n_times) override { 7412037Sandreas.sandberg@arm.com PYBIND11_OVERLOAD_PURE( 7512037Sandreas.sandberg@arm.com std::string, /* Return type */ 7612037Sandreas.sandberg@arm.com Animal, /* Parent class */ 7712037Sandreas.sandberg@arm.com go, /* Name of function in C++ (must match Python name) */ 7812037Sandreas.sandberg@arm.com n_times /* Argument(s) */ 7912037Sandreas.sandberg@arm.com ); 8012037Sandreas.sandberg@arm.com } 8112037Sandreas.sandberg@arm.com }; 8212037Sandreas.sandberg@arm.com 8312037Sandreas.sandberg@arm.comThe macro :c:macro:`PYBIND11_OVERLOAD_PURE` should be used for pure virtual 8412037Sandreas.sandberg@arm.comfunctions, and :c:macro:`PYBIND11_OVERLOAD` should be used for functions which have 8512037Sandreas.sandberg@arm.coma default implementation. There are also two alternate macros 8612037Sandreas.sandberg@arm.com:c:macro:`PYBIND11_OVERLOAD_PURE_NAME` and :c:macro:`PYBIND11_OVERLOAD_NAME` which 8712037Sandreas.sandberg@arm.comtake a string-valued name argument between the *Parent class* and *Name of the 8812037Sandreas.sandberg@arm.comfunction* slots, which defines the name of function in Python. This is required 8912391Sjason@lowepower.comwhen the C++ and Python versions of the 9012391Sjason@lowepower.comfunction have different names, e.g. ``operator()`` vs ``__call__``. 9112391Sjason@lowepower.com 9212391Sjason@lowepower.comThe binding code also needs a few minor adaptations (highlighted): 9312037Sandreas.sandberg@arm.com 9412037Sandreas.sandberg@arm.com.. code-block:: cpp 9512037Sandreas.sandberg@arm.com :emphasize-lines: 2,3 9612391Sjason@lowepower.com 9712391Sjason@lowepower.com PYBIND11_MODULE(example, m) { 9812037Sandreas.sandberg@arm.com py::class_<Animal, PyAnimal /* <--- trampoline*/>(m, "Animal") 9912037Sandreas.sandberg@arm.com .def(py::init<>()) 10012037Sandreas.sandberg@arm.com .def("go", &Animal::go); 10112037Sandreas.sandberg@arm.com 10212391Sjason@lowepower.com py::class_<Dog, Animal>(m, "Dog") 10312391Sjason@lowepower.com .def(py::init<>()); 10412391Sjason@lowepower.com 10512037Sandreas.sandberg@arm.com m.def("call_go", &call_go); 10612037Sandreas.sandberg@arm.com } 10712037Sandreas.sandberg@arm.com 10812037Sandreas.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 11012037Sandreas.sandberg@arm.combe combined with other template arguments such as a custom holder type; the 11112037Sandreas.sandberg@arm.comorder of template types does not matter). Following this, we are able to 11212037Sandreas.sandberg@arm.comdefine a constructor as usual. 11312037Sandreas.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 11712037Sandreas.sandberg@arm.com :emphasize-lines: 3 11812037Sandreas.sandberg@arm.com 11912037Sandreas.sandberg@arm.com py::class_<Animal, PyAnimal /* <--- trampoline*/>(m, "Animal"); 12012037Sandreas.sandberg@arm.com .def(py::init<>()) 12112037Sandreas.sandberg@arm.com .def("go", &PyAnimal::go); /* <--- THIS IS WRONG, use &Animal::go */ 12212391Sjason@lowepower.com 12312391Sjason@lowepower.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 12512037Sandreas.sandberg@arm.comnecessary steps required to providing proper overload support for inherited 12612037Sandreas.sandberg@arm.comclasses. 12712391Sjason@lowepower.com 12812391Sjason@lowepower.comThe Python session below shows how to override ``Animal::go`` and invoke it via 12912037Sandreas.sandberg@arm.coma virtual method call. 13012037Sandreas.sandberg@arm.com 13112037Sandreas.sandberg@arm.com.. code-block:: pycon 13212037Sandreas.sandberg@arm.com 13312391Sjason@lowepower.com >>> from example import * 13412391Sjason@lowepower.com >>> d = Dog() 13512391Sjason@lowepower.com >>> call_go(d) 13612037Sandreas.sandberg@arm.com u'woof! woof! woof! ' 13712037Sandreas.sandberg@arm.com >>> class Cat(Animal): 13812037Sandreas.sandberg@arm.com ... def go(self, n_times): 13912037Sandreas.sandberg@arm.com ... return "meow! " * n_times 14012037Sandreas.sandberg@arm.com ... 14112037Sandreas.sandberg@arm.com >>> c = Cat() 14212037Sandreas.sandberg@arm.com >>> call_go(c) 14312037Sandreas.sandberg@arm.com u'meow! meow! meow! ' 14412037Sandreas.sandberg@arm.com 14512037Sandreas.sandberg@arm.comIf you are defining a custom constructor in a derived Python class, you *must* 14612037Sandreas.sandberg@arm.comensure that you explicitly call the bound C++ constructor using ``__init__``, 14712037Sandreas.sandberg@arm.com*regardless* of whether it is a default constructor or not. Otherwise, the 14812037Sandreas.sandberg@arm.commemory for the C++ portion of the instance will be left uninitialized, which 14912037Sandreas.sandberg@arm.comwill generally leave the C++ instance in an invalid state and cause undefined 15012037Sandreas.sandberg@arm.combehavior if the C++ instance is subsequently used. 15112037Sandreas.sandberg@arm.com 15212391Sjason@lowepower.comHere is an example: 15312391Sjason@lowepower.com 15412037Sandreas.sandberg@arm.com.. code-block:: python 15512037Sandreas.sandberg@arm.com 15612037Sandreas.sandberg@arm.com class Dachshund(Dog): 15712037Sandreas.sandberg@arm.com def __init__(self, name): 15812037Sandreas.sandberg@arm.com Dog.__init__(self) # Without this, undefined behavior may occur if the C++ portions are referenced. 15912037Sandreas.sandberg@arm.com self.name = name 16012037Sandreas.sandberg@arm.com def bark(self): 16112391Sjason@lowepower.com return "yap!" 16212037Sandreas.sandberg@arm.com 16312037Sandreas.sandberg@arm.comNote that a direct ``__init__`` constructor *should be called*, and ``super()`` 16412037Sandreas.sandberg@arm.comshould not be used. For simple cases of linear inheritance, ``super()`` 16512037Sandreas.sandberg@arm.commay work, but once you begin mixing Python and C++ multiple inheritance, 16612037Sandreas.sandberg@arm.comthings will fall apart due to differences between Python's MRO and C++'s 16712037Sandreas.sandberg@arm.commechanisms. 16812037Sandreas.sandberg@arm.com 16912037Sandreas.sandberg@arm.comPlease take a look at the :ref:`macro_notes` before using this feature. 17012037Sandreas.sandberg@arm.com 17112037Sandreas.sandberg@arm.com.. note:: 17212037Sandreas.sandberg@arm.com 17312037Sandreas.sandberg@arm.com When the overridden type returns a reference or pointer to a type that 17412037Sandreas.sandberg@arm.com pybind11 converts from Python (for example, numeric values, std::string, 17512391Sjason@lowepower.com and other built-in value-converting types), there are some limitations to 17612391Sjason@lowepower.com be aware of: 17712391Sjason@lowepower.com 17812391Sjason@lowepower.com - because in these cases there is no C++ variable to reference (the value 17912391Sjason@lowepower.com is stored in the referenced Python variable), pybind11 provides one in 18012391Sjason@lowepower.com the PYBIND11_OVERLOAD macros (when needed) with static storage duration. 18112037Sandreas.sandberg@arm.com Note that this means that invoking the overloaded method on *any* 18212037Sandreas.sandberg@arm.com instance will change the referenced value stored in *all* instances of 18312037Sandreas.sandberg@arm.com that type. 18412037Sandreas.sandberg@arm.com 18512037Sandreas.sandberg@arm.com - Attempts to modify a non-const reference will not have the desired 18612037Sandreas.sandberg@arm.com effect: it will change only the static cache variable, but this change 18712037Sandreas.sandberg@arm.com will not propagate to underlying Python instance, and the change will be 18812037Sandreas.sandberg@arm.com replaced the next time the overload is invoked. 18912037Sandreas.sandberg@arm.com 19012037Sandreas.sandberg@arm.com.. seealso:: 19112037Sandreas.sandberg@arm.com 19212037Sandreas.sandberg@arm.com The file :file:`tests/test_virtual_functions.cpp` contains a complete 19312037Sandreas.sandberg@arm.com example that demonstrates how to override virtual functions using pybind11 19412037Sandreas.sandberg@arm.com in more detail. 19512037Sandreas.sandberg@arm.com 19612037Sandreas.sandberg@arm.com.. _virtual_and_inheritance: 19712037Sandreas.sandberg@arm.com 19812037Sandreas.sandberg@arm.comCombining virtual functions and inheritance 19912037Sandreas.sandberg@arm.com=========================================== 20012037Sandreas.sandberg@arm.com 20112037Sandreas.sandberg@arm.comWhen combining virtual methods with inheritance, you need to be sure to provide 20212037Sandreas.sandberg@arm.coman override for each method for which you want to allow overrides from derived 20312037Sandreas.sandberg@arm.compython classes. For example, suppose we extend the above ``Animal``/``Dog`` 20412037Sandreas.sandberg@arm.comexample as follows: 20512037Sandreas.sandberg@arm.com 20612037Sandreas.sandberg@arm.com.. code-block:: cpp 20712037Sandreas.sandberg@arm.com 20812037Sandreas.sandberg@arm.com class Animal { 20912391Sjason@lowepower.com public: 21012391Sjason@lowepower.com virtual std::string go(int n_times) = 0; 21112037Sandreas.sandberg@arm.com virtual std::string name() { return "unknown"; } 21212391Sjason@lowepower.com }; 21312391Sjason@lowepower.com class Dog : public Animal { 21412037Sandreas.sandberg@arm.com public: 21512037Sandreas.sandberg@arm.com std::string go(int n_times) override { 21612037Sandreas.sandberg@arm.com std::string result; 21712037Sandreas.sandberg@arm.com for (int i=0; i<n_times; ++i) 21812037Sandreas.sandberg@arm.com result += bark() + " "; 21912391Sjason@lowepower.com return result; 22012391Sjason@lowepower.com } 22112391Sjason@lowepower.com virtual std::string bark() { return "woof!"; } 22212037Sandreas.sandberg@arm.com }; 22312391Sjason@lowepower.com 22412391Sjason@lowepower.comthen the trampoline class for ``Animal`` must, as described in the previous 22512391Sjason@lowepower.comsection, override ``go()`` and ``name()``, but in order to allow python code to 22612037Sandreas.sandberg@arm.cominherit properly from ``Dog``, we also need a trampoline class for ``Dog`` that 22712037Sandreas.sandberg@arm.comoverrides both the added ``bark()`` method *and* the ``go()`` and ``name()`` 22812037Sandreas.sandberg@arm.commethods inherited from ``Animal`` (even though ``Dog`` doesn't directly 22912037Sandreas.sandberg@arm.comoverride the ``name()`` method): 23012037Sandreas.sandberg@arm.com 23112037Sandreas.sandberg@arm.com.. code-block:: cpp 23212037Sandreas.sandberg@arm.com 23312391Sjason@lowepower.com class PyAnimal : public Animal { 23412037Sandreas.sandberg@arm.com public: 23512037Sandreas.sandberg@arm.com using Animal::Animal; // Inherit constructors 23612037Sandreas.sandberg@arm.com std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Animal, go, n_times); } 23712391Sjason@lowepower.com std::string name() override { PYBIND11_OVERLOAD(std::string, Animal, name, ); } 23812391Sjason@lowepower.com }; 23912391Sjason@lowepower.com class PyDog : public Dog { 24012037Sandreas.sandberg@arm.com public: 24112037Sandreas.sandberg@arm.com using Dog::Dog; // Inherit constructors 24212391Sjason@lowepower.com std::string go(int n_times) override { PYBIND11_OVERLOAD(std::string, Dog, go, n_times); } 24312037Sandreas.sandberg@arm.com std::string name() override { PYBIND11_OVERLOAD(std::string, Dog, name, ); } 24412037Sandreas.sandberg@arm.com std::string bark() override { PYBIND11_OVERLOAD(std::string, Dog, bark, ); } 24512037Sandreas.sandberg@arm.com }; 24612037Sandreas.sandberg@arm.com 24712037Sandreas.sandberg@arm.com.. note:: 24812037Sandreas.sandberg@arm.com 24912391Sjason@lowepower.com Note the trailing commas in the ``PYBIND11_OVERLOAD`` calls to ``name()`` 25012391Sjason@lowepower.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 25412037Sandreas.sandberg@arm.comA registered class derived from a pybind11-registered class with virtual 25512391Sjason@lowepower.commethods requires a similar trampoline class, *even if* it doesn't explicitly 25612391Sjason@lowepower.comdeclare or override any virtual methods itself: 25712391Sjason@lowepower.com 25812391Sjason@lowepower.com.. code-block:: cpp 25912391Sjason@lowepower.com 26012391Sjason@lowepower.com class Husky : public Dog {}; 26112037Sandreas.sandberg@arm.com class PyHusky : public Husky { 26212037Sandreas.sandberg@arm.com public: 26312037Sandreas.sandberg@arm.com using Husky::Husky; // Inherit constructors 26412037Sandreas.sandberg@arm.com std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Husky, go, n_times); } 26512037Sandreas.sandberg@arm.com std::string name() override { PYBIND11_OVERLOAD(std::string, Husky, name, ); } 26612037Sandreas.sandberg@arm.com std::string bark() override { PYBIND11_OVERLOAD(std::string, Husky, bark, ); } 26712037Sandreas.sandberg@arm.com }; 26812037Sandreas.sandberg@arm.com 26912037Sandreas.sandberg@arm.comThere is, however, a technique that can be used to avoid this duplication 27012037Sandreas.sandberg@arm.com(which can be especially helpful for a base class with several virtual 27112037Sandreas.sandberg@arm.commethods). The technique involves using template trampoline classes, as 27212037Sandreas.sandberg@arm.comfollows: 27312037Sandreas.sandberg@arm.com 27412037Sandreas.sandberg@arm.com.. code-block:: cpp 27512037Sandreas.sandberg@arm.com 27612037Sandreas.sandberg@arm.com template <class AnimalBase = Animal> class PyAnimal : public AnimalBase { 27712037Sandreas.sandberg@arm.com public: 27812391Sjason@lowepower.com using AnimalBase::AnimalBase; // Inherit constructors 27912391Sjason@lowepower.com std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, AnimalBase, go, n_times); } 28012037Sandreas.sandberg@arm.com std::string name() override { PYBIND11_OVERLOAD(std::string, AnimalBase, name, ); } 28112037Sandreas.sandberg@arm.com }; 28212037Sandreas.sandberg@arm.com template <class DogBase = Dog> class PyDog : public PyAnimal<DogBase> { 28312037Sandreas.sandberg@arm.com public: 28412037Sandreas.sandberg@arm.com using PyAnimal<DogBase>::PyAnimal; // Inherit constructors 28512037Sandreas.sandberg@arm.com // Override PyAnimal's pure virtual go() with a non-pure one: 28612391Sjason@lowepower.com std::string go(int n_times) override { PYBIND11_OVERLOAD(std::string, DogBase, go, n_times); } 28712391Sjason@lowepower.com std::string bark() override { PYBIND11_OVERLOAD(std::string, DogBase, bark, ); } 28812391Sjason@lowepower.com }; 28912391Sjason@lowepower.com 29012037Sandreas.sandberg@arm.comThis technique has the advantage of requiring just one trampoline method to be 29112037Sandreas.sandberg@arm.comdeclared per virtual method and pure virtual method override. It does, 29212391Sjason@lowepower.comhowever, require the compiler to generate at least as many methods (and 29312391Sjason@lowepower.compossibly more, if both pure virtual and overridden pure virtual methods are 29412391Sjason@lowepower.comexposed, as above). 29512391Sjason@lowepower.com 29612391Sjason@lowepower.comThe classes are then registered with pybind11 using: 29712391Sjason@lowepower.com 29812391Sjason@lowepower.com.. code-block:: cpp 29912391Sjason@lowepower.com 30012391Sjason@lowepower.com py::class_<Animal, PyAnimal<>> animal(m, "Animal"); 30112037Sandreas.sandberg@arm.com py::class_<Dog, PyDog<>> dog(m, "Dog"); 30212037Sandreas.sandberg@arm.com py::class_<Husky, PyDog<Husky>> husky(m, "Husky"); 30312037Sandreas.sandberg@arm.com // ... add animal, dog, husky definitions 30412037Sandreas.sandberg@arm.com 30512391Sjason@lowepower.comNote that ``Husky`` did not require a dedicated trampoline template class at 306all, since it neither declares any new virtual methods nor provides any pure 307virtual method implementations. 308 309With either the repeated-virtuals or templated trampoline methods in place, you 310can now create a python class that inherits from ``Dog``: 311 312.. code-block:: python 313 314 class ShihTzu(Dog): 315 def bark(self): 316 return "yip!" 317 318.. seealso:: 319 320 See the file :file:`tests/test_virtual_functions.cpp` for complete examples 321 using both the duplication and templated trampoline approaches. 322 323.. _extended_aliases: 324 325Extended trampoline class functionality 326======================================= 327 328.. _extended_class_functionality_forced_trampoline: 329 330Forced trampoline class initialisation 331-------------------------------------- 332The trampoline classes described in the previous sections are, by default, only 333initialized when needed. More specifically, they are initialized when a python 334class actually inherits from a registered type (instead of merely creating an 335instance of the registered type), or when a registered constructor is only 336valid for the trampoline class but not the registered class. This is primarily 337for performance reasons: when the trampoline class is not needed for anything 338except virtual method dispatching, not initializing the trampoline class 339improves performance by avoiding needing to do a run-time check to see if the 340inheriting python instance has an overloaded method. 341 342Sometimes, however, it is useful to always initialize a trampoline class as an 343intermediate class that does more than just handle virtual method dispatching. 344For example, such a class might perform extra class initialization, extra 345destruction operations, and might define new members and methods to enable a 346more python-like interface to a class. 347 348In order to tell pybind11 that it should *always* initialize the trampoline 349class when creating new instances of a type, the class constructors should be 350declared using ``py::init_alias<Args, ...>()`` instead of the usual 351``py::init<Args, ...>()``. This forces construction via the trampoline class, 352ensuring member initialization and (eventual) destruction. 353 354.. seealso:: 355 356 See the file :file:`tests/test_virtual_functions.cpp` for complete examples 357 showing both normal and forced trampoline instantiation. 358 359Different method signatures 360--------------------------- 361The macro's introduced in :ref:`overriding_virtuals` cover most of the standard 362use cases when exposing C++ classes to Python. Sometimes it is hard or unwieldy 363to create a direct one-on-one mapping between the arguments and method return 364type. 365 366An example would be when the C++ signature contains output arguments using 367references (See also :ref:`faq_reference_arguments`). Another way of solving 368this is to use the method body of the trampoline class to do conversions to the 369input and return of the Python method. 370 371The main building block to do so is the :func:`get_overload`, this function 372allows retrieving a method implemented in Python from within the trampoline's 373methods. Consider for example a C++ method which has the signature 374``bool myMethod(int32_t& value)``, where the return indicates whether 375something should be done with the ``value``. This can be made convenient on the 376Python side by allowing the Python function to return ``None`` or an ``int``: 377 378.. code-block:: cpp 379 380 bool MyClass::myMethod(int32_t& value) 381 { 382 pybind11::gil_scoped_acquire gil; // Acquire the GIL while in this scope. 383 // Try to look up the overloaded method on the Python side. 384 pybind11::function overload = pybind11::get_overload(this, "myMethod"); 385 if (overload) { // method is found 386 auto obj = overload(value); // Call the Python function. 387 if (py::isinstance<py::int_>(obj)) { // check if it returned a Python integer type 388 value = obj.cast<int32_t>(); // Cast it and assign it to the value. 389 return true; // Return true; value should be used. 390 } else { 391 return false; // Python returned none, return false. 392 } 393 } 394 return false; // Alternatively return MyClass::myMethod(value); 395 } 396 397 398.. _custom_constructors: 399 400Custom constructors 401=================== 402 403The syntax for binding constructors was previously introduced, but it only 404works when a constructor of the appropriate arguments actually exists on the 405C++ side. To extend this to more general cases, pybind11 makes it possible 406to bind factory functions as constructors. For example, suppose you have a 407class like this: 408 409.. code-block:: cpp 410 411 class Example { 412 private: 413 Example(int); // private constructor 414 public: 415 // Factory function: 416 static Example create(int a) { return Example(a); } 417 }; 418 419 py::class_<Example>(m, "Example") 420 .def(py::init(&Example::create)); 421 422While it is possible to create a straightforward binding of the static 423``create`` method, it may sometimes be preferable to expose it as a constructor 424on the Python side. This can be accomplished by calling ``.def(py::init(...))`` 425with the function reference returning the new instance passed as an argument. 426It is also possible to use this approach to bind a function returning a new 427instance by raw pointer or by the holder (e.g. ``std::unique_ptr``). 428 429The following example shows the different approaches: 430 431.. code-block:: cpp 432 433 class Example { 434 private: 435 Example(int); // private constructor 436 public: 437 // Factory function - returned by value: 438 static Example create(int a) { return Example(a); } 439 440 // These constructors are publicly callable: 441 Example(double); 442 Example(int, int); 443 Example(std::string); 444 }; 445 446 py::class_<Example>(m, "Example") 447 // Bind the factory function as a constructor: 448 .def(py::init(&Example::create)) 449 // Bind a lambda function returning a pointer wrapped in a holder: 450 .def(py::init([](std::string arg) { 451 return std::unique_ptr<Example>(new Example(arg)); 452 })) 453 // Return a raw pointer: 454 .def(py::init([](int a, int b) { return new Example(a, b); })) 455 // You can mix the above with regular C++ constructor bindings as well: 456 .def(py::init<double>()) 457 ; 458 459When the constructor is invoked from Python, pybind11 will call the factory 460function and store the resulting C++ instance in the Python instance. 461 462When combining factory functions constructors with :ref:`virtual function 463trampolines <overriding_virtuals>` there are two approaches. The first is to 464add a constructor to the alias class that takes a base value by 465rvalue-reference. If such a constructor is available, it will be used to 466construct an alias instance from the value returned by the factory function. 467The second option is to provide two factory functions to ``py::init()``: the 468first will be invoked when no alias class is required (i.e. when the class is 469being used but not inherited from in Python), and the second will be invoked 470when an alias is required. 471 472You can also specify a single factory function that always returns an alias 473instance: this will result in behaviour similar to ``py::init_alias<...>()``, 474as described in the :ref:`extended trampoline class documentation 475<extended_aliases>`. 476 477The following example shows the different factory approaches for a class with 478an alias: 479 480.. code-block:: cpp 481 482 #include <pybind11/factory.h> 483 class Example { 484 public: 485 // ... 486 virtual ~Example() = default; 487 }; 488 class PyExample : public Example { 489 public: 490 using Example::Example; 491 PyExample(Example &&base) : Example(std::move(base)) {} 492 }; 493 py::class_<Example, PyExample>(m, "Example") 494 // Returns an Example pointer. If a PyExample is needed, the Example 495 // instance will be moved via the extra constructor in PyExample, above. 496 .def(py::init([]() { return new Example(); })) 497 // Two callbacks: 498 .def(py::init([]() { return new Example(); } /* no alias needed */, 499 []() { return new PyExample(); } /* alias needed */)) 500 // *Always* returns an alias instance (like py::init_alias<>()) 501 .def(py::init([]() { return new PyExample(); })) 502 ; 503 504Brace initialization 505-------------------- 506 507``pybind11::init<>`` internally uses C++11 brace initialization to call the 508constructor of the target class. This means that it can be used to bind 509*implicit* constructors as well: 510 511.. code-block:: cpp 512 513 struct Aggregate { 514 int a; 515 std::string b; 516 }; 517 518 py::class_<Aggregate>(m, "Aggregate") 519 .def(py::init<int, const std::string &>()); 520 521.. note:: 522 523 Note that brace initialization preferentially invokes constructor overloads 524 taking a ``std::initializer_list``. In the rare event that this causes an 525 issue, you can work around it by using ``py::init(...)`` with a lambda 526 function that constructs the new object as desired. 527 528.. _classes_with_non_public_destructors: 529 530Non-public destructors 531====================== 532 533If a class has a private or protected destructor (as might e.g. be the case in 534a singleton pattern), a compile error will occur when creating bindings via 535pybind11. The underlying issue is that the ``std::unique_ptr`` holder type that 536is responsible for managing the lifetime of instances will reference the 537destructor even if no deallocations ever take place. In order to expose classes 538with private or protected destructors, it is possible to override the holder 539type via a holder type argument to ``class_``. Pybind11 provides a helper class 540``py::nodelete`` that disables any destructor invocations. In this case, it is 541crucial that instances are deallocated on the C++ side to avoid memory leaks. 542 543.. code-block:: cpp 544 545 /* ... definition ... */ 546 547 class MyClass { 548 private: 549 ~MyClass() { } 550 }; 551 552 /* ... binding code ... */ 553 554 py::class_<MyClass, std::unique_ptr<MyClass, py::nodelete>>(m, "MyClass") 555 .def(py::init<>()) 556 557.. _implicit_conversions: 558 559Implicit conversions 560==================== 561 562Suppose that instances of two types ``A`` and ``B`` are used in a project, and 563that an ``A`` can easily be converted into an instance of type ``B`` (examples of this 564could be a fixed and an arbitrary precision number type). 565 566.. code-block:: cpp 567 568 py::class_<A>(m, "A") 569 /// ... members ... 570 571 py::class_<B>(m, "B") 572 .def(py::init<A>()) 573 /// ... members ... 574 575 m.def("func", 576 [](const B &) { /* .... */ } 577 ); 578 579To invoke the function ``func`` using a variable ``a`` containing an ``A`` 580instance, we'd have to write ``func(B(a))`` in Python. On the other hand, C++ 581will automatically apply an implicit type conversion, which makes it possible 582to directly write ``func(a)``. 583 584In this situation (i.e. where ``B`` has a constructor that converts from 585``A``), the following statement enables similar implicit conversions on the 586Python side: 587 588.. code-block:: cpp 589 590 py::implicitly_convertible<A, B>(); 591 592.. note:: 593 594 Implicit conversions from ``A`` to ``B`` only work when ``B`` is a custom 595 data type that is exposed to Python via pybind11. 596 597 To prevent runaway recursion, implicit conversions are non-reentrant: an 598 implicit conversion invoked as part of another implicit conversion of the 599 same type (i.e. from ``A`` to ``B``) will fail. 600 601.. _static_properties: 602 603Static properties 604================= 605 606The section on :ref:`properties` discussed the creation of instance properties 607that are implemented in terms of C++ getters and setters. 608 609Static properties can also be created in a similar way to expose getters and 610setters of static class attributes. Note that the implicit ``self`` argument 611also exists in this case and is used to pass the Python ``type`` subclass 612instance. This parameter will often not be needed by the C++ side, and the 613following example illustrates how to instantiate a lambda getter function 614that ignores it: 615 616.. code-block:: cpp 617 618 py::class_<Foo>(m, "Foo") 619 .def_property_readonly_static("foo", [](py::object /* self */) { return Foo(); }); 620 621Operator overloading 622==================== 623 624Suppose that we're given the following ``Vector2`` class with a vector addition 625and scalar multiplication operation, all implemented using overloaded operators 626in C++. 627 628.. code-block:: cpp 629 630 class Vector2 { 631 public: 632 Vector2(float x, float y) : x(x), y(y) { } 633 634 Vector2 operator+(const Vector2 &v) const { return Vector2(x + v.x, y + v.y); } 635 Vector2 operator*(float value) const { return Vector2(x * value, y * value); } 636 Vector2& operator+=(const Vector2 &v) { x += v.x; y += v.y; return *this; } 637 Vector2& operator*=(float v) { x *= v; y *= v; return *this; } 638 639 friend Vector2 operator*(float f, const Vector2 &v) { 640 return Vector2(f * v.x, f * v.y); 641 } 642 643 std::string toString() const { 644 return "[" + std::to_string(x) + ", " + std::to_string(y) + "]"; 645 } 646 private: 647 float x, y; 648 }; 649 650The following snippet shows how the above operators can be conveniently exposed 651to Python. 652 653.. code-block:: cpp 654 655 #include <pybind11/operators.h> 656 657 PYBIND11_MODULE(example, m) { 658 py::class_<Vector2>(m, "Vector2") 659 .def(py::init<float, float>()) 660 .def(py::self + py::self) 661 .def(py::self += py::self) 662 .def(py::self *= float()) 663 .def(float() * py::self) 664 .def(py::self * float()) 665 .def(-py::self) 666 .def("__repr__", &Vector2::toString); 667 } 668 669Note that a line like 670 671.. code-block:: cpp 672 673 .def(py::self * float()) 674 675is really just short hand notation for 676 677.. code-block:: cpp 678 679 .def("__mul__", [](const Vector2 &a, float b) { 680 return a * b; 681 }, py::is_operator()) 682 683This can be useful for exposing additional operators that don't exist on the 684C++ side, or to perform other types of customization. The ``py::is_operator`` 685flag marker is needed to inform pybind11 that this is an operator, which 686returns ``NotImplemented`` when invoked with incompatible arguments rather than 687throwing a type error. 688 689.. note:: 690 691 To use the more convenient ``py::self`` notation, the additional 692 header file :file:`pybind11/operators.h` must be included. 693 694.. seealso:: 695 696 The file :file:`tests/test_operator_overloading.cpp` contains a 697 complete example that demonstrates how to work with overloaded operators in 698 more detail. 699 700.. _pickling: 701 702Pickling support 703================ 704 705Python's ``pickle`` module provides a powerful facility to serialize and 706de-serialize a Python object graph into a binary data stream. To pickle and 707unpickle C++ classes using pybind11, a ``py::pickle()`` definition must be 708provided. Suppose the class in question has the following signature: 709 710.. code-block:: cpp 711 712 class Pickleable { 713 public: 714 Pickleable(const std::string &value) : m_value(value) { } 715 const std::string &value() const { return m_value; } 716 717 void setExtra(int extra) { m_extra = extra; } 718 int extra() const { return m_extra; } 719 private: 720 std::string m_value; 721 int m_extra = 0; 722 }; 723 724Pickling support in Python is enabled by defining the ``__setstate__`` and 725``__getstate__`` methods [#f3]_. For pybind11 classes, use ``py::pickle()`` 726to bind these two functions: 727 728.. code-block:: cpp 729 730 py::class_<Pickleable>(m, "Pickleable") 731 .def(py::init<std::string>()) 732 .def("value", &Pickleable::value) 733 .def("extra", &Pickleable::extra) 734 .def("setExtra", &Pickleable::setExtra) 735 .def(py::pickle( 736 [](const Pickleable &p) { // __getstate__ 737 /* Return a tuple that fully encodes the state of the object */ 738 return py::make_tuple(p.value(), p.extra()); 739 }, 740 [](py::tuple t) { // __setstate__ 741 if (t.size() != 2) 742 throw std::runtime_error("Invalid state!"); 743 744 /* Create a new C++ instance */ 745 Pickleable p(t[0].cast<std::string>()); 746 747 /* Assign any additional state */ 748 p.setExtra(t[1].cast<int>()); 749 750 return p; 751 } 752 )); 753 754The ``__setstate__`` part of the ``py::picke()`` definition follows the same 755rules as the single-argument version of ``py::init()``. The return type can be 756a value, pointer or holder type. See :ref:`custom_constructors` for details. 757 758An instance can now be pickled as follows: 759 760.. code-block:: python 761 762 try: 763 import cPickle as pickle # Use cPickle on Python 2.7 764 except ImportError: 765 import pickle 766 767 p = Pickleable("test_value") 768 p.setExtra(15) 769 data = pickle.dumps(p, 2) 770 771Note that only the cPickle module is supported on Python 2.7. The second 772argument to ``dumps`` is also crucial: it selects the pickle protocol version 7732, since the older version 1 is not supported. Newer versions are also fine—for 774instance, specify ``-1`` to always use the latest available version. Beware: 775failure to follow these instructions will cause important pybind11 memory 776allocation routines to be skipped during unpickling, which will likely lead to 777memory corruption and/or segmentation faults. 778 779.. seealso:: 780 781 The file :file:`tests/test_pickling.cpp` contains a complete example 782 that demonstrates how to pickle and unpickle types using pybind11 in more 783 detail. 784 785.. [#f3] http://docs.python.org/3/library/pickle.html#pickling-class-instances 786 787Multiple Inheritance 788==================== 789 790pybind11 can create bindings for types that derive from multiple base types 791(aka. *multiple inheritance*). To do so, specify all bases in the template 792arguments of the ``class_`` declaration: 793 794.. code-block:: cpp 795 796 py::class_<MyType, BaseType1, BaseType2, BaseType3>(m, "MyType") 797 ... 798 799The base types can be specified in arbitrary order, and they can even be 800interspersed with alias types and holder types (discussed earlier in this 801document)---pybind11 will automatically find out which is which. The only 802requirement is that the first template argument is the type to be declared. 803 804It is also permitted to inherit multiply from exported C++ classes in Python, 805as well as inheriting from multiple Python and/or pybind11-exported classes. 806 807There is one caveat regarding the implementation of this feature: 808 809When only one base type is specified for a C++ type that actually has multiple 810bases, pybind11 will assume that it does not participate in multiple 811inheritance, which can lead to undefined behavior. In such cases, add the tag 812``multiple_inheritance`` to the class constructor: 813 814.. code-block:: cpp 815 816 py::class_<MyType, BaseType2>(m, "MyType", py::multiple_inheritance()); 817 818The tag is redundant and does not need to be specified when multiple base types 819are listed. 820 821.. _module_local: 822 823Module-local class bindings 824=========================== 825 826When creating a binding for a class, pybind11 by default makes that binding 827"global" across modules. What this means is that a type defined in one module 828can be returned from any module resulting in the same Python type. For 829example, this allows the following: 830 831.. code-block:: cpp 832 833 // In the module1.cpp binding code for module1: 834 py::class_<Pet>(m, "Pet") 835 .def(py::init<std::string>()) 836 .def_readonly("name", &Pet::name); 837 838.. code-block:: cpp 839 840 // In the module2.cpp binding code for module2: 841 m.def("create_pet", [](std::string name) { return new Pet(name); }); 842 843.. code-block:: pycon 844 845 >>> from module1 import Pet 846 >>> from module2 import create_pet 847 >>> pet1 = Pet("Kitty") 848 >>> pet2 = create_pet("Doggy") 849 >>> pet2.name() 850 'Doggy' 851 852When writing binding code for a library, this is usually desirable: this 853allows, for example, splitting up a complex library into multiple Python 854modules. 855 856In some cases, however, this can cause conflicts. For example, suppose two 857unrelated modules make use of an external C++ library and each provide custom 858bindings for one of that library's classes. This will result in an error when 859a Python program attempts to import both modules (directly or indirectly) 860because of conflicting definitions on the external type: 861 862.. code-block:: cpp 863 864 // dogs.cpp 865 866 // Binding for external library class: 867 py::class<pets::Pet>(m, "Pet") 868 .def("name", &pets::Pet::name); 869 870 // Binding for local extension class: 871 py::class<Dog, pets::Pet>(m, "Dog") 872 .def(py::init<std::string>()); 873 874.. code-block:: cpp 875 876 // cats.cpp, in a completely separate project from the above dogs.cpp. 877 878 // Binding for external library class: 879 py::class<pets::Pet>(m, "Pet") 880 .def("get_name", &pets::Pet::name); 881 882 // Binding for local extending class: 883 py::class<Cat, pets::Pet>(m, "Cat") 884 .def(py::init<std::string>()); 885 886.. code-block:: pycon 887 888 >>> import cats 889 >>> import dogs 890 Traceback (most recent call last): 891 File "<stdin>", line 1, in <module> 892 ImportError: generic_type: type "Pet" is already registered! 893 894To get around this, you can tell pybind11 to keep the external class binding 895localized to the module by passing the ``py::module_local()`` attribute into 896the ``py::class_`` constructor: 897 898.. code-block:: cpp 899 900 // Pet binding in dogs.cpp: 901 py::class<pets::Pet>(m, "Pet", py::module_local()) 902 .def("name", &pets::Pet::name); 903 904.. code-block:: cpp 905 906 // Pet binding in cats.cpp: 907 py::class<pets::Pet>(m, "Pet", py::module_local()) 908 .def("get_name", &pets::Pet::name); 909 910This makes the Python-side ``dogs.Pet`` and ``cats.Pet`` into distinct classes, 911avoiding the conflict and allowing both modules to be loaded. C++ code in the 912``dogs`` module that casts or returns a ``Pet`` instance will result in a 913``dogs.Pet`` Python instance, while C++ code in the ``cats`` module will result 914in a ``cats.Pet`` Python instance. 915 916This does come with two caveats, however: First, external modules cannot return 917or cast a ``Pet`` instance to Python (unless they also provide their own local 918bindings). Second, from the Python point of view they are two distinct classes. 919 920Note that the locality only applies in the C++ -> Python direction. When 921passing such a ``py::module_local`` type into a C++ function, the module-local 922classes are still considered. This means that if the following function is 923added to any module (including but not limited to the ``cats`` and ``dogs`` 924modules above) it will be callable with either a ``dogs.Pet`` or ``cats.Pet`` 925argument: 926 927.. code-block:: cpp 928 929 m.def("pet_name", [](const pets::Pet &pet) { return pet.name(); }); 930 931For example, suppose the above function is added to each of ``cats.cpp``, 932``dogs.cpp`` and ``frogs.cpp`` (where ``frogs.cpp`` is some other module that 933does *not* bind ``Pets`` at all). 934 935.. code-block:: pycon 936 937 >>> import cats, dogs, frogs # No error because of the added py::module_local() 938 >>> mycat, mydog = cats.Cat("Fluffy"), dogs.Dog("Rover") 939 >>> (cats.pet_name(mycat), dogs.pet_name(mydog)) 940 ('Fluffy', 'Rover') 941 >>> (cats.pet_name(mydog), dogs.pet_name(mycat), frogs.pet_name(mycat)) 942 ('Rover', 'Fluffy', 'Fluffy') 943 944It is possible to use ``py::module_local()`` registrations in one module even 945if another module registers the same type globally: within the module with the 946module-local definition, all C++ instances will be cast to the associated bound 947Python type. In other modules any such values are converted to the global 948Python type created elsewhere. 949 950.. note:: 951 952 STL bindings (as provided via the optional :file:`pybind11/stl_bind.h` 953 header) apply ``py::module_local`` by default when the bound type might 954 conflict with other modules; see :ref:`stl_bind` for details. 955 956.. note:: 957 958 The localization of the bound types is actually tied to the shared object 959 or binary generated by the compiler/linker. For typical modules created 960 with ``PYBIND11_MODULE()``, this distinction is not significant. It is 961 possible, however, when :ref:`embedding` to embed multiple modules in the 962 same binary (see :ref:`embedding_modules`). In such a case, the 963 localization will apply across all embedded modules within the same binary. 964 965.. seealso:: 966 967 The file :file:`tests/test_local_bindings.cpp` contains additional examples 968 that demonstrate how ``py::module_local()`` works. 969 970Binding protected member functions 971================================== 972 973It's normally not possible to expose ``protected`` member functions to Python: 974 975.. code-block:: cpp 976 977 class A { 978 protected: 979 int foo() const { return 42; } 980 }; 981 982 py::class_<A>(m, "A") 983 .def("foo", &A::foo); // error: 'foo' is a protected member of 'A' 984 985On one hand, this is good because non-``public`` members aren't meant to be 986accessed from the outside. But we may want to make use of ``protected`` 987functions in derived Python classes. 988 989The following pattern makes this possible: 990 991.. code-block:: cpp 992 993 class A { 994 protected: 995 int foo() const { return 42; } 996 }; 997 998 class Publicist : public A { // helper type for exposing protected functions 999 public: 1000 using A::foo; // inherited with different access modifier 1001 }; 1002 1003 py::class_<A>(m, "A") // bind the primary class 1004 .def("foo", &Publicist::foo); // expose protected methods via the publicist 1005 1006This works because ``&Publicist::foo`` is exactly the same function as 1007``&A::foo`` (same signature and address), just with a different access 1008modifier. The only purpose of the ``Publicist`` helper class is to make 1009the function name ``public``. 1010 1011If the intent is to expose ``protected`` ``virtual`` functions which can be 1012overridden in Python, the publicist pattern can be combined with the previously 1013described trampoline: 1014 1015.. code-block:: cpp 1016 1017 class A { 1018 public: 1019 virtual ~A() = default; 1020 1021 protected: 1022 virtual int foo() const { return 42; } 1023 }; 1024 1025 class Trampoline : public A { 1026 public: 1027 int foo() const override { PYBIND11_OVERLOAD(int, A, foo, ); } 1028 }; 1029 1030 class Publicist : public A { 1031 public: 1032 using A::foo; 1033 }; 1034 1035 py::class_<A, Trampoline>(m, "A") // <-- `Trampoline` here 1036 .def("foo", &Publicist::foo); // <-- `Publicist` here, not `Trampoline`! 1037 1038.. note:: 1039 1040 MSVC 2015 has a compiler bug (fixed in version 2017) which 1041 requires a more explicit function binding in the form of 1042 ``.def("foo", static_cast<int (A::*)() const>(&Publicist::foo));`` 1043 where ``int (A::*)() const`` is the type of ``A::foo``. 1044 1045Custom automatic downcasters 1046============================ 1047 1048As explained in :ref:`inheritance`, pybind11 comes with built-in 1049understanding of the dynamic type of polymorphic objects in C++; that 1050is, returning a Pet to Python produces a Python object that knows it's 1051wrapping a Dog, if Pet has virtual methods and pybind11 knows about 1052Dog and this Pet is in fact a Dog. Sometimes, you might want to 1053provide this automatic downcasting behavior when creating bindings for 1054a class hierarchy that does not use standard C++ polymorphism, such as 1055LLVM [#f4]_. As long as there's some way to determine at runtime 1056whether a downcast is safe, you can proceed by specializing the 1057``pybind11::polymorphic_type_hook`` template: 1058 1059.. code-block:: cpp 1060 1061 enum class PetKind { Cat, Dog, Zebra }; 1062 struct Pet { // Not polymorphic: has no virtual methods 1063 const PetKind kind; 1064 int age = 0; 1065 protected: 1066 Pet(PetKind _kind) : kind(_kind) {} 1067 }; 1068 struct Dog : Pet { 1069 Dog() : Pet(PetKind::Dog) {} 1070 std::string sound = "woof!"; 1071 std::string bark() const { return sound; } 1072 }; 1073 1074 namespace pybind11 { 1075 template<> struct polymorphic_type_hook<Pet> { 1076 static const void *get(const Pet *src, const std::type_info*& type) { 1077 // note that src may be nullptr 1078 if (src && src->kind == PetKind::Dog) { 1079 type = &typeid(Dog); 1080 return static_cast<const Dog*>(src); 1081 } 1082 return src; 1083 } 1084 }; 1085 } // namespace pybind11 1086 1087When pybind11 wants to convert a C++ pointer of type ``Base*`` to a 1088Python object, it calls ``polymorphic_type_hook<Base>::get()`` to 1089determine if a downcast is possible. The ``get()`` function should use 1090whatever runtime information is available to determine if its ``src`` 1091parameter is in fact an instance of some class ``Derived`` that 1092inherits from ``Base``. If it finds such a ``Derived``, it sets ``type 1093= &typeid(Derived)`` and returns a pointer to the ``Derived`` object 1094that contains ``src``. Otherwise, it just returns ``src``, leaving 1095``type`` at its default value of nullptr. If you set ``type`` to a 1096type that pybind11 doesn't know about, no downcasting will occur, and 1097the original ``src`` pointer will be used with its static type 1098``Base*``. 1099 1100It is critical that the returned pointer and ``type`` argument of 1101``get()`` agree with each other: if ``type`` is set to something 1102non-null, the returned pointer must point to the start of an object 1103whose type is ``type``. If the hierarchy being exposed uses only 1104single inheritance, a simple ``return src;`` will achieve this just 1105fine, but in the general case, you must cast ``src`` to the 1106appropriate derived-class pointer (e.g. using 1107``static_cast<Derived>(src)``) before allowing it to be returned as a 1108``void*``. 1109 1110.. [#f4] https://llvm.org/docs/HowToSetUpLLVMStyleRTTI.html 1111 1112.. note:: 1113 1114 pybind11's standard support for downcasting objects whose types 1115 have virtual methods is implemented using 1116 ``polymorphic_type_hook`` too, using the standard C++ ability to 1117 determine the most-derived type of a polymorphic object using 1118 ``typeid()`` and to cast a base pointer to that most-derived type 1119 (even if you don't know what it is) using ``dynamic_cast<void*>``. 1120 1121.. seealso:: 1122 1123 The file :file:`tests/test_tagbased_polymorphic.cpp` contains a 1124 more complete example, including a demonstration of how to provide 1125 automatic downcasting for an entire class hierarchy without 1126 writing one get() function for each class. 1127