classes.rst revision 12391:ceeca8b41e4b
1Classes 2####### 3 4This section presents advanced binding code for classes and it is assumed 5that you are already familiar with the basics from :doc:`/classes`. 6 7.. _overriding_virtuals: 8 9Overriding virtual functions in Python 10====================================== 11 12Suppose that a C++ class or interface has a virtual function that we'd like to 13to override from within Python (we'll focus on the class ``Animal``; ``Dog`` is 14given as a specific example of how one would do this with traditional C++ 15code). 16 17.. code-block:: cpp 18 19 class Animal { 20 public: 21 virtual ~Animal() { } 22 virtual std::string go(int n_times) = 0; 23 }; 24 25 class Dog : public Animal { 26 public: 27 std::string go(int n_times) override { 28 std::string result; 29 for (int i=0; i<n_times; ++i) 30 result += "woof! "; 31 return result; 32 } 33 }; 34 35Let's also suppose that we are given a plain function which calls the 36function ``go()`` on an arbitrary ``Animal`` instance. 37 38.. code-block:: cpp 39 40 std::string call_go(Animal *animal) { 41 return animal->go(3); 42 } 43 44Normally, the binding code for these classes would look as follows: 45 46.. code-block:: cpp 47 48 PYBIND11_MODULE(example, m) { 49 py::class_<Animal> animal(m, "Animal"); 50 animal 51 .def("go", &Animal::go); 52 53 py::class_<Dog>(m, "Dog", animal) 54 .def(py::init<>()); 55 56 m.def("call_go", &call_go); 57 } 58 59However, these bindings are impossible to extend: ``Animal`` is not 60constructible, and we clearly require some kind of "trampoline" that 61redirects virtual calls back to Python. 62 63Defining a new type of ``Animal`` from within Python is possible but requires a 64helper class that is defined as follows: 65 66.. code-block:: cpp 67 68 class PyAnimal : public Animal { 69 public: 70 /* Inherit the constructors */ 71 using Animal::Animal; 72 73 /* Trampoline (need one for each virtual function) */ 74 std::string go(int n_times) override { 75 PYBIND11_OVERLOAD_PURE( 76 std::string, /* Return type */ 77 Animal, /* Parent class */ 78 go, /* Name of function in C++ (must match Python name) */ 79 n_times /* Argument(s) */ 80 ); 81 } 82 }; 83 84The macro :func:`PYBIND11_OVERLOAD_PURE` should be used for pure virtual 85functions, and :func:`PYBIND11_OVERLOAD` should be used for functions which have 86a default implementation. There are also two alternate macros 87:func:`PYBIND11_OVERLOAD_PURE_NAME` and :func:`PYBIND11_OVERLOAD_NAME` which 88take a string-valued name argument between the *Parent class* and *Name of the 89function* slots, which defines the name of function in Python. This is required 90when the C++ and Python versions of the 91function have different names, e.g. ``operator()`` vs ``__call__``. 92 93The binding code also needs a few minor adaptations (highlighted): 94 95.. code-block:: cpp 96 :emphasize-lines: 2,4,5 97 98 PYBIND11_MODULE(example, m) { 99 py::class_<Animal, PyAnimal /* <--- trampoline*/> animal(m, "Animal"); 100 animal 101 .def(py::init<>()) 102 .def("go", &Animal::go); 103 104 py::class_<Dog>(m, "Dog", animal) 105 .def(py::init<>()); 106 107 m.def("call_go", &call_go); 108 } 109 110Importantly, pybind11 is made aware of the trampoline helper class by 111specifying it as an extra template argument to :class:`class_`. (This can also 112be combined with other template arguments such as a custom holder type; the 113order of template types does not matter). Following this, we are able to 114define a constructor as usual. 115 116Bindings should be made against the actual class, not the trampoline helper class. 117 118.. code-block:: cpp 119 120 py::class_<Animal, PyAnimal /* <--- trampoline*/> animal(m, "Animal"); 121 animal 122 .def(py::init<>()) 123 .def("go", &PyAnimal::go); /* <--- THIS IS WRONG, use &Animal::go */ 124 125Note, however, that the above is sufficient for allowing python classes to 126extend ``Animal``, but not ``Dog``: see :ref:`virtual_and_inheritance` for the 127necessary steps required to providing proper overload support for inherited 128classes. 129 130The Python session below shows how to override ``Animal::go`` and invoke it via 131a virtual method call. 132 133.. code-block:: pycon 134 135 >>> from example import * 136 >>> d = Dog() 137 >>> call_go(d) 138 u'woof! woof! woof! ' 139 >>> class Cat(Animal): 140 ... def go(self, n_times): 141 ... return "meow! " * n_times 142 ... 143 >>> c = Cat() 144 >>> call_go(c) 145 u'meow! meow! meow! ' 146 147If you are defining a custom constructor in a derived Python class, you *must* 148ensure that you explicitly call the bound C++ constructor using ``__init__``, 149*regardless* of whether it is a default constructor or not. Otherwise, the 150memory for the C++ portion of the instance will be left uninitialized, which 151will generally leave the C++ instance in an invalid state and cause undefined 152behavior if the C++ instance is subsequently used. 153 154Here is an example: 155 156.. code-block:: python 157 158 class Dachschund(Dog): 159 def __init__(self, name): 160 Dog.__init__(self) # Without this, undefind behavior may occur if the C++ portions are referenced. 161 self.name = name 162 def bark(self): 163 return "yap!" 164 165Note that a direct ``__init__`` constructor *should be called*, and ``super()`` 166should not be used. For simple cases of linear inheritance, ``super()`` 167may work, but once you begin mixing Python and C++ multiple inheritance, 168things will fall apart due to differences between Python's MRO and C++'s 169mechanisms. 170 171Please take a look at the :ref:`macro_notes` before using this feature. 172 173.. note:: 174 175 When the overridden type returns a reference or pointer to a type that 176 pybind11 converts from Python (for example, numeric values, std::string, 177 and other built-in value-converting types), there are some limitations to 178 be aware of: 179 180 - because in these cases there is no C++ variable to reference (the value 181 is stored in the referenced Python variable), pybind11 provides one in 182 the PYBIND11_OVERLOAD macros (when needed) with static storage duration. 183 Note that this means that invoking the overloaded method on *any* 184 instance will change the referenced value stored in *all* instances of 185 that type. 186 187 - Attempts to modify a non-const reference will not have the desired 188 effect: it will change only the static cache variable, but this change 189 will not propagate to underlying Python instance, and the change will be 190 replaced the next time the overload is invoked. 191 192.. seealso:: 193 194 The file :file:`tests/test_virtual_functions.cpp` contains a complete 195 example that demonstrates how to override virtual functions using pybind11 196 in more detail. 197 198.. _virtual_and_inheritance: 199 200Combining virtual functions and inheritance 201=========================================== 202 203When combining virtual methods with inheritance, you need to be sure to provide 204an override for each method for which you want to allow overrides from derived 205python classes. For example, suppose we extend the above ``Animal``/``Dog`` 206example as follows: 207 208.. code-block:: cpp 209 210 class Animal { 211 public: 212 virtual std::string go(int n_times) = 0; 213 virtual std::string name() { return "unknown"; } 214 }; 215 class Dog : public Animal { 216 public: 217 std::string go(int n_times) override { 218 std::string result; 219 for (int i=0; i<n_times; ++i) 220 result += bark() + " "; 221 return result; 222 } 223 virtual std::string bark() { return "woof!"; } 224 }; 225 226then the trampoline class for ``Animal`` must, as described in the previous 227section, override ``go()`` and ``name()``, but in order to allow python code to 228inherit properly from ``Dog``, we also need a trampoline class for ``Dog`` that 229overrides both the added ``bark()`` method *and* the ``go()`` and ``name()`` 230methods inherited from ``Animal`` (even though ``Dog`` doesn't directly 231override the ``name()`` method): 232 233.. code-block:: cpp 234 235 class PyAnimal : public Animal { 236 public: 237 using Animal::Animal; // Inherit constructors 238 std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Animal, go, n_times); } 239 std::string name() override { PYBIND11_OVERLOAD(std::string, Animal, name, ); } 240 }; 241 class PyDog : public Dog { 242 public: 243 using Dog::Dog; // Inherit constructors 244 std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Dog, go, n_times); } 245 std::string name() override { PYBIND11_OVERLOAD(std::string, Dog, name, ); } 246 std::string bark() override { PYBIND11_OVERLOAD(std::string, Dog, bark, ); } 247 }; 248 249.. note:: 250 251 Note the trailing commas in the ``PYBIND11_OVERLOAD`` calls to ``name()`` 252 and ``bark()``. These are needed to portably implement a trampoline for a 253 function that does not take any arguments. For functions that take 254 a nonzero number of arguments, the trailing comma must be omitted. 255 256A registered class derived from a pybind11-registered class with virtual 257methods requires a similar trampoline class, *even if* it doesn't explicitly 258declare or override any virtual methods itself: 259 260.. code-block:: cpp 261 262 class Husky : public Dog {}; 263 class PyHusky : public Husky { 264 public: 265 using Husky::Husky; // Inherit constructors 266 std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Husky, go, n_times); } 267 std::string name() override { PYBIND11_OVERLOAD(std::string, Husky, name, ); } 268 std::string bark() override { PYBIND11_OVERLOAD(std::string, Husky, bark, ); } 269 }; 270 271There is, however, a technique that can be used to avoid this duplication 272(which can be especially helpful for a base class with several virtual 273methods). The technique involves using template trampoline classes, as 274follows: 275 276.. code-block:: cpp 277 278 template <class AnimalBase = Animal> class PyAnimal : public AnimalBase { 279 public: 280 using AnimalBase::AnimalBase; // Inherit constructors 281 std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, AnimalBase, go, n_times); } 282 std::string name() override { PYBIND11_OVERLOAD(std::string, AnimalBase, name, ); } 283 }; 284 template <class DogBase = Dog> class PyDog : public PyAnimal<DogBase> { 285 public: 286 using PyAnimal<DogBase>::PyAnimal; // Inherit constructors 287 // Override PyAnimal's pure virtual go() with a non-pure one: 288 std::string go(int n_times) override { PYBIND11_OVERLOAD(std::string, DogBase, go, n_times); } 289 std::string bark() override { PYBIND11_OVERLOAD(std::string, DogBase, bark, ); } 290 }; 291 292This technique has the advantage of requiring just one trampoline method to be 293declared per virtual method and pure virtual method override. It does, 294however, require the compiler to generate at least as many methods (and 295possibly more, if both pure virtual and overridden pure virtual methods are 296exposed, as above). 297 298The classes are then registered with pybind11 using: 299 300.. code-block:: cpp 301 302 py::class_<Animal, PyAnimal<>> animal(m, "Animal"); 303 py::class_<Dog, PyDog<>> dog(m, "Dog"); 304 py::class_<Husky, PyDog<Husky>> husky(m, "Husky"); 305 // ... add animal, dog, husky definitions 306 307Note that ``Husky`` did not require a dedicated trampoline template class at 308all, since it neither declares any new virtual methods nor provides any pure 309virtual method implementations. 310 311With either the repeated-virtuals or templated trampoline methods in place, you 312can now create a python class that inherits from ``Dog``: 313 314.. code-block:: python 315 316 class ShihTzu(Dog): 317 def bark(self): 318 return "yip!" 319 320.. seealso:: 321 322 See the file :file:`tests/test_virtual_functions.cpp` for complete examples 323 using both the duplication and templated trampoline approaches. 324 325.. _extended_aliases: 326 327Extended trampoline class functionality 328======================================= 329 330The trampoline classes described in the previous sections are, by default, only 331initialized when needed. More specifically, they are initialized when a python 332class actually inherits from a registered type (instead of merely creating an 333instance of the registered type), or when a registered constructor is only 334valid for the trampoline class but not the registered class. This is primarily 335for performance reasons: when the trampoline class is not needed for anything 336except virtual method dispatching, not initializing the trampoline class 337improves performance by avoiding needing to do a run-time check to see if the 338inheriting python instance has an overloaded method. 339 340Sometimes, however, it is useful to always initialize a trampoline class as an 341intermediate class that does more than just handle virtual method dispatching. 342For example, such a class might perform extra class initialization, extra 343destruction operations, and might define new members and methods to enable a 344more python-like interface to a class. 345 346In order to tell pybind11 that it should *always* initialize the trampoline 347class when creating new instances of a type, the class constructors should be 348declared using ``py::init_alias<Args, ...>()`` instead of the usual 349``py::init<Args, ...>()``. This forces construction via the trampoline class, 350ensuring member initialization and (eventual) destruction. 351 352.. seealso:: 353 354 See the file :file:`tests/test_virtual_functions.cpp` for complete examples 355 showing both normal and forced trampoline instantiation. 356 357.. _custom_constructors: 358 359Custom constructors 360=================== 361 362The syntax for binding constructors was previously introduced, but it only 363works when a constructor of the appropriate arguments actually exists on the 364C++ side. To extend this to more general cases, pybind11 makes it possible 365to bind factory functions as constructors. For example, suppose you have a 366class like this: 367 368.. code-block:: cpp 369 370 class Example { 371 private: 372 Example(int); // private constructor 373 public: 374 // Factory function: 375 static Example create(int a) { return Example(a); } 376 }; 377 378 py::class_<Example>(m, "Example") 379 .def(py::init(&Example::create)); 380 381While it is possible to create a straightforward binding of the static 382``create`` method, it may sometimes be preferable to expose it as a constructor 383on the Python side. This can be accomplished by calling ``.def(py::init(...))`` 384with the function reference returning the new instance passed as an argument. 385It is also possible to use this approach to bind a function returning a new 386instance by raw pointer or by the holder (e.g. ``std::unique_ptr``). 387 388The following example shows the different approaches: 389 390.. code-block:: cpp 391 392 class Example { 393 private: 394 Example(int); // private constructor 395 public: 396 // Factory function - returned by value: 397 static Example create(int a) { return Example(a); } 398 399 // These constructors are publicly callable: 400 Example(double); 401 Example(int, int); 402 Example(std::string); 403 }; 404 405 py::class_<Example>(m, "Example") 406 // Bind the factory function as a constructor: 407 .def(py::init(&Example::create)) 408 // Bind a lambda function returning a pointer wrapped in a holder: 409 .def(py::init([](std::string arg) { 410 return std::unique_ptr<Example>(new Example(arg)); 411 })) 412 // Return a raw pointer: 413 .def(py::init([](int a, int b) { return new Example(a, b); })) 414 // You can mix the above with regular C++ constructor bindings as well: 415 .def(py::init<double>()) 416 ; 417 418When the constructor is invoked from Python, pybind11 will call the factory 419function and store the resulting C++ instance in the Python instance. 420 421When combining factory functions constructors with :ref:`virtual function 422trampolines <overriding_virtuals>` there are two approaches. The first is to 423add a constructor to the alias class that takes a base value by 424rvalue-reference. If such a constructor is available, it will be used to 425construct an alias instance from the value returned by the factory function. 426The second option is to provide two factory functions to ``py::init()``: the 427first will be invoked when no alias class is required (i.e. when the class is 428being used but not inherited from in Python), and the second will be invoked 429when an alias is required. 430 431You can also specify a single factory function that always returns an alias 432instance: this will result in behaviour similar to ``py::init_alias<...>()``, 433as described in the :ref:`extended trampoline class documentation 434<extended_aliases>`. 435 436The following example shows the different factory approaches for a class with 437an alias: 438 439.. code-block:: cpp 440 441 #include <pybind11/factory.h> 442 class Example { 443 public: 444 // ... 445 virtual ~Example() = default; 446 }; 447 class PyExample : public Example { 448 public: 449 using Example::Example; 450 PyExample(Example &&base) : Example(std::move(base)) {} 451 }; 452 py::class_<Example, PyExample>(m, "Example") 453 // Returns an Example pointer. If a PyExample is needed, the Example 454 // instance will be moved via the extra constructor in PyExample, above. 455 .def(py::init([]() { return new Example(); })) 456 // Two callbacks: 457 .def(py::init([]() { return new Example(); } /* no alias needed */, 458 []() { return new PyExample(); } /* alias needed */)) 459 // *Always* returns an alias instance (like py::init_alias<>()) 460 .def(py::init([]() { return new PyExample(); })) 461 ; 462 463Brace initialization 464-------------------- 465 466``pybind11::init<>`` internally uses C++11 brace initialization to call the 467constructor of the target class. This means that it can be used to bind 468*implicit* constructors as well: 469 470.. code-block:: cpp 471 472 struct Aggregate { 473 int a; 474 std::string b; 475 }; 476 477 py::class_<Aggregate>(m, "Aggregate") 478 .def(py::init<int, const std::string &>()); 479 480.. note:: 481 482 Note that brace initialization preferentially invokes constructor overloads 483 taking a ``std::initializer_list``. In the rare event that this causes an 484 issue, you can work around it by using ``py::init(...)`` with a lambda 485 function that constructs the new object as desired. 486 487.. _classes_with_non_public_destructors: 488 489Non-public destructors 490====================== 491 492If a class has a private or protected destructor (as might e.g. be the case in 493a singleton pattern), a compile error will occur when creating bindings via 494pybind11. The underlying issue is that the ``std::unique_ptr`` holder type that 495is responsible for managing the lifetime of instances will reference the 496destructor even if no deallocations ever take place. In order to expose classes 497with private or protected destructors, it is possible to override the holder 498type via a holder type argument to ``class_``. Pybind11 provides a helper class 499``py::nodelete`` that disables any destructor invocations. In this case, it is 500crucial that instances are deallocated on the C++ side to avoid memory leaks. 501 502.. code-block:: cpp 503 504 /* ... definition ... */ 505 506 class MyClass { 507 private: 508 ~MyClass() { } 509 }; 510 511 /* ... binding code ... */ 512 513 py::class_<MyClass, std::unique_ptr<MyClass, py::nodelete>>(m, "MyClass") 514 .def(py::init<>()) 515 516.. _implicit_conversions: 517 518Implicit conversions 519==================== 520 521Suppose that instances of two types ``A`` and ``B`` are used in a project, and 522that an ``A`` can easily be converted into an instance of type ``B`` (examples of this 523could be a fixed and an arbitrary precision number type). 524 525.. code-block:: cpp 526 527 py::class_<A>(m, "A") 528 /// ... members ... 529 530 py::class_<B>(m, "B") 531 .def(py::init<A>()) 532 /// ... members ... 533 534 m.def("func", 535 [](const B &) { /* .... */ } 536 ); 537 538To invoke the function ``func`` using a variable ``a`` containing an ``A`` 539instance, we'd have to write ``func(B(a))`` in Python. On the other hand, C++ 540will automatically apply an implicit type conversion, which makes it possible 541to directly write ``func(a)``. 542 543In this situation (i.e. where ``B`` has a constructor that converts from 544``A``), the following statement enables similar implicit conversions on the 545Python side: 546 547.. code-block:: cpp 548 549 py::implicitly_convertible<A, B>(); 550 551.. note:: 552 553 Implicit conversions from ``A`` to ``B`` only work when ``B`` is a custom 554 data type that is exposed to Python via pybind11. 555 556 To prevent runaway recursion, implicit conversions are non-reentrant: an 557 implicit conversion invoked as part of another implicit conversion of the 558 same type (i.e. from ``A`` to ``B``) will fail. 559 560.. _static_properties: 561 562Static properties 563================= 564 565The section on :ref:`properties` discussed the creation of instance properties 566that are implemented in terms of C++ getters and setters. 567 568Static properties can also be created in a similar way to expose getters and 569setters of static class attributes. Note that the implicit ``self`` argument 570also exists in this case and is used to pass the Python ``type`` subclass 571instance. This parameter will often not be needed by the C++ side, and the 572following example illustrates how to instantiate a lambda getter function 573that ignores it: 574 575.. code-block:: cpp 576 577 py::class_<Foo>(m, "Foo") 578 .def_property_readonly_static("foo", [](py::object /* self */) { return Foo(); }); 579 580Operator overloading 581==================== 582 583Suppose that we're given the following ``Vector2`` class with a vector addition 584and scalar multiplication operation, all implemented using overloaded operators 585in C++. 586 587.. code-block:: cpp 588 589 class Vector2 { 590 public: 591 Vector2(float x, float y) : x(x), y(y) { } 592 593 Vector2 operator+(const Vector2 &v) const { return Vector2(x + v.x, y + v.y); } 594 Vector2 operator*(float value) const { return Vector2(x * value, y * value); } 595 Vector2& operator+=(const Vector2 &v) { x += v.x; y += v.y; return *this; } 596 Vector2& operator*=(float v) { x *= v; y *= v; return *this; } 597 598 friend Vector2 operator*(float f, const Vector2 &v) { 599 return Vector2(f * v.x, f * v.y); 600 } 601 602 std::string toString() const { 603 return "[" + std::to_string(x) + ", " + std::to_string(y) + "]"; 604 } 605 private: 606 float x, y; 607 }; 608 609The following snippet shows how the above operators can be conveniently exposed 610to Python. 611 612.. code-block:: cpp 613 614 #include <pybind11/operators.h> 615 616 PYBIND11_MODULE(example, m) { 617 py::class_<Vector2>(m, "Vector2") 618 .def(py::init<float, float>()) 619 .def(py::self + py::self) 620 .def(py::self += py::self) 621 .def(py::self *= float()) 622 .def(float() * py::self) 623 .def(py::self * float()) 624 .def("__repr__", &Vector2::toString); 625 } 626 627Note that a line like 628 629.. code-block:: cpp 630 631 .def(py::self * float()) 632 633is really just short hand notation for 634 635.. code-block:: cpp 636 637 .def("__mul__", [](const Vector2 &a, float b) { 638 return a * b; 639 }, py::is_operator()) 640 641This can be useful for exposing additional operators that don't exist on the 642C++ side, or to perform other types of customization. The ``py::is_operator`` 643flag marker is needed to inform pybind11 that this is an operator, which 644returns ``NotImplemented`` when invoked with incompatible arguments rather than 645throwing a type error. 646 647.. note:: 648 649 To use the more convenient ``py::self`` notation, the additional 650 header file :file:`pybind11/operators.h` must be included. 651 652.. seealso:: 653 654 The file :file:`tests/test_operator_overloading.cpp` contains a 655 complete example that demonstrates how to work with overloaded operators in 656 more detail. 657 658.. _pickling: 659 660Pickling support 661================ 662 663Python's ``pickle`` module provides a powerful facility to serialize and 664de-serialize a Python object graph into a binary data stream. To pickle and 665unpickle C++ classes using pybind11, a ``py::pickle()`` definition must be 666provided. Suppose the class in question has the following signature: 667 668.. code-block:: cpp 669 670 class Pickleable { 671 public: 672 Pickleable(const std::string &value) : m_value(value) { } 673 const std::string &value() const { return m_value; } 674 675 void setExtra(int extra) { m_extra = extra; } 676 int extra() const { return m_extra; } 677 private: 678 std::string m_value; 679 int m_extra = 0; 680 }; 681 682Pickling support in Python is enabled by defining the ``__setstate__`` and 683``__getstate__`` methods [#f3]_. For pybind11 classes, use ``py::pickle()`` 684to bind these two functions: 685 686.. code-block:: cpp 687 688 py::class_<Pickleable>(m, "Pickleable") 689 .def(py::init<std::string>()) 690 .def("value", &Pickleable::value) 691 .def("extra", &Pickleable::extra) 692 .def("setExtra", &Pickleable::setExtra) 693 .def(py::pickle( 694 [](const Pickleable &p) { // __getstate__ 695 /* Return a tuple that fully encodes the state of the object */ 696 return py::make_tuple(p.value(), p.extra()); 697 }, 698 [](py::tuple t) { // __setstate__ 699 if (t.size() != 2) 700 throw std::runtime_error("Invalid state!"); 701 702 /* Create a new C++ instance */ 703 Pickleable p(t[0].cast<std::string>()); 704 705 /* Assign any additional state */ 706 p.setExtra(t[1].cast<int>()); 707 708 return p; 709 } 710 )); 711 712The ``__setstate__`` part of the ``py::picke()`` definition follows the same 713rules as the single-argument version of ``py::init()``. The return type can be 714a value, pointer or holder type. See :ref:`custom_constructors` for details. 715 716An instance can now be pickled as follows: 717 718.. code-block:: python 719 720 try: 721 import cPickle as pickle # Use cPickle on Python 2.7 722 except ImportError: 723 import pickle 724 725 p = Pickleable("test_value") 726 p.setExtra(15) 727 data = pickle.dumps(p, 2) 728 729Note that only the cPickle module is supported on Python 2.7. The second 730argument to ``dumps`` is also crucial: it selects the pickle protocol version 7312, since the older version 1 is not supported. Newer versions are also fine—for 732instance, specify ``-1`` to always use the latest available version. Beware: 733failure to follow these instructions will cause important pybind11 memory 734allocation routines to be skipped during unpickling, which will likely lead to 735memory corruption and/or segmentation faults. 736 737.. seealso:: 738 739 The file :file:`tests/test_pickling.cpp` contains a complete example 740 that demonstrates how to pickle and unpickle types using pybind11 in more 741 detail. 742 743.. [#f3] http://docs.python.org/3/library/pickle.html#pickling-class-instances 744 745Multiple Inheritance 746==================== 747 748pybind11 can create bindings for types that derive from multiple base types 749(aka. *multiple inheritance*). To do so, specify all bases in the template 750arguments of the ``class_`` declaration: 751 752.. code-block:: cpp 753 754 py::class_<MyType, BaseType1, BaseType2, BaseType3>(m, "MyType") 755 ... 756 757The base types can be specified in arbitrary order, and they can even be 758interspersed with alias types and holder types (discussed earlier in this 759document)---pybind11 will automatically find out which is which. The only 760requirement is that the first template argument is the type to be declared. 761 762It is also permitted to inherit multiply from exported C++ classes in Python, 763as well as inheriting from multiple Python and/or pybind-exported classes. 764 765There is one caveat regarding the implementation of this feature: 766 767When only one base type is specified for a C++ type that actually has multiple 768bases, pybind11 will assume that it does not participate in multiple 769inheritance, which can lead to undefined behavior. In such cases, add the tag 770``multiple_inheritance`` to the class constructor: 771 772.. code-block:: cpp 773 774 py::class_<MyType, BaseType2>(m, "MyType", py::multiple_inheritance()); 775 776The tag is redundant and does not need to be specified when multiple base types 777are listed. 778 779.. _module_local: 780 781Module-local class bindings 782=========================== 783 784When creating a binding for a class, pybind by default makes that binding 785"global" across modules. What this means is that a type defined in one module 786can be returned from any module resulting in the same Python type. For 787example, this allows the following: 788 789.. code-block:: cpp 790 791 // In the module1.cpp binding code for module1: 792 py::class_<Pet>(m, "Pet") 793 .def(py::init<std::string>()) 794 .def_readonly("name", &Pet::name); 795 796.. code-block:: cpp 797 798 // In the module2.cpp binding code for module2: 799 m.def("create_pet", [](std::string name) { return new Pet(name); }); 800 801.. code-block:: pycon 802 803 >>> from module1 import Pet 804 >>> from module2 import create_pet 805 >>> pet1 = Pet("Kitty") 806 >>> pet2 = create_pet("Doggy") 807 >>> pet2.name() 808 'Doggy' 809 810When writing binding code for a library, this is usually desirable: this 811allows, for example, splitting up a complex library into multiple Python 812modules. 813 814In some cases, however, this can cause conflicts. For example, suppose two 815unrelated modules make use of an external C++ library and each provide custom 816bindings for one of that library's classes. This will result in an error when 817a Python program attempts to import both modules (directly or indirectly) 818because of conflicting definitions on the external type: 819 820.. code-block:: cpp 821 822 // dogs.cpp 823 824 // Binding for external library class: 825 py::class<pets::Pet>(m, "Pet") 826 .def("name", &pets::Pet::name); 827 828 // Binding for local extension class: 829 py::class<Dog, pets::Pet>(m, "Dog") 830 .def(py::init<std::string>()); 831 832.. code-block:: cpp 833 834 // cats.cpp, in a completely separate project from the above dogs.cpp. 835 836 // Binding for external library class: 837 py::class<pets::Pet>(m, "Pet") 838 .def("get_name", &pets::Pet::name); 839 840 // Binding for local extending class: 841 py::class<Cat, pets::Pet>(m, "Cat") 842 .def(py::init<std::string>()); 843 844.. code-block:: pycon 845 846 >>> import cats 847 >>> import dogs 848 Traceback (most recent call last): 849 File "<stdin>", line 1, in <module> 850 ImportError: generic_type: type "Pet" is already registered! 851 852To get around this, you can tell pybind11 to keep the external class binding 853localized to the module by passing the ``py::module_local()`` attribute into 854the ``py::class_`` constructor: 855 856.. code-block:: cpp 857 858 // Pet binding in dogs.cpp: 859 py::class<pets::Pet>(m, "Pet", py::module_local()) 860 .def("name", &pets::Pet::name); 861 862.. code-block:: cpp 863 864 // Pet binding in cats.cpp: 865 py::class<pets::Pet>(m, "Pet", py::module_local()) 866 .def("get_name", &pets::Pet::name); 867 868This makes the Python-side ``dogs.Pet`` and ``cats.Pet`` into distinct classes, 869avoiding the conflict and allowing both modules to be loaded. C++ code in the 870``dogs`` module that casts or returns a ``Pet`` instance will result in a 871``dogs.Pet`` Python instance, while C++ code in the ``cats`` module will result 872in a ``cats.Pet`` Python instance. 873 874This does come with two caveats, however: First, external modules cannot return 875or cast a ``Pet`` instance to Python (unless they also provide their own local 876bindings). Second, from the Python point of view they are two distinct classes. 877 878Note that the locality only applies in the C++ -> Python direction. When 879passing such a ``py::module_local`` type into a C++ function, the module-local 880classes are still considered. This means that if the following function is 881added to any module (including but not limited to the ``cats`` and ``dogs`` 882modules above) it will be callable with either a ``dogs.Pet`` or ``cats.Pet`` 883argument: 884 885.. code-block:: cpp 886 887 m.def("pet_name", [](const pets::Pet &pet) { return pet.name(); }); 888 889For example, suppose the above function is added to each of ``cats.cpp``, 890``dogs.cpp`` and ``frogs.cpp`` (where ``frogs.cpp`` is some other module that 891does *not* bind ``Pets`` at all). 892 893.. code-block:: pycon 894 895 >>> import cats, dogs, frogs # No error because of the added py::module_local() 896 >>> mycat, mydog = cats.Cat("Fluffy"), dogs.Dog("Rover") 897 >>> (cats.pet_name(mycat), dogs.pet_name(mydog)) 898 ('Fluffy', 'Rover') 899 >>> (cats.pet_name(mydog), dogs.pet_name(mycat), frogs.pet_name(mycat)) 900 ('Rover', 'Fluffy', 'Fluffy') 901 902It is possible to use ``py::module_local()`` registrations in one module even 903if another module registers the same type globally: within the module with the 904module-local definition, all C++ instances will be cast to the associated bound 905Python type. In other modules any such values are converted to the global 906Python type created elsewhere. 907 908.. note:: 909 910 STL bindings (as provided via the optional :file:`pybind11/stl_bind.h` 911 header) apply ``py::module_local`` by default when the bound type might 912 conflict with other modules; see :ref:`stl_bind` for details. 913 914.. note:: 915 916 The localization of the bound types is actually tied to the shared object 917 or binary generated by the compiler/linker. For typical modules created 918 with ``PYBIND11_MODULE()``, this distinction is not significant. It is 919 possible, however, when :ref:`embedding` to embed multiple modules in the 920 same binary (see :ref:`embedding_modules`). In such a case, the 921 localization will apply across all embedded modules within the same binary. 922 923.. seealso:: 924 925 The file :file:`tests/test_local_bindings.cpp` contains additional examples 926 that demonstrate how ``py::module_local()`` works. 927 928Binding protected member functions 929================================== 930 931It's normally not possible to expose ``protected`` member functions to Python: 932 933.. code-block:: cpp 934 935 class A { 936 protected: 937 int foo() const { return 42; } 938 }; 939 940 py::class_<A>(m, "A") 941 .def("foo", &A::foo); // error: 'foo' is a protected member of 'A' 942 943On one hand, this is good because non-``public`` members aren't meant to be 944accessed from the outside. But we may want to make use of ``protected`` 945functions in derived Python classes. 946 947The following pattern makes this possible: 948 949.. code-block:: cpp 950 951 class A { 952 protected: 953 int foo() const { return 42; } 954 }; 955 956 class Publicist : public A { // helper type for exposing protected functions 957 public: 958 using A::foo; // inherited with different access modifier 959 }; 960 961 py::class_<A>(m, "A") // bind the primary class 962 .def("foo", &Publicist::foo); // expose protected methods via the publicist 963 964This works because ``&Publicist::foo`` is exactly the same function as 965``&A::foo`` (same signature and address), just with a different access 966modifier. The only purpose of the ``Publicist`` helper class is to make 967the function name ``public``. 968 969If the intent is to expose ``protected`` ``virtual`` functions which can be 970overridden in Python, the publicist pattern can be combined with the previously 971described trampoline: 972 973.. code-block:: cpp 974 975 class A { 976 public: 977 virtual ~A() = default; 978 979 protected: 980 virtual int foo() const { return 42; } 981 }; 982 983 class Trampoline : public A { 984 public: 985 int foo() const override { PYBIND11_OVERLOAD(int, A, foo, ); } 986 }; 987 988 class Publicist : public A { 989 public: 990 using A::foo; 991 }; 992 993 py::class_<A, Trampoline>(m, "A") // <-- `Trampoline` here 994 .def("foo", &Publicist::foo); // <-- `Publicist` here, not `Trampoline`! 995 996.. note:: 997 998 MSVC 2015 has a compiler bug (fixed in version 2017) which 999 requires a more explicit function binding in the form of 1000 ``.def("foo", static_cast<int (A::*)() const>(&Publicist::foo));`` 1001 where ``int (A::*)() const`` is the type of ``A::foo``. 1002