classes.rst revision 12391
111986Sandreas.sandberg@arm.comClasses 211986Sandreas.sandberg@arm.com####### 311986Sandreas.sandberg@arm.com 411986Sandreas.sandberg@arm.comThis section presents advanced binding code for classes and it is assumed 511986Sandreas.sandberg@arm.comthat you are already familiar with the basics from :doc:`/classes`. 611986Sandreas.sandberg@arm.com 711986Sandreas.sandberg@arm.com.. _overriding_virtuals: 811986Sandreas.sandberg@arm.com 911986Sandreas.sandberg@arm.comOverriding virtual functions in Python 1011986Sandreas.sandberg@arm.com====================================== 1111986Sandreas.sandberg@arm.com 1211986Sandreas.sandberg@arm.comSuppose that a C++ class or interface has a virtual function that we'd like to 1311986Sandreas.sandberg@arm.comto override from within Python (we'll focus on the class ``Animal``; ``Dog`` is 1411986Sandreas.sandberg@arm.comgiven as a specific example of how one would do this with traditional C++ 1511986Sandreas.sandberg@arm.comcode). 1611986Sandreas.sandberg@arm.com 1711986Sandreas.sandberg@arm.com.. code-block:: cpp 1811986Sandreas.sandberg@arm.com 1911986Sandreas.sandberg@arm.com class Animal { 2011986Sandreas.sandberg@arm.com public: 2111986Sandreas.sandberg@arm.com virtual ~Animal() { } 2211986Sandreas.sandberg@arm.com virtual std::string go(int n_times) = 0; 2311986Sandreas.sandberg@arm.com }; 2411986Sandreas.sandberg@arm.com 2511986Sandreas.sandberg@arm.com class Dog : public Animal { 2611986Sandreas.sandberg@arm.com public: 2711986Sandreas.sandberg@arm.com std::string go(int n_times) override { 2811986Sandreas.sandberg@arm.com std::string result; 2911986Sandreas.sandberg@arm.com for (int i=0; i<n_times; ++i) 3011986Sandreas.sandberg@arm.com result += "woof! "; 3111986Sandreas.sandberg@arm.com return result; 3211986Sandreas.sandberg@arm.com } 3311986Sandreas.sandberg@arm.com }; 3411986Sandreas.sandberg@arm.com 3511986Sandreas.sandberg@arm.comLet's also suppose that we are given a plain function which calls the 3611986Sandreas.sandberg@arm.comfunction ``go()`` on an arbitrary ``Animal`` instance. 3711986Sandreas.sandberg@arm.com 3811986Sandreas.sandberg@arm.com.. code-block:: cpp 3911986Sandreas.sandberg@arm.com 4011986Sandreas.sandberg@arm.com std::string call_go(Animal *animal) { 4111986Sandreas.sandberg@arm.com return animal->go(3); 4211986Sandreas.sandberg@arm.com } 4311986Sandreas.sandberg@arm.com 4411986Sandreas.sandberg@arm.comNormally, the binding code for these classes would look as follows: 4511986Sandreas.sandberg@arm.com 4611986Sandreas.sandberg@arm.com.. code-block:: cpp 4711986Sandreas.sandberg@arm.com 4812391Sjason@lowepower.com PYBIND11_MODULE(example, m) { 4911986Sandreas.sandberg@arm.com py::class_<Animal> animal(m, "Animal"); 5011986Sandreas.sandberg@arm.com animal 5111986Sandreas.sandberg@arm.com .def("go", &Animal::go); 5211986Sandreas.sandberg@arm.com 5311986Sandreas.sandberg@arm.com py::class_<Dog>(m, "Dog", animal) 5411986Sandreas.sandberg@arm.com .def(py::init<>()); 5511986Sandreas.sandberg@arm.com 5611986Sandreas.sandberg@arm.com m.def("call_go", &call_go); 5711986Sandreas.sandberg@arm.com } 5811986Sandreas.sandberg@arm.com 5911986Sandreas.sandberg@arm.comHowever, these bindings are impossible to extend: ``Animal`` is not 6011986Sandreas.sandberg@arm.comconstructible, and we clearly require some kind of "trampoline" that 6111986Sandreas.sandberg@arm.comredirects virtual calls back to Python. 6211986Sandreas.sandberg@arm.com 6311986Sandreas.sandberg@arm.comDefining a new type of ``Animal`` from within Python is possible but requires a 6411986Sandreas.sandberg@arm.comhelper class that is defined as follows: 6511986Sandreas.sandberg@arm.com 6611986Sandreas.sandberg@arm.com.. code-block:: cpp 6711986Sandreas.sandberg@arm.com 6811986Sandreas.sandberg@arm.com class PyAnimal : public Animal { 6911986Sandreas.sandberg@arm.com public: 7011986Sandreas.sandberg@arm.com /* Inherit the constructors */ 7111986Sandreas.sandberg@arm.com using Animal::Animal; 7211986Sandreas.sandberg@arm.com 7311986Sandreas.sandberg@arm.com /* Trampoline (need one for each virtual function) */ 7411986Sandreas.sandberg@arm.com std::string go(int n_times) override { 7511986Sandreas.sandberg@arm.com PYBIND11_OVERLOAD_PURE( 7611986Sandreas.sandberg@arm.com std::string, /* Return type */ 7711986Sandreas.sandberg@arm.com Animal, /* Parent class */ 7812037Sandreas.sandberg@arm.com go, /* Name of function in C++ (must match Python name) */ 7911986Sandreas.sandberg@arm.com n_times /* Argument(s) */ 8011986Sandreas.sandberg@arm.com ); 8111986Sandreas.sandberg@arm.com } 8211986Sandreas.sandberg@arm.com }; 8311986Sandreas.sandberg@arm.com 8411986Sandreas.sandberg@arm.comThe macro :func:`PYBIND11_OVERLOAD_PURE` should be used for pure virtual 8511986Sandreas.sandberg@arm.comfunctions, and :func:`PYBIND11_OVERLOAD` should be used for functions which have 8611986Sandreas.sandberg@arm.coma default implementation. There are also two alternate macros 8711986Sandreas.sandberg@arm.com:func:`PYBIND11_OVERLOAD_PURE_NAME` and :func:`PYBIND11_OVERLOAD_NAME` which 8811986Sandreas.sandberg@arm.comtake a string-valued name argument between the *Parent class* and *Name of the 8912391Sjason@lowepower.comfunction* slots, which defines the name of function in Python. This is required 9012037Sandreas.sandberg@arm.comwhen the C++ and Python versions of the 9111986Sandreas.sandberg@arm.comfunction have different names, e.g. ``operator()`` vs ``__call__``. 9211986Sandreas.sandberg@arm.com 9311986Sandreas.sandberg@arm.comThe binding code also needs a few minor adaptations (highlighted): 9411986Sandreas.sandberg@arm.com 9511986Sandreas.sandberg@arm.com.. code-block:: cpp 9612391Sjason@lowepower.com :emphasize-lines: 2,4,5 9711986Sandreas.sandberg@arm.com 9812391Sjason@lowepower.com PYBIND11_MODULE(example, m) { 9911986Sandreas.sandberg@arm.com py::class_<Animal, PyAnimal /* <--- trampoline*/> animal(m, "Animal"); 10011986Sandreas.sandberg@arm.com animal 10111986Sandreas.sandberg@arm.com .def(py::init<>()) 10211986Sandreas.sandberg@arm.com .def("go", &Animal::go); 10311986Sandreas.sandberg@arm.com 10411986Sandreas.sandberg@arm.com py::class_<Dog>(m, "Dog", animal) 10511986Sandreas.sandberg@arm.com .def(py::init<>()); 10611986Sandreas.sandberg@arm.com 10711986Sandreas.sandberg@arm.com m.def("call_go", &call_go); 10811986Sandreas.sandberg@arm.com } 10911986Sandreas.sandberg@arm.com 11011986Sandreas.sandberg@arm.comImportantly, pybind11 is made aware of the trampoline helper class by 11112037Sandreas.sandberg@arm.comspecifying it as an extra template argument to :class:`class_`. (This can also 11211986Sandreas.sandberg@arm.combe combined with other template arguments such as a custom holder type; the 11311986Sandreas.sandberg@arm.comorder of template types does not matter). Following this, we are able to 11411986Sandreas.sandberg@arm.comdefine a constructor as usual. 11511986Sandreas.sandberg@arm.com 11612037Sandreas.sandberg@arm.comBindings should be made against the actual class, not the trampoline helper class. 11712037Sandreas.sandberg@arm.com 11812037Sandreas.sandberg@arm.com.. code-block:: cpp 11912037Sandreas.sandberg@arm.com 12012037Sandreas.sandberg@arm.com py::class_<Animal, PyAnimal /* <--- trampoline*/> animal(m, "Animal"); 12112037Sandreas.sandberg@arm.com animal 12212037Sandreas.sandberg@arm.com .def(py::init<>()) 12312037Sandreas.sandberg@arm.com .def("go", &PyAnimal::go); /* <--- THIS IS WRONG, use &Animal::go */ 12412037Sandreas.sandberg@arm.com 12511986Sandreas.sandberg@arm.comNote, however, that the above is sufficient for allowing python classes to 12612391Sjason@lowepower.comextend ``Animal``, but not ``Dog``: see :ref:`virtual_and_inheritance` for the 12711986Sandreas.sandberg@arm.comnecessary steps required to providing proper overload support for inherited 12811986Sandreas.sandberg@arm.comclasses. 12911986Sandreas.sandberg@arm.com 13011986Sandreas.sandberg@arm.comThe Python session below shows how to override ``Animal::go`` and invoke it via 13111986Sandreas.sandberg@arm.coma virtual method call. 13211986Sandreas.sandberg@arm.com 13311986Sandreas.sandberg@arm.com.. code-block:: pycon 13411986Sandreas.sandberg@arm.com 13511986Sandreas.sandberg@arm.com >>> from example import * 13611986Sandreas.sandberg@arm.com >>> d = Dog() 13711986Sandreas.sandberg@arm.com >>> call_go(d) 13811986Sandreas.sandberg@arm.com u'woof! woof! woof! ' 13911986Sandreas.sandberg@arm.com >>> class Cat(Animal): 14011986Sandreas.sandberg@arm.com ... def go(self, n_times): 14111986Sandreas.sandberg@arm.com ... return "meow! " * n_times 14211986Sandreas.sandberg@arm.com ... 14311986Sandreas.sandberg@arm.com >>> c = Cat() 14411986Sandreas.sandberg@arm.com >>> call_go(c) 14511986Sandreas.sandberg@arm.com u'meow! meow! meow! ' 14611986Sandreas.sandberg@arm.com 14712391Sjason@lowepower.comIf you are defining a custom constructor in a derived Python class, you *must* 14812391Sjason@lowepower.comensure that you explicitly call the bound C++ constructor using ``__init__``, 14912391Sjason@lowepower.com*regardless* of whether it is a default constructor or not. Otherwise, the 15012391Sjason@lowepower.commemory for the C++ portion of the instance will be left uninitialized, which 15112391Sjason@lowepower.comwill generally leave the C++ instance in an invalid state and cause undefined 15212391Sjason@lowepower.combehavior if the C++ instance is subsequently used. 15312391Sjason@lowepower.com 15412391Sjason@lowepower.comHere is an example: 15512391Sjason@lowepower.com 15612391Sjason@lowepower.com.. code-block:: python 15712391Sjason@lowepower.com 15812391Sjason@lowepower.com class Dachschund(Dog): 15912391Sjason@lowepower.com def __init__(self, name): 16012391Sjason@lowepower.com Dog.__init__(self) # Without this, undefind behavior may occur if the C++ portions are referenced. 16112391Sjason@lowepower.com self.name = name 16212391Sjason@lowepower.com def bark(self): 16312391Sjason@lowepower.com return "yap!" 16412391Sjason@lowepower.com 16512391Sjason@lowepower.comNote that a direct ``__init__`` constructor *should be called*, and ``super()`` 16612391Sjason@lowepower.comshould not be used. For simple cases of linear inheritance, ``super()`` 16712391Sjason@lowepower.commay work, but once you begin mixing Python and C++ multiple inheritance, 16812391Sjason@lowepower.comthings will fall apart due to differences between Python's MRO and C++'s 16912391Sjason@lowepower.commechanisms. 17012391Sjason@lowepower.com 17111986Sandreas.sandberg@arm.comPlease take a look at the :ref:`macro_notes` before using this feature. 17211986Sandreas.sandberg@arm.com 17311986Sandreas.sandberg@arm.com.. note:: 17411986Sandreas.sandberg@arm.com 17511986Sandreas.sandberg@arm.com When the overridden type returns a reference or pointer to a type that 17611986Sandreas.sandberg@arm.com pybind11 converts from Python (for example, numeric values, std::string, 17711986Sandreas.sandberg@arm.com and other built-in value-converting types), there are some limitations to 17811986Sandreas.sandberg@arm.com be aware of: 17911986Sandreas.sandberg@arm.com 18011986Sandreas.sandberg@arm.com - because in these cases there is no C++ variable to reference (the value 18111986Sandreas.sandberg@arm.com is stored in the referenced Python variable), pybind11 provides one in 18211986Sandreas.sandberg@arm.com the PYBIND11_OVERLOAD macros (when needed) with static storage duration. 18311986Sandreas.sandberg@arm.com Note that this means that invoking the overloaded method on *any* 18411986Sandreas.sandberg@arm.com instance will change the referenced value stored in *all* instances of 18511986Sandreas.sandberg@arm.com that type. 18611986Sandreas.sandberg@arm.com 18711986Sandreas.sandberg@arm.com - Attempts to modify a non-const reference will not have the desired 18811986Sandreas.sandberg@arm.com effect: it will change only the static cache variable, but this change 18911986Sandreas.sandberg@arm.com will not propagate to underlying Python instance, and the change will be 19011986Sandreas.sandberg@arm.com replaced the next time the overload is invoked. 19111986Sandreas.sandberg@arm.com 19211986Sandreas.sandberg@arm.com.. seealso:: 19311986Sandreas.sandberg@arm.com 19411986Sandreas.sandberg@arm.com The file :file:`tests/test_virtual_functions.cpp` contains a complete 19511986Sandreas.sandberg@arm.com example that demonstrates how to override virtual functions using pybind11 19611986Sandreas.sandberg@arm.com in more detail. 19711986Sandreas.sandberg@arm.com 19811986Sandreas.sandberg@arm.com.. _virtual_and_inheritance: 19911986Sandreas.sandberg@arm.com 20011986Sandreas.sandberg@arm.comCombining virtual functions and inheritance 20111986Sandreas.sandberg@arm.com=========================================== 20211986Sandreas.sandberg@arm.com 20311986Sandreas.sandberg@arm.comWhen combining virtual methods with inheritance, you need to be sure to provide 20411986Sandreas.sandberg@arm.coman override for each method for which you want to allow overrides from derived 20511986Sandreas.sandberg@arm.compython classes. For example, suppose we extend the above ``Animal``/``Dog`` 20611986Sandreas.sandberg@arm.comexample as follows: 20711986Sandreas.sandberg@arm.com 20811986Sandreas.sandberg@arm.com.. code-block:: cpp 20911986Sandreas.sandberg@arm.com 21011986Sandreas.sandberg@arm.com class Animal { 21111986Sandreas.sandberg@arm.com public: 21211986Sandreas.sandberg@arm.com virtual std::string go(int n_times) = 0; 21311986Sandreas.sandberg@arm.com virtual std::string name() { return "unknown"; } 21411986Sandreas.sandberg@arm.com }; 21512037Sandreas.sandberg@arm.com class Dog : public Animal { 21611986Sandreas.sandberg@arm.com public: 21711986Sandreas.sandberg@arm.com std::string go(int n_times) override { 21811986Sandreas.sandberg@arm.com std::string result; 21911986Sandreas.sandberg@arm.com for (int i=0; i<n_times; ++i) 22011986Sandreas.sandberg@arm.com result += bark() + " "; 22111986Sandreas.sandberg@arm.com return result; 22211986Sandreas.sandberg@arm.com } 22311986Sandreas.sandberg@arm.com virtual std::string bark() { return "woof!"; } 22411986Sandreas.sandberg@arm.com }; 22511986Sandreas.sandberg@arm.com 22611986Sandreas.sandberg@arm.comthen the trampoline class for ``Animal`` must, as described in the previous 22711986Sandreas.sandberg@arm.comsection, override ``go()`` and ``name()``, but in order to allow python code to 22811986Sandreas.sandberg@arm.cominherit properly from ``Dog``, we also need a trampoline class for ``Dog`` that 22911986Sandreas.sandberg@arm.comoverrides both the added ``bark()`` method *and* the ``go()`` and ``name()`` 23011986Sandreas.sandberg@arm.commethods inherited from ``Animal`` (even though ``Dog`` doesn't directly 23111986Sandreas.sandberg@arm.comoverride the ``name()`` method): 23211986Sandreas.sandberg@arm.com 23311986Sandreas.sandberg@arm.com.. code-block:: cpp 23411986Sandreas.sandberg@arm.com 23511986Sandreas.sandberg@arm.com class PyAnimal : public Animal { 23611986Sandreas.sandberg@arm.com public: 23711986Sandreas.sandberg@arm.com using Animal::Animal; // Inherit constructors 23811986Sandreas.sandberg@arm.com std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Animal, go, n_times); } 23911986Sandreas.sandberg@arm.com std::string name() override { PYBIND11_OVERLOAD(std::string, Animal, name, ); } 24011986Sandreas.sandberg@arm.com }; 24111986Sandreas.sandberg@arm.com class PyDog : public Dog { 24211986Sandreas.sandberg@arm.com public: 24311986Sandreas.sandberg@arm.com using Dog::Dog; // Inherit constructors 24411986Sandreas.sandberg@arm.com std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Dog, go, n_times); } 24511986Sandreas.sandberg@arm.com std::string name() override { PYBIND11_OVERLOAD(std::string, Dog, name, ); } 24611986Sandreas.sandberg@arm.com std::string bark() override { PYBIND11_OVERLOAD(std::string, Dog, bark, ); } 24711986Sandreas.sandberg@arm.com }; 24811986Sandreas.sandberg@arm.com 24912037Sandreas.sandberg@arm.com.. note:: 25012037Sandreas.sandberg@arm.com 25112037Sandreas.sandberg@arm.com Note the trailing commas in the ``PYBIND11_OVERLOAD`` calls to ``name()`` 25212037Sandreas.sandberg@arm.com and ``bark()``. These are needed to portably implement a trampoline for a 25312037Sandreas.sandberg@arm.com function that does not take any arguments. For functions that take 25412037Sandreas.sandberg@arm.com a nonzero number of arguments, the trailing comma must be omitted. 25512037Sandreas.sandberg@arm.com 25611986Sandreas.sandberg@arm.comA registered class derived from a pybind11-registered class with virtual 25711986Sandreas.sandberg@arm.commethods requires a similar trampoline class, *even if* it doesn't explicitly 25811986Sandreas.sandberg@arm.comdeclare or override any virtual methods itself: 25911986Sandreas.sandberg@arm.com 26011986Sandreas.sandberg@arm.com.. code-block:: cpp 26111986Sandreas.sandberg@arm.com 26211986Sandreas.sandberg@arm.com class Husky : public Dog {}; 26311986Sandreas.sandberg@arm.com class PyHusky : public Husky { 26412037Sandreas.sandberg@arm.com public: 26512037Sandreas.sandberg@arm.com using Husky::Husky; // Inherit constructors 26611986Sandreas.sandberg@arm.com std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Husky, go, n_times); } 26711986Sandreas.sandberg@arm.com std::string name() override { PYBIND11_OVERLOAD(std::string, Husky, name, ); } 26811986Sandreas.sandberg@arm.com std::string bark() override { PYBIND11_OVERLOAD(std::string, Husky, bark, ); } 26911986Sandreas.sandberg@arm.com }; 27011986Sandreas.sandberg@arm.com 27111986Sandreas.sandberg@arm.comThere is, however, a technique that can be used to avoid this duplication 27211986Sandreas.sandberg@arm.com(which can be especially helpful for a base class with several virtual 27311986Sandreas.sandberg@arm.commethods). The technique involves using template trampoline classes, as 27411986Sandreas.sandberg@arm.comfollows: 27511986Sandreas.sandberg@arm.com 27611986Sandreas.sandberg@arm.com.. code-block:: cpp 27711986Sandreas.sandberg@arm.com 27811986Sandreas.sandberg@arm.com template <class AnimalBase = Animal> class PyAnimal : public AnimalBase { 27912037Sandreas.sandberg@arm.com public: 28011986Sandreas.sandberg@arm.com using AnimalBase::AnimalBase; // Inherit constructors 28111986Sandreas.sandberg@arm.com std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, AnimalBase, go, n_times); } 28211986Sandreas.sandberg@arm.com std::string name() override { PYBIND11_OVERLOAD(std::string, AnimalBase, name, ); } 28311986Sandreas.sandberg@arm.com }; 28411986Sandreas.sandberg@arm.com template <class DogBase = Dog> class PyDog : public PyAnimal<DogBase> { 28512037Sandreas.sandberg@arm.com public: 28611986Sandreas.sandberg@arm.com using PyAnimal<DogBase>::PyAnimal; // Inherit constructors 28711986Sandreas.sandberg@arm.com // Override PyAnimal's pure virtual go() with a non-pure one: 28811986Sandreas.sandberg@arm.com std::string go(int n_times) override { PYBIND11_OVERLOAD(std::string, DogBase, go, n_times); } 28911986Sandreas.sandberg@arm.com std::string bark() override { PYBIND11_OVERLOAD(std::string, DogBase, bark, ); } 29011986Sandreas.sandberg@arm.com }; 29111986Sandreas.sandberg@arm.com 29211986Sandreas.sandberg@arm.comThis technique has the advantage of requiring just one trampoline method to be 29311986Sandreas.sandberg@arm.comdeclared per virtual method and pure virtual method override. It does, 29411986Sandreas.sandberg@arm.comhowever, require the compiler to generate at least as many methods (and 29511986Sandreas.sandberg@arm.compossibly more, if both pure virtual and overridden pure virtual methods are 29611986Sandreas.sandberg@arm.comexposed, as above). 29711986Sandreas.sandberg@arm.com 29811986Sandreas.sandberg@arm.comThe classes are then registered with pybind11 using: 29911986Sandreas.sandberg@arm.com 30011986Sandreas.sandberg@arm.com.. code-block:: cpp 30111986Sandreas.sandberg@arm.com 30211986Sandreas.sandberg@arm.com py::class_<Animal, PyAnimal<>> animal(m, "Animal"); 30311986Sandreas.sandberg@arm.com py::class_<Dog, PyDog<>> dog(m, "Dog"); 30411986Sandreas.sandberg@arm.com py::class_<Husky, PyDog<Husky>> husky(m, "Husky"); 30511986Sandreas.sandberg@arm.com // ... add animal, dog, husky definitions 30611986Sandreas.sandberg@arm.com 30711986Sandreas.sandberg@arm.comNote that ``Husky`` did not require a dedicated trampoline template class at 30811986Sandreas.sandberg@arm.comall, since it neither declares any new virtual methods nor provides any pure 30911986Sandreas.sandberg@arm.comvirtual method implementations. 31011986Sandreas.sandberg@arm.com 31111986Sandreas.sandberg@arm.comWith either the repeated-virtuals or templated trampoline methods in place, you 31211986Sandreas.sandberg@arm.comcan now create a python class that inherits from ``Dog``: 31311986Sandreas.sandberg@arm.com 31411986Sandreas.sandberg@arm.com.. code-block:: python 31511986Sandreas.sandberg@arm.com 31611986Sandreas.sandberg@arm.com class ShihTzu(Dog): 31711986Sandreas.sandberg@arm.com def bark(self): 31811986Sandreas.sandberg@arm.com return "yip!" 31911986Sandreas.sandberg@arm.com 32011986Sandreas.sandberg@arm.com.. seealso:: 32111986Sandreas.sandberg@arm.com 32211986Sandreas.sandberg@arm.com See the file :file:`tests/test_virtual_functions.cpp` for complete examples 32311986Sandreas.sandberg@arm.com using both the duplication and templated trampoline approaches. 32411986Sandreas.sandberg@arm.com 32512391Sjason@lowepower.com.. _extended_aliases: 32612391Sjason@lowepower.com 32711986Sandreas.sandberg@arm.comExtended trampoline class functionality 32811986Sandreas.sandberg@arm.com======================================= 32911986Sandreas.sandberg@arm.com 33011986Sandreas.sandberg@arm.comThe trampoline classes described in the previous sections are, by default, only 33111986Sandreas.sandberg@arm.cominitialized when needed. More specifically, they are initialized when a python 33211986Sandreas.sandberg@arm.comclass actually inherits from a registered type (instead of merely creating an 33311986Sandreas.sandberg@arm.cominstance of the registered type), or when a registered constructor is only 33411986Sandreas.sandberg@arm.comvalid for the trampoline class but not the registered class. This is primarily 33511986Sandreas.sandberg@arm.comfor performance reasons: when the trampoline class is not needed for anything 33611986Sandreas.sandberg@arm.comexcept virtual method dispatching, not initializing the trampoline class 33711986Sandreas.sandberg@arm.comimproves performance by avoiding needing to do a run-time check to see if the 33811986Sandreas.sandberg@arm.cominheriting python instance has an overloaded method. 33911986Sandreas.sandberg@arm.com 34011986Sandreas.sandberg@arm.comSometimes, however, it is useful to always initialize a trampoline class as an 34111986Sandreas.sandberg@arm.comintermediate class that does more than just handle virtual method dispatching. 34211986Sandreas.sandberg@arm.comFor example, such a class might perform extra class initialization, extra 34311986Sandreas.sandberg@arm.comdestruction operations, and might define new members and methods to enable a 34411986Sandreas.sandberg@arm.commore python-like interface to a class. 34511986Sandreas.sandberg@arm.com 34611986Sandreas.sandberg@arm.comIn order to tell pybind11 that it should *always* initialize the trampoline 34711986Sandreas.sandberg@arm.comclass when creating new instances of a type, the class constructors should be 34811986Sandreas.sandberg@arm.comdeclared using ``py::init_alias<Args, ...>()`` instead of the usual 34911986Sandreas.sandberg@arm.com``py::init<Args, ...>()``. This forces construction via the trampoline class, 35011986Sandreas.sandberg@arm.comensuring member initialization and (eventual) destruction. 35111986Sandreas.sandberg@arm.com 35211986Sandreas.sandberg@arm.com.. seealso:: 35311986Sandreas.sandberg@arm.com 35412391Sjason@lowepower.com See the file :file:`tests/test_virtual_functions.cpp` for complete examples 35511986Sandreas.sandberg@arm.com showing both normal and forced trampoline instantiation. 35611986Sandreas.sandberg@arm.com 35711986Sandreas.sandberg@arm.com.. _custom_constructors: 35811986Sandreas.sandberg@arm.com 35911986Sandreas.sandberg@arm.comCustom constructors 36011986Sandreas.sandberg@arm.com=================== 36111986Sandreas.sandberg@arm.com 36211986Sandreas.sandberg@arm.comThe syntax for binding constructors was previously introduced, but it only 36312391Sjason@lowepower.comworks when a constructor of the appropriate arguments actually exists on the 36412391Sjason@lowepower.comC++ side. To extend this to more general cases, pybind11 makes it possible 36512391Sjason@lowepower.comto bind factory functions as constructors. For example, suppose you have a 36612391Sjason@lowepower.comclass like this: 36711986Sandreas.sandberg@arm.com 36811986Sandreas.sandberg@arm.com.. code-block:: cpp 36911986Sandreas.sandberg@arm.com 37012391Sjason@lowepower.com class Example { 37112391Sjason@lowepower.com private: 37212391Sjason@lowepower.com Example(int); // private constructor 37312391Sjason@lowepower.com public: 37412391Sjason@lowepower.com // Factory function: 37512391Sjason@lowepower.com static Example create(int a) { return Example(a); } 37612391Sjason@lowepower.com }; 37712391Sjason@lowepower.com 37811986Sandreas.sandberg@arm.com py::class_<Example>(m, "Example") 37912391Sjason@lowepower.com .def(py::init(&Example::create)); 38011986Sandreas.sandberg@arm.com 38112391Sjason@lowepower.comWhile it is possible to create a straightforward binding of the static 38212391Sjason@lowepower.com``create`` method, it may sometimes be preferable to expose it as a constructor 38312391Sjason@lowepower.comon the Python side. This can be accomplished by calling ``.def(py::init(...))`` 38412391Sjason@lowepower.comwith the function reference returning the new instance passed as an argument. 38512391Sjason@lowepower.comIt is also possible to use this approach to bind a function returning a new 38612391Sjason@lowepower.cominstance by raw pointer or by the holder (e.g. ``std::unique_ptr``). 38712391Sjason@lowepower.com 38812391Sjason@lowepower.comThe following example shows the different approaches: 38911986Sandreas.sandberg@arm.com 39011986Sandreas.sandberg@arm.com.. code-block:: cpp 39111986Sandreas.sandberg@arm.com 39212391Sjason@lowepower.com class Example { 39312391Sjason@lowepower.com private: 39412391Sjason@lowepower.com Example(int); // private constructor 39512391Sjason@lowepower.com public: 39612391Sjason@lowepower.com // Factory function - returned by value: 39712391Sjason@lowepower.com static Example create(int a) { return Example(a); } 39812391Sjason@lowepower.com 39912391Sjason@lowepower.com // These constructors are publicly callable: 40012391Sjason@lowepower.com Example(double); 40112391Sjason@lowepower.com Example(int, int); 40212391Sjason@lowepower.com Example(std::string); 40312391Sjason@lowepower.com }; 40412391Sjason@lowepower.com 40511986Sandreas.sandberg@arm.com py::class_<Example>(m, "Example") 40612391Sjason@lowepower.com // Bind the factory function as a constructor: 40712391Sjason@lowepower.com .def(py::init(&Example::create)) 40812391Sjason@lowepower.com // Bind a lambda function returning a pointer wrapped in a holder: 40912391Sjason@lowepower.com .def(py::init([](std::string arg) { 41012391Sjason@lowepower.com return std::unique_ptr<Example>(new Example(arg)); 41112391Sjason@lowepower.com })) 41212391Sjason@lowepower.com // Return a raw pointer: 41312391Sjason@lowepower.com .def(py::init([](int a, int b) { return new Example(a, b); })) 41412391Sjason@lowepower.com // You can mix the above with regular C++ constructor bindings as well: 41512391Sjason@lowepower.com .def(py::init<double>()) 41612391Sjason@lowepower.com ; 41711986Sandreas.sandberg@arm.com 41812391Sjason@lowepower.comWhen the constructor is invoked from Python, pybind11 will call the factory 41912391Sjason@lowepower.comfunction and store the resulting C++ instance in the Python instance. 42012391Sjason@lowepower.com 42112391Sjason@lowepower.comWhen combining factory functions constructors with :ref:`virtual function 42212391Sjason@lowepower.comtrampolines <overriding_virtuals>` there are two approaches. The first is to 42312391Sjason@lowepower.comadd a constructor to the alias class that takes a base value by 42412391Sjason@lowepower.comrvalue-reference. If such a constructor is available, it will be used to 42512391Sjason@lowepower.comconstruct an alias instance from the value returned by the factory function. 42612391Sjason@lowepower.comThe second option is to provide two factory functions to ``py::init()``: the 42712391Sjason@lowepower.comfirst will be invoked when no alias class is required (i.e. when the class is 42812391Sjason@lowepower.combeing used but not inherited from in Python), and the second will be invoked 42912391Sjason@lowepower.comwhen an alias is required. 43012391Sjason@lowepower.com 43112391Sjason@lowepower.comYou can also specify a single factory function that always returns an alias 43212391Sjason@lowepower.cominstance: this will result in behaviour similar to ``py::init_alias<...>()``, 43312391Sjason@lowepower.comas described in the :ref:`extended trampoline class documentation 43412391Sjason@lowepower.com<extended_aliases>`. 43512391Sjason@lowepower.com 43612391Sjason@lowepower.comThe following example shows the different factory approaches for a class with 43712391Sjason@lowepower.coman alias: 43812391Sjason@lowepower.com 43912391Sjason@lowepower.com.. code-block:: cpp 44012391Sjason@lowepower.com 44112391Sjason@lowepower.com #include <pybind11/factory.h> 44212391Sjason@lowepower.com class Example { 44312391Sjason@lowepower.com public: 44412391Sjason@lowepower.com // ... 44512391Sjason@lowepower.com virtual ~Example() = default; 44612391Sjason@lowepower.com }; 44712391Sjason@lowepower.com class PyExample : public Example { 44812391Sjason@lowepower.com public: 44912391Sjason@lowepower.com using Example::Example; 45012391Sjason@lowepower.com PyExample(Example &&base) : Example(std::move(base)) {} 45112391Sjason@lowepower.com }; 45212391Sjason@lowepower.com py::class_<Example, PyExample>(m, "Example") 45312391Sjason@lowepower.com // Returns an Example pointer. If a PyExample is needed, the Example 45412391Sjason@lowepower.com // instance will be moved via the extra constructor in PyExample, above. 45512391Sjason@lowepower.com .def(py::init([]() { return new Example(); })) 45612391Sjason@lowepower.com // Two callbacks: 45712391Sjason@lowepower.com .def(py::init([]() { return new Example(); } /* no alias needed */, 45812391Sjason@lowepower.com []() { return new PyExample(); } /* alias needed */)) 45912391Sjason@lowepower.com // *Always* returns an alias instance (like py::init_alias<>()) 46012391Sjason@lowepower.com .def(py::init([]() { return new PyExample(); })) 46112391Sjason@lowepower.com ; 46212391Sjason@lowepower.com 46312391Sjason@lowepower.comBrace initialization 46412391Sjason@lowepower.com-------------------- 46512391Sjason@lowepower.com 46612391Sjason@lowepower.com``pybind11::init<>`` internally uses C++11 brace initialization to call the 46712391Sjason@lowepower.comconstructor of the target class. This means that it can be used to bind 46812391Sjason@lowepower.com*implicit* constructors as well: 46912391Sjason@lowepower.com 47012391Sjason@lowepower.com.. code-block:: cpp 47112391Sjason@lowepower.com 47212391Sjason@lowepower.com struct Aggregate { 47312391Sjason@lowepower.com int a; 47412391Sjason@lowepower.com std::string b; 47512391Sjason@lowepower.com }; 47612391Sjason@lowepower.com 47712391Sjason@lowepower.com py::class_<Aggregate>(m, "Aggregate") 47812391Sjason@lowepower.com .def(py::init<int, const std::string &>()); 47912391Sjason@lowepower.com 48012391Sjason@lowepower.com.. note:: 48112391Sjason@lowepower.com 48212391Sjason@lowepower.com Note that brace initialization preferentially invokes constructor overloads 48312391Sjason@lowepower.com taking a ``std::initializer_list``. In the rare event that this causes an 48412391Sjason@lowepower.com issue, you can work around it by using ``py::init(...)`` with a lambda 48512391Sjason@lowepower.com function that constructs the new object as desired. 48611986Sandreas.sandberg@arm.com 48711986Sandreas.sandberg@arm.com.. _classes_with_non_public_destructors: 48811986Sandreas.sandberg@arm.com 48911986Sandreas.sandberg@arm.comNon-public destructors 49011986Sandreas.sandberg@arm.com====================== 49111986Sandreas.sandberg@arm.com 49211986Sandreas.sandberg@arm.comIf a class has a private or protected destructor (as might e.g. be the case in 49311986Sandreas.sandberg@arm.coma singleton pattern), a compile error will occur when creating bindings via 49411986Sandreas.sandberg@arm.compybind11. The underlying issue is that the ``std::unique_ptr`` holder type that 49511986Sandreas.sandberg@arm.comis responsible for managing the lifetime of instances will reference the 49611986Sandreas.sandberg@arm.comdestructor even if no deallocations ever take place. In order to expose classes 49711986Sandreas.sandberg@arm.comwith private or protected destructors, it is possible to override the holder 49811986Sandreas.sandberg@arm.comtype via a holder type argument to ``class_``. Pybind11 provides a helper class 49911986Sandreas.sandberg@arm.com``py::nodelete`` that disables any destructor invocations. In this case, it is 50011986Sandreas.sandberg@arm.comcrucial that instances are deallocated on the C++ side to avoid memory leaks. 50111986Sandreas.sandberg@arm.com 50211986Sandreas.sandberg@arm.com.. code-block:: cpp 50311986Sandreas.sandberg@arm.com 50411986Sandreas.sandberg@arm.com /* ... definition ... */ 50511986Sandreas.sandberg@arm.com 50611986Sandreas.sandberg@arm.com class MyClass { 50711986Sandreas.sandberg@arm.com private: 50811986Sandreas.sandberg@arm.com ~MyClass() { } 50911986Sandreas.sandberg@arm.com }; 51011986Sandreas.sandberg@arm.com 51111986Sandreas.sandberg@arm.com /* ... binding code ... */ 51211986Sandreas.sandberg@arm.com 51311986Sandreas.sandberg@arm.com py::class_<MyClass, std::unique_ptr<MyClass, py::nodelete>>(m, "MyClass") 51412037Sandreas.sandberg@arm.com .def(py::init<>()) 51512037Sandreas.sandberg@arm.com 51612037Sandreas.sandberg@arm.com.. _implicit_conversions: 51711986Sandreas.sandberg@arm.com 51811986Sandreas.sandberg@arm.comImplicit conversions 51911986Sandreas.sandberg@arm.com==================== 52011986Sandreas.sandberg@arm.com 52111986Sandreas.sandberg@arm.comSuppose that instances of two types ``A`` and ``B`` are used in a project, and 52211986Sandreas.sandberg@arm.comthat an ``A`` can easily be converted into an instance of type ``B`` (examples of this 52311986Sandreas.sandberg@arm.comcould be a fixed and an arbitrary precision number type). 52411986Sandreas.sandberg@arm.com 52511986Sandreas.sandberg@arm.com.. code-block:: cpp 52611986Sandreas.sandberg@arm.com 52711986Sandreas.sandberg@arm.com py::class_<A>(m, "A") 52811986Sandreas.sandberg@arm.com /// ... members ... 52911986Sandreas.sandberg@arm.com 53011986Sandreas.sandberg@arm.com py::class_<B>(m, "B") 53111986Sandreas.sandberg@arm.com .def(py::init<A>()) 53211986Sandreas.sandberg@arm.com /// ... members ... 53311986Sandreas.sandberg@arm.com 53411986Sandreas.sandberg@arm.com m.def("func", 53511986Sandreas.sandberg@arm.com [](const B &) { /* .... */ } 53611986Sandreas.sandberg@arm.com ); 53711986Sandreas.sandberg@arm.com 53811986Sandreas.sandberg@arm.comTo invoke the function ``func`` using a variable ``a`` containing an ``A`` 53911986Sandreas.sandberg@arm.cominstance, we'd have to write ``func(B(a))`` in Python. On the other hand, C++ 54011986Sandreas.sandberg@arm.comwill automatically apply an implicit type conversion, which makes it possible 54111986Sandreas.sandberg@arm.comto directly write ``func(a)``. 54211986Sandreas.sandberg@arm.com 54311986Sandreas.sandberg@arm.comIn this situation (i.e. where ``B`` has a constructor that converts from 54411986Sandreas.sandberg@arm.com``A``), the following statement enables similar implicit conversions on the 54511986Sandreas.sandberg@arm.comPython side: 54611986Sandreas.sandberg@arm.com 54711986Sandreas.sandberg@arm.com.. code-block:: cpp 54811986Sandreas.sandberg@arm.com 54911986Sandreas.sandberg@arm.com py::implicitly_convertible<A, B>(); 55011986Sandreas.sandberg@arm.com 55111986Sandreas.sandberg@arm.com.. note:: 55211986Sandreas.sandberg@arm.com 55311986Sandreas.sandberg@arm.com Implicit conversions from ``A`` to ``B`` only work when ``B`` is a custom 55411986Sandreas.sandberg@arm.com data type that is exposed to Python via pybind11. 55511986Sandreas.sandberg@arm.com 55612391Sjason@lowepower.com To prevent runaway recursion, implicit conversions are non-reentrant: an 55712391Sjason@lowepower.com implicit conversion invoked as part of another implicit conversion of the 55812391Sjason@lowepower.com same type (i.e. from ``A`` to ``B``) will fail. 55912391Sjason@lowepower.com 56011986Sandreas.sandberg@arm.com.. _static_properties: 56111986Sandreas.sandberg@arm.com 56211986Sandreas.sandberg@arm.comStatic properties 56311986Sandreas.sandberg@arm.com================= 56411986Sandreas.sandberg@arm.com 56511986Sandreas.sandberg@arm.comThe section on :ref:`properties` discussed the creation of instance properties 56611986Sandreas.sandberg@arm.comthat are implemented in terms of C++ getters and setters. 56711986Sandreas.sandberg@arm.com 56811986Sandreas.sandberg@arm.comStatic properties can also be created in a similar way to expose getters and 56912037Sandreas.sandberg@arm.comsetters of static class attributes. Note that the implicit ``self`` argument 57012037Sandreas.sandberg@arm.comalso exists in this case and is used to pass the Python ``type`` subclass 57112037Sandreas.sandberg@arm.cominstance. This parameter will often not be needed by the C++ side, and the 57212037Sandreas.sandberg@arm.comfollowing example illustrates how to instantiate a lambda getter function 57312037Sandreas.sandberg@arm.comthat ignores it: 57411986Sandreas.sandberg@arm.com 57511986Sandreas.sandberg@arm.com.. code-block:: cpp 57611986Sandreas.sandberg@arm.com 57711986Sandreas.sandberg@arm.com py::class_<Foo>(m, "Foo") 57811986Sandreas.sandberg@arm.com .def_property_readonly_static("foo", [](py::object /* self */) { return Foo(); }); 57911986Sandreas.sandberg@arm.com 58011986Sandreas.sandberg@arm.comOperator overloading 58111986Sandreas.sandberg@arm.com==================== 58211986Sandreas.sandberg@arm.com 58311986Sandreas.sandberg@arm.comSuppose that we're given the following ``Vector2`` class with a vector addition 58411986Sandreas.sandberg@arm.comand scalar multiplication operation, all implemented using overloaded operators 58511986Sandreas.sandberg@arm.comin C++. 58611986Sandreas.sandberg@arm.com 58711986Sandreas.sandberg@arm.com.. code-block:: cpp 58811986Sandreas.sandberg@arm.com 58911986Sandreas.sandberg@arm.com class Vector2 { 59011986Sandreas.sandberg@arm.com public: 59111986Sandreas.sandberg@arm.com Vector2(float x, float y) : x(x), y(y) { } 59211986Sandreas.sandberg@arm.com 59311986Sandreas.sandberg@arm.com Vector2 operator+(const Vector2 &v) const { return Vector2(x + v.x, y + v.y); } 59411986Sandreas.sandberg@arm.com Vector2 operator*(float value) const { return Vector2(x * value, y * value); } 59511986Sandreas.sandberg@arm.com Vector2& operator+=(const Vector2 &v) { x += v.x; y += v.y; return *this; } 59611986Sandreas.sandberg@arm.com Vector2& operator*=(float v) { x *= v; y *= v; return *this; } 59711986Sandreas.sandberg@arm.com 59811986Sandreas.sandberg@arm.com friend Vector2 operator*(float f, const Vector2 &v) { 59911986Sandreas.sandberg@arm.com return Vector2(f * v.x, f * v.y); 60011986Sandreas.sandberg@arm.com } 60111986Sandreas.sandberg@arm.com 60211986Sandreas.sandberg@arm.com std::string toString() const { 60311986Sandreas.sandberg@arm.com return "[" + std::to_string(x) + ", " + std::to_string(y) + "]"; 60411986Sandreas.sandberg@arm.com } 60511986Sandreas.sandberg@arm.com private: 60611986Sandreas.sandberg@arm.com float x, y; 60711986Sandreas.sandberg@arm.com }; 60811986Sandreas.sandberg@arm.com 60911986Sandreas.sandberg@arm.comThe following snippet shows how the above operators can be conveniently exposed 61011986Sandreas.sandberg@arm.comto Python. 61111986Sandreas.sandberg@arm.com 61211986Sandreas.sandberg@arm.com.. code-block:: cpp 61311986Sandreas.sandberg@arm.com 61411986Sandreas.sandberg@arm.com #include <pybind11/operators.h> 61511986Sandreas.sandberg@arm.com 61612391Sjason@lowepower.com PYBIND11_MODULE(example, m) { 61711986Sandreas.sandberg@arm.com py::class_<Vector2>(m, "Vector2") 61811986Sandreas.sandberg@arm.com .def(py::init<float, float>()) 61911986Sandreas.sandberg@arm.com .def(py::self + py::self) 62011986Sandreas.sandberg@arm.com .def(py::self += py::self) 62111986Sandreas.sandberg@arm.com .def(py::self *= float()) 62211986Sandreas.sandberg@arm.com .def(float() * py::self) 62312037Sandreas.sandberg@arm.com .def(py::self * float()) 62411986Sandreas.sandberg@arm.com .def("__repr__", &Vector2::toString); 62511986Sandreas.sandberg@arm.com } 62611986Sandreas.sandberg@arm.com 62711986Sandreas.sandberg@arm.comNote that a line like 62811986Sandreas.sandberg@arm.com 62911986Sandreas.sandberg@arm.com.. code-block:: cpp 63011986Sandreas.sandberg@arm.com 63111986Sandreas.sandberg@arm.com .def(py::self * float()) 63211986Sandreas.sandberg@arm.com 63311986Sandreas.sandberg@arm.comis really just short hand notation for 63411986Sandreas.sandberg@arm.com 63511986Sandreas.sandberg@arm.com.. code-block:: cpp 63611986Sandreas.sandberg@arm.com 63711986Sandreas.sandberg@arm.com .def("__mul__", [](const Vector2 &a, float b) { 63811986Sandreas.sandberg@arm.com return a * b; 63911986Sandreas.sandberg@arm.com }, py::is_operator()) 64011986Sandreas.sandberg@arm.com 64111986Sandreas.sandberg@arm.comThis can be useful for exposing additional operators that don't exist on the 64211986Sandreas.sandberg@arm.comC++ side, or to perform other types of customization. The ``py::is_operator`` 64311986Sandreas.sandberg@arm.comflag marker is needed to inform pybind11 that this is an operator, which 64411986Sandreas.sandberg@arm.comreturns ``NotImplemented`` when invoked with incompatible arguments rather than 64511986Sandreas.sandberg@arm.comthrowing a type error. 64611986Sandreas.sandberg@arm.com 64711986Sandreas.sandberg@arm.com.. note:: 64811986Sandreas.sandberg@arm.com 64911986Sandreas.sandberg@arm.com To use the more convenient ``py::self`` notation, the additional 65011986Sandreas.sandberg@arm.com header file :file:`pybind11/operators.h` must be included. 65111986Sandreas.sandberg@arm.com 65211986Sandreas.sandberg@arm.com.. seealso:: 65311986Sandreas.sandberg@arm.com 65411986Sandreas.sandberg@arm.com The file :file:`tests/test_operator_overloading.cpp` contains a 65511986Sandreas.sandberg@arm.com complete example that demonstrates how to work with overloaded operators in 65611986Sandreas.sandberg@arm.com more detail. 65711986Sandreas.sandberg@arm.com 65812391Sjason@lowepower.com.. _pickling: 65912391Sjason@lowepower.com 66011986Sandreas.sandberg@arm.comPickling support 66111986Sandreas.sandberg@arm.com================ 66211986Sandreas.sandberg@arm.com 66311986Sandreas.sandberg@arm.comPython's ``pickle`` module provides a powerful facility to serialize and 66411986Sandreas.sandberg@arm.comde-serialize a Python object graph into a binary data stream. To pickle and 66512391Sjason@lowepower.comunpickle C++ classes using pybind11, a ``py::pickle()`` definition must be 66612391Sjason@lowepower.comprovided. Suppose the class in question has the following signature: 66711986Sandreas.sandberg@arm.com 66811986Sandreas.sandberg@arm.com.. code-block:: cpp 66911986Sandreas.sandberg@arm.com 67011986Sandreas.sandberg@arm.com class Pickleable { 67111986Sandreas.sandberg@arm.com public: 67211986Sandreas.sandberg@arm.com Pickleable(const std::string &value) : m_value(value) { } 67311986Sandreas.sandberg@arm.com const std::string &value() const { return m_value; } 67411986Sandreas.sandberg@arm.com 67511986Sandreas.sandberg@arm.com void setExtra(int extra) { m_extra = extra; } 67611986Sandreas.sandberg@arm.com int extra() const { return m_extra; } 67711986Sandreas.sandberg@arm.com private: 67811986Sandreas.sandberg@arm.com std::string m_value; 67911986Sandreas.sandberg@arm.com int m_extra = 0; 68011986Sandreas.sandberg@arm.com }; 68111986Sandreas.sandberg@arm.com 68212391Sjason@lowepower.comPickling support in Python is enabled by defining the ``__setstate__`` and 68312391Sjason@lowepower.com``__getstate__`` methods [#f3]_. For pybind11 classes, use ``py::pickle()`` 68412391Sjason@lowepower.comto bind these two functions: 68511986Sandreas.sandberg@arm.com 68611986Sandreas.sandberg@arm.com.. code-block:: cpp 68711986Sandreas.sandberg@arm.com 68811986Sandreas.sandberg@arm.com py::class_<Pickleable>(m, "Pickleable") 68911986Sandreas.sandberg@arm.com .def(py::init<std::string>()) 69011986Sandreas.sandberg@arm.com .def("value", &Pickleable::value) 69111986Sandreas.sandberg@arm.com .def("extra", &Pickleable::extra) 69211986Sandreas.sandberg@arm.com .def("setExtra", &Pickleable::setExtra) 69312391Sjason@lowepower.com .def(py::pickle( 69412391Sjason@lowepower.com [](const Pickleable &p) { // __getstate__ 69512391Sjason@lowepower.com /* Return a tuple that fully encodes the state of the object */ 69612391Sjason@lowepower.com return py::make_tuple(p.value(), p.extra()); 69712391Sjason@lowepower.com }, 69812391Sjason@lowepower.com [](py::tuple t) { // __setstate__ 69912391Sjason@lowepower.com if (t.size() != 2) 70012391Sjason@lowepower.com throw std::runtime_error("Invalid state!"); 70111986Sandreas.sandberg@arm.com 70212391Sjason@lowepower.com /* Create a new C++ instance */ 70312391Sjason@lowepower.com Pickleable p(t[0].cast<std::string>()); 70411986Sandreas.sandberg@arm.com 70512391Sjason@lowepower.com /* Assign any additional state */ 70612391Sjason@lowepower.com p.setExtra(t[1].cast<int>()); 70712391Sjason@lowepower.com 70812391Sjason@lowepower.com return p; 70912391Sjason@lowepower.com } 71012391Sjason@lowepower.com )); 71112391Sjason@lowepower.com 71212391Sjason@lowepower.comThe ``__setstate__`` part of the ``py::picke()`` definition follows the same 71312391Sjason@lowepower.comrules as the single-argument version of ``py::init()``. The return type can be 71412391Sjason@lowepower.coma value, pointer or holder type. See :ref:`custom_constructors` for details. 71511986Sandreas.sandberg@arm.com 71611986Sandreas.sandberg@arm.comAn instance can now be pickled as follows: 71711986Sandreas.sandberg@arm.com 71811986Sandreas.sandberg@arm.com.. code-block:: python 71911986Sandreas.sandberg@arm.com 72011986Sandreas.sandberg@arm.com try: 72111986Sandreas.sandberg@arm.com import cPickle as pickle # Use cPickle on Python 2.7 72211986Sandreas.sandberg@arm.com except ImportError: 72311986Sandreas.sandberg@arm.com import pickle 72411986Sandreas.sandberg@arm.com 72511986Sandreas.sandberg@arm.com p = Pickleable("test_value") 72611986Sandreas.sandberg@arm.com p.setExtra(15) 72711986Sandreas.sandberg@arm.com data = pickle.dumps(p, 2) 72811986Sandreas.sandberg@arm.com 72911986Sandreas.sandberg@arm.comNote that only the cPickle module is supported on Python 2.7. The second 73011986Sandreas.sandberg@arm.comargument to ``dumps`` is also crucial: it selects the pickle protocol version 73111986Sandreas.sandberg@arm.com2, since the older version 1 is not supported. Newer versions are also fine—for 73211986Sandreas.sandberg@arm.cominstance, specify ``-1`` to always use the latest available version. Beware: 73311986Sandreas.sandberg@arm.comfailure to follow these instructions will cause important pybind11 memory 73411986Sandreas.sandberg@arm.comallocation routines to be skipped during unpickling, which will likely lead to 73511986Sandreas.sandberg@arm.commemory corruption and/or segmentation faults. 73611986Sandreas.sandberg@arm.com 73711986Sandreas.sandberg@arm.com.. seealso:: 73811986Sandreas.sandberg@arm.com 73911986Sandreas.sandberg@arm.com The file :file:`tests/test_pickling.cpp` contains a complete example 74011986Sandreas.sandberg@arm.com that demonstrates how to pickle and unpickle types using pybind11 in more 74111986Sandreas.sandberg@arm.com detail. 74211986Sandreas.sandberg@arm.com 74311986Sandreas.sandberg@arm.com.. [#f3] http://docs.python.org/3/library/pickle.html#pickling-class-instances 74411986Sandreas.sandberg@arm.com 74511986Sandreas.sandberg@arm.comMultiple Inheritance 74611986Sandreas.sandberg@arm.com==================== 74711986Sandreas.sandberg@arm.com 74811986Sandreas.sandberg@arm.compybind11 can create bindings for types that derive from multiple base types 74911986Sandreas.sandberg@arm.com(aka. *multiple inheritance*). To do so, specify all bases in the template 75011986Sandreas.sandberg@arm.comarguments of the ``class_`` declaration: 75111986Sandreas.sandberg@arm.com 75211986Sandreas.sandberg@arm.com.. code-block:: cpp 75311986Sandreas.sandberg@arm.com 75411986Sandreas.sandberg@arm.com py::class_<MyType, BaseType1, BaseType2, BaseType3>(m, "MyType") 75511986Sandreas.sandberg@arm.com ... 75611986Sandreas.sandberg@arm.com 75711986Sandreas.sandberg@arm.comThe base types can be specified in arbitrary order, and they can even be 75811986Sandreas.sandberg@arm.cominterspersed with alias types and holder types (discussed earlier in this 75911986Sandreas.sandberg@arm.comdocument)---pybind11 will automatically find out which is which. The only 76011986Sandreas.sandberg@arm.comrequirement is that the first template argument is the type to be declared. 76111986Sandreas.sandberg@arm.com 76212391Sjason@lowepower.comIt is also permitted to inherit multiply from exported C++ classes in Python, 76312391Sjason@lowepower.comas well as inheriting from multiple Python and/or pybind-exported classes. 76411986Sandreas.sandberg@arm.com 76512391Sjason@lowepower.comThere is one caveat regarding the implementation of this feature: 76611986Sandreas.sandberg@arm.com 76712391Sjason@lowepower.comWhen only one base type is specified for a C++ type that actually has multiple 76812391Sjason@lowepower.combases, pybind11 will assume that it does not participate in multiple 76912391Sjason@lowepower.cominheritance, which can lead to undefined behavior. In such cases, add the tag 77012391Sjason@lowepower.com``multiple_inheritance`` to the class constructor: 77111986Sandreas.sandberg@arm.com 77212391Sjason@lowepower.com.. code-block:: cpp 77311986Sandreas.sandberg@arm.com 77412391Sjason@lowepower.com py::class_<MyType, BaseType2>(m, "MyType", py::multiple_inheritance()); 77511986Sandreas.sandberg@arm.com 77612391Sjason@lowepower.comThe tag is redundant and does not need to be specified when multiple base types 77712391Sjason@lowepower.comare listed. 77812391Sjason@lowepower.com 77912391Sjason@lowepower.com.. _module_local: 78012391Sjason@lowepower.com 78112391Sjason@lowepower.comModule-local class bindings 78212391Sjason@lowepower.com=========================== 78312391Sjason@lowepower.com 78412391Sjason@lowepower.comWhen creating a binding for a class, pybind by default makes that binding 78512391Sjason@lowepower.com"global" across modules. What this means is that a type defined in one module 78612391Sjason@lowepower.comcan be returned from any module resulting in the same Python type. For 78712391Sjason@lowepower.comexample, this allows the following: 78812391Sjason@lowepower.com 78912391Sjason@lowepower.com.. code-block:: cpp 79012391Sjason@lowepower.com 79112391Sjason@lowepower.com // In the module1.cpp binding code for module1: 79212391Sjason@lowepower.com py::class_<Pet>(m, "Pet") 79312391Sjason@lowepower.com .def(py::init<std::string>()) 79412391Sjason@lowepower.com .def_readonly("name", &Pet::name); 79512391Sjason@lowepower.com 79612391Sjason@lowepower.com.. code-block:: cpp 79712391Sjason@lowepower.com 79812391Sjason@lowepower.com // In the module2.cpp binding code for module2: 79912391Sjason@lowepower.com m.def("create_pet", [](std::string name) { return new Pet(name); }); 80012391Sjason@lowepower.com 80112391Sjason@lowepower.com.. code-block:: pycon 80212391Sjason@lowepower.com 80312391Sjason@lowepower.com >>> from module1 import Pet 80412391Sjason@lowepower.com >>> from module2 import create_pet 80512391Sjason@lowepower.com >>> pet1 = Pet("Kitty") 80612391Sjason@lowepower.com >>> pet2 = create_pet("Doggy") 80712391Sjason@lowepower.com >>> pet2.name() 80812391Sjason@lowepower.com 'Doggy' 80912391Sjason@lowepower.com 81012391Sjason@lowepower.comWhen writing binding code for a library, this is usually desirable: this 81112391Sjason@lowepower.comallows, for example, splitting up a complex library into multiple Python 81212391Sjason@lowepower.commodules. 81312391Sjason@lowepower.com 81412391Sjason@lowepower.comIn some cases, however, this can cause conflicts. For example, suppose two 81512391Sjason@lowepower.comunrelated modules make use of an external C++ library and each provide custom 81612391Sjason@lowepower.combindings for one of that library's classes. This will result in an error when 81712391Sjason@lowepower.coma Python program attempts to import both modules (directly or indirectly) 81812391Sjason@lowepower.combecause of conflicting definitions on the external type: 81912391Sjason@lowepower.com 82012391Sjason@lowepower.com.. code-block:: cpp 82112391Sjason@lowepower.com 82212391Sjason@lowepower.com // dogs.cpp 82312391Sjason@lowepower.com 82412391Sjason@lowepower.com // Binding for external library class: 82512391Sjason@lowepower.com py::class<pets::Pet>(m, "Pet") 82612391Sjason@lowepower.com .def("name", &pets::Pet::name); 82712391Sjason@lowepower.com 82812391Sjason@lowepower.com // Binding for local extension class: 82912391Sjason@lowepower.com py::class<Dog, pets::Pet>(m, "Dog") 83012391Sjason@lowepower.com .def(py::init<std::string>()); 83112391Sjason@lowepower.com 83212391Sjason@lowepower.com.. code-block:: cpp 83312391Sjason@lowepower.com 83412391Sjason@lowepower.com // cats.cpp, in a completely separate project from the above dogs.cpp. 83512391Sjason@lowepower.com 83612391Sjason@lowepower.com // Binding for external library class: 83712391Sjason@lowepower.com py::class<pets::Pet>(m, "Pet") 83812391Sjason@lowepower.com .def("get_name", &pets::Pet::name); 83912391Sjason@lowepower.com 84012391Sjason@lowepower.com // Binding for local extending class: 84112391Sjason@lowepower.com py::class<Cat, pets::Pet>(m, "Cat") 84212391Sjason@lowepower.com .def(py::init<std::string>()); 84312391Sjason@lowepower.com 84412391Sjason@lowepower.com.. code-block:: pycon 84512391Sjason@lowepower.com 84612391Sjason@lowepower.com >>> import cats 84712391Sjason@lowepower.com >>> import dogs 84812391Sjason@lowepower.com Traceback (most recent call last): 84912391Sjason@lowepower.com File "<stdin>", line 1, in <module> 85012391Sjason@lowepower.com ImportError: generic_type: type "Pet" is already registered! 85112391Sjason@lowepower.com 85212391Sjason@lowepower.comTo get around this, you can tell pybind11 to keep the external class binding 85312391Sjason@lowepower.comlocalized to the module by passing the ``py::module_local()`` attribute into 85412391Sjason@lowepower.comthe ``py::class_`` constructor: 85512391Sjason@lowepower.com 85612391Sjason@lowepower.com.. code-block:: cpp 85712391Sjason@lowepower.com 85812391Sjason@lowepower.com // Pet binding in dogs.cpp: 85912391Sjason@lowepower.com py::class<pets::Pet>(m, "Pet", py::module_local()) 86012391Sjason@lowepower.com .def("name", &pets::Pet::name); 86112391Sjason@lowepower.com 86212391Sjason@lowepower.com.. code-block:: cpp 86312391Sjason@lowepower.com 86412391Sjason@lowepower.com // Pet binding in cats.cpp: 86512391Sjason@lowepower.com py::class<pets::Pet>(m, "Pet", py::module_local()) 86612391Sjason@lowepower.com .def("get_name", &pets::Pet::name); 86712391Sjason@lowepower.com 86812391Sjason@lowepower.comThis makes the Python-side ``dogs.Pet`` and ``cats.Pet`` into distinct classes, 86912391Sjason@lowepower.comavoiding the conflict and allowing both modules to be loaded. C++ code in the 87012391Sjason@lowepower.com``dogs`` module that casts or returns a ``Pet`` instance will result in a 87112391Sjason@lowepower.com``dogs.Pet`` Python instance, while C++ code in the ``cats`` module will result 87212391Sjason@lowepower.comin a ``cats.Pet`` Python instance. 87312391Sjason@lowepower.com 87412391Sjason@lowepower.comThis does come with two caveats, however: First, external modules cannot return 87512391Sjason@lowepower.comor cast a ``Pet`` instance to Python (unless they also provide their own local 87612391Sjason@lowepower.combindings). Second, from the Python point of view they are two distinct classes. 87712391Sjason@lowepower.com 87812391Sjason@lowepower.comNote that the locality only applies in the C++ -> Python direction. When 87912391Sjason@lowepower.compassing such a ``py::module_local`` type into a C++ function, the module-local 88012391Sjason@lowepower.comclasses are still considered. This means that if the following function is 88112391Sjason@lowepower.comadded to any module (including but not limited to the ``cats`` and ``dogs`` 88212391Sjason@lowepower.commodules above) it will be callable with either a ``dogs.Pet`` or ``cats.Pet`` 88312391Sjason@lowepower.comargument: 88412391Sjason@lowepower.com 88512391Sjason@lowepower.com.. code-block:: cpp 88612391Sjason@lowepower.com 88712391Sjason@lowepower.com m.def("pet_name", [](const pets::Pet &pet) { return pet.name(); }); 88812391Sjason@lowepower.com 88912391Sjason@lowepower.comFor example, suppose the above function is added to each of ``cats.cpp``, 89012391Sjason@lowepower.com``dogs.cpp`` and ``frogs.cpp`` (where ``frogs.cpp`` is some other module that 89112391Sjason@lowepower.comdoes *not* bind ``Pets`` at all). 89212391Sjason@lowepower.com 89312391Sjason@lowepower.com.. code-block:: pycon 89412391Sjason@lowepower.com 89512391Sjason@lowepower.com >>> import cats, dogs, frogs # No error because of the added py::module_local() 89612391Sjason@lowepower.com >>> mycat, mydog = cats.Cat("Fluffy"), dogs.Dog("Rover") 89712391Sjason@lowepower.com >>> (cats.pet_name(mycat), dogs.pet_name(mydog)) 89812391Sjason@lowepower.com ('Fluffy', 'Rover') 89912391Sjason@lowepower.com >>> (cats.pet_name(mydog), dogs.pet_name(mycat), frogs.pet_name(mycat)) 90012391Sjason@lowepower.com ('Rover', 'Fluffy', 'Fluffy') 90112391Sjason@lowepower.com 90212391Sjason@lowepower.comIt is possible to use ``py::module_local()`` registrations in one module even 90312391Sjason@lowepower.comif another module registers the same type globally: within the module with the 90412391Sjason@lowepower.commodule-local definition, all C++ instances will be cast to the associated bound 90512391Sjason@lowepower.comPython type. In other modules any such values are converted to the global 90612391Sjason@lowepower.comPython type created elsewhere. 90712391Sjason@lowepower.com 90812391Sjason@lowepower.com.. note:: 90912391Sjason@lowepower.com 91012391Sjason@lowepower.com STL bindings (as provided via the optional :file:`pybind11/stl_bind.h` 91112391Sjason@lowepower.com header) apply ``py::module_local`` by default when the bound type might 91212391Sjason@lowepower.com conflict with other modules; see :ref:`stl_bind` for details. 91312391Sjason@lowepower.com 91412391Sjason@lowepower.com.. note:: 91512391Sjason@lowepower.com 91612391Sjason@lowepower.com The localization of the bound types is actually tied to the shared object 91712391Sjason@lowepower.com or binary generated by the compiler/linker. For typical modules created 91812391Sjason@lowepower.com with ``PYBIND11_MODULE()``, this distinction is not significant. It is 91912391Sjason@lowepower.com possible, however, when :ref:`embedding` to embed multiple modules in the 92012391Sjason@lowepower.com same binary (see :ref:`embedding_modules`). In such a case, the 92112391Sjason@lowepower.com localization will apply across all embedded modules within the same binary. 92212391Sjason@lowepower.com 92312391Sjason@lowepower.com.. seealso:: 92412391Sjason@lowepower.com 92512391Sjason@lowepower.com The file :file:`tests/test_local_bindings.cpp` contains additional examples 92612391Sjason@lowepower.com that demonstrate how ``py::module_local()`` works. 92712391Sjason@lowepower.com 92812391Sjason@lowepower.comBinding protected member functions 92912391Sjason@lowepower.com================================== 93012391Sjason@lowepower.com 93112391Sjason@lowepower.comIt's normally not possible to expose ``protected`` member functions to Python: 93212391Sjason@lowepower.com 93312391Sjason@lowepower.com.. code-block:: cpp 93412391Sjason@lowepower.com 93512391Sjason@lowepower.com class A { 93612391Sjason@lowepower.com protected: 93712391Sjason@lowepower.com int foo() const { return 42; } 93812391Sjason@lowepower.com }; 93912391Sjason@lowepower.com 94012391Sjason@lowepower.com py::class_<A>(m, "A") 94112391Sjason@lowepower.com .def("foo", &A::foo); // error: 'foo' is a protected member of 'A' 94212391Sjason@lowepower.com 94312391Sjason@lowepower.comOn one hand, this is good because non-``public`` members aren't meant to be 94412391Sjason@lowepower.comaccessed from the outside. But we may want to make use of ``protected`` 94512391Sjason@lowepower.comfunctions in derived Python classes. 94612391Sjason@lowepower.com 94712391Sjason@lowepower.comThe following pattern makes this possible: 94812391Sjason@lowepower.com 94912391Sjason@lowepower.com.. code-block:: cpp 95012391Sjason@lowepower.com 95112391Sjason@lowepower.com class A { 95212391Sjason@lowepower.com protected: 95312391Sjason@lowepower.com int foo() const { return 42; } 95412391Sjason@lowepower.com }; 95512391Sjason@lowepower.com 95612391Sjason@lowepower.com class Publicist : public A { // helper type for exposing protected functions 95712391Sjason@lowepower.com public: 95812391Sjason@lowepower.com using A::foo; // inherited with different access modifier 95912391Sjason@lowepower.com }; 96012391Sjason@lowepower.com 96112391Sjason@lowepower.com py::class_<A>(m, "A") // bind the primary class 96212391Sjason@lowepower.com .def("foo", &Publicist::foo); // expose protected methods via the publicist 96312391Sjason@lowepower.com 96412391Sjason@lowepower.comThis works because ``&Publicist::foo`` is exactly the same function as 96512391Sjason@lowepower.com``&A::foo`` (same signature and address), just with a different access 96612391Sjason@lowepower.commodifier. The only purpose of the ``Publicist`` helper class is to make 96712391Sjason@lowepower.comthe function name ``public``. 96812391Sjason@lowepower.com 96912391Sjason@lowepower.comIf the intent is to expose ``protected`` ``virtual`` functions which can be 97012391Sjason@lowepower.comoverridden in Python, the publicist pattern can be combined with the previously 97112391Sjason@lowepower.comdescribed trampoline: 97212391Sjason@lowepower.com 97312391Sjason@lowepower.com.. code-block:: cpp 97412391Sjason@lowepower.com 97512391Sjason@lowepower.com class A { 97612391Sjason@lowepower.com public: 97712391Sjason@lowepower.com virtual ~A() = default; 97812391Sjason@lowepower.com 97912391Sjason@lowepower.com protected: 98012391Sjason@lowepower.com virtual int foo() const { return 42; } 98112391Sjason@lowepower.com }; 98212391Sjason@lowepower.com 98312391Sjason@lowepower.com class Trampoline : public A { 98412391Sjason@lowepower.com public: 98512391Sjason@lowepower.com int foo() const override { PYBIND11_OVERLOAD(int, A, foo, ); } 98612391Sjason@lowepower.com }; 98712391Sjason@lowepower.com 98812391Sjason@lowepower.com class Publicist : public A { 98912391Sjason@lowepower.com public: 99012391Sjason@lowepower.com using A::foo; 99112391Sjason@lowepower.com }; 99212391Sjason@lowepower.com 99312391Sjason@lowepower.com py::class_<A, Trampoline>(m, "A") // <-- `Trampoline` here 99412391Sjason@lowepower.com .def("foo", &Publicist::foo); // <-- `Publicist` here, not `Trampoline`! 99512391Sjason@lowepower.com 99612391Sjason@lowepower.com.. note:: 99712391Sjason@lowepower.com 99812391Sjason@lowepower.com MSVC 2015 has a compiler bug (fixed in version 2017) which 99912391Sjason@lowepower.com requires a more explicit function binding in the form of 100012391Sjason@lowepower.com ``.def("foo", static_cast<int (A::*)() const>(&Publicist::foo));`` 100112391Sjason@lowepower.com where ``int (A::*)() const`` is the type of ``A::foo``. 1002