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