Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 1 | Classes |
| 2 | ####### |
| 3 | |
| 4 | This section presents advanced binding code for classes and it is assumed |
| 5 | that you are already familiar with the basics from :doc:`/classes`. |
| 6 | |
| 7 | .. _overriding_virtuals: |
| 8 | |
| 9 | Overriding virtual functions in Python |
| 10 | ====================================== |
| 11 | |
| 12 | Suppose that a C++ class or interface has a virtual function that we'd like to |
| 13 | to override from within Python (we'll focus on the class ``Animal``; ``Dog`` is |
| 14 | given as a specific example of how one would do this with traditional C++ |
| 15 | code). |
| 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 | |
| 35 | Let's also suppose that we are given a plain function which calls the |
| 36 | function ``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 | |
| 44 | Normally, the binding code for these classes would look as follows: |
| 45 | |
| 46 | .. code-block:: cpp |
| 47 | |
Dean Moldovan | 443ab59 | 2017-04-24 01:51:44 +0200 | [diff] [blame] | 48 | PYBIND11_MODULE(example, m) { |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 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); |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 57 | } |
| 58 | |
| 59 | However, these bindings are impossible to extend: ``Animal`` is not |
| 60 | constructible, and we clearly require some kind of "trampoline" that |
| 61 | redirects virtual calls back to Python. |
| 62 | |
| 63 | Defining a new type of ``Animal`` from within Python is possible but requires a |
| 64 | helper 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 */ |
jbarlow83 | 7830e85 | 2017-01-13 02:17:29 -0800 | [diff] [blame] | 78 | go, /* Name of function in C++ (must match Python name) */ |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 79 | n_times /* Argument(s) */ |
| 80 | ); |
| 81 | } |
| 82 | }; |
| 83 | |
| 84 | The macro :func:`PYBIND11_OVERLOAD_PURE` should be used for pure virtual |
| 85 | functions, and :func:`PYBIND11_OVERLOAD` should be used for functions which have |
| 86 | a default implementation. There are also two alternate macros |
| 87 | :func:`PYBIND11_OVERLOAD_PURE_NAME` and :func:`PYBIND11_OVERLOAD_NAME` which |
| 88 | take a string-valued name argument between the *Parent class* and *Name of the |
jbarlow83 | 7830e85 | 2017-01-13 02:17:29 -0800 | [diff] [blame] | 89 | function* slots, which defines the name of function in Python. This is required |
| 90 | when the C++ and Python versions of the |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 91 | function have different names, e.g. ``operator()`` vs ``__call__``. |
| 92 | |
| 93 | The binding code also needs a few minor adaptations (highlighted): |
| 94 | |
| 95 | .. code-block:: cpp |
Dean Moldovan | 443ab59 | 2017-04-24 01:51:44 +0200 | [diff] [blame] | 96 | :emphasize-lines: 2,4,5 |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 97 | |
Dean Moldovan | 443ab59 | 2017-04-24 01:51:44 +0200 | [diff] [blame] | 98 | PYBIND11_MODULE(example, m) { |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 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); |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 108 | } |
| 109 | |
| 110 | Importantly, pybind11 is made aware of the trampoline helper class by |
jbarlow83 | 7830e85 | 2017-01-13 02:17:29 -0800 | [diff] [blame] | 111 | specifying it as an extra template argument to :class:`class_`. (This can also |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 112 | be combined with other template arguments such as a custom holder type; the |
| 113 | order of template types does not matter). Following this, we are able to |
| 114 | define a constructor as usual. |
| 115 | |
jbarlow83 | 7830e85 | 2017-01-13 02:17:29 -0800 | [diff] [blame] | 116 | Bindings 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 | |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 125 | Note, however, that the above is sufficient for allowing python classes to |
| 126 | extend ``Animal``, but not ``Dog``: see ref:`virtual_and_inheritance` for the |
| 127 | necessary steps required to providing proper overload support for inherited |
| 128 | classes. |
| 129 | |
| 130 | The Python session below shows how to override ``Animal::go`` and invoke it via |
| 131 | a 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 | |
| 147 | Please take a look at the :ref:`macro_notes` before using this feature. |
| 148 | |
| 149 | .. note:: |
| 150 | |
| 151 | When the overridden type returns a reference or pointer to a type that |
| 152 | pybind11 converts from Python (for example, numeric values, std::string, |
| 153 | and other built-in value-converting types), there are some limitations to |
| 154 | be aware of: |
| 155 | |
| 156 | - because in these cases there is no C++ variable to reference (the value |
| 157 | is stored in the referenced Python variable), pybind11 provides one in |
| 158 | the PYBIND11_OVERLOAD macros (when needed) with static storage duration. |
| 159 | Note that this means that invoking the overloaded method on *any* |
| 160 | instance will change the referenced value stored in *all* instances of |
| 161 | that type. |
| 162 | |
| 163 | - Attempts to modify a non-const reference will not have the desired |
| 164 | effect: it will change only the static cache variable, but this change |
| 165 | will not propagate to underlying Python instance, and the change will be |
| 166 | replaced the next time the overload is invoked. |
| 167 | |
| 168 | .. seealso:: |
| 169 | |
| 170 | The file :file:`tests/test_virtual_functions.cpp` contains a complete |
| 171 | example that demonstrates how to override virtual functions using pybind11 |
| 172 | in more detail. |
| 173 | |
| 174 | .. _virtual_and_inheritance: |
| 175 | |
| 176 | Combining virtual functions and inheritance |
| 177 | =========================================== |
| 178 | |
| 179 | When combining virtual methods with inheritance, you need to be sure to provide |
| 180 | an override for each method for which you want to allow overrides from derived |
| 181 | python classes. For example, suppose we extend the above ``Animal``/``Dog`` |
| 182 | example as follows: |
| 183 | |
| 184 | .. code-block:: cpp |
| 185 | |
| 186 | class Animal { |
| 187 | public: |
| 188 | virtual std::string go(int n_times) = 0; |
| 189 | virtual std::string name() { return "unknown"; } |
| 190 | }; |
myd7349 | 9b815ad | 2017-01-13 18:15:52 +0800 | [diff] [blame] | 191 | class Dog : public Animal { |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 192 | public: |
| 193 | std::string go(int n_times) override { |
| 194 | std::string result; |
| 195 | for (int i=0; i<n_times; ++i) |
| 196 | result += bark() + " "; |
| 197 | return result; |
| 198 | } |
| 199 | virtual std::string bark() { return "woof!"; } |
| 200 | }; |
| 201 | |
| 202 | then the trampoline class for ``Animal`` must, as described in the previous |
| 203 | section, override ``go()`` and ``name()``, but in order to allow python code to |
| 204 | inherit properly from ``Dog``, we also need a trampoline class for ``Dog`` that |
| 205 | overrides both the added ``bark()`` method *and* the ``go()`` and ``name()`` |
| 206 | methods inherited from ``Animal`` (even though ``Dog`` doesn't directly |
| 207 | override the ``name()`` method): |
| 208 | |
| 209 | .. code-block:: cpp |
| 210 | |
| 211 | class PyAnimal : public Animal { |
| 212 | public: |
| 213 | using Animal::Animal; // Inherit constructors |
| 214 | std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Animal, go, n_times); } |
| 215 | std::string name() override { PYBIND11_OVERLOAD(std::string, Animal, name, ); } |
| 216 | }; |
| 217 | class PyDog : public Dog { |
| 218 | public: |
| 219 | using Dog::Dog; // Inherit constructors |
| 220 | std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Dog, go, n_times); } |
| 221 | std::string name() override { PYBIND11_OVERLOAD(std::string, Dog, name, ); } |
| 222 | std::string bark() override { PYBIND11_OVERLOAD(std::string, Dog, bark, ); } |
| 223 | }; |
| 224 | |
Wenzel Jakob | ab26259 | 2017-03-22 21:39:19 +0100 | [diff] [blame] | 225 | .. note:: |
| 226 | |
| 227 | Note the trailing commas in the ``PYBIND11_OVERLOAD`` calls to ``name()`` |
| 228 | and ``bark()``. These are needed to portably implement a trampoline for a |
| 229 | function that does not take any arguments. For functions that take |
| 230 | a nonzero number of arguments, the trailing comma must be omitted. |
| 231 | |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 232 | A registered class derived from a pybind11-registered class with virtual |
| 233 | methods requires a similar trampoline class, *even if* it doesn't explicitly |
| 234 | declare or override any virtual methods itself: |
| 235 | |
| 236 | .. code-block:: cpp |
| 237 | |
| 238 | class Husky : public Dog {}; |
| 239 | class PyHusky : public Husky { |
myd7349 | 9b815ad | 2017-01-13 18:15:52 +0800 | [diff] [blame] | 240 | public: |
| 241 | using Husky::Husky; // Inherit constructors |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 242 | std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Husky, go, n_times); } |
| 243 | std::string name() override { PYBIND11_OVERLOAD(std::string, Husky, name, ); } |
| 244 | std::string bark() override { PYBIND11_OVERLOAD(std::string, Husky, bark, ); } |
| 245 | }; |
| 246 | |
| 247 | There is, however, a technique that can be used to avoid this duplication |
| 248 | (which can be especially helpful for a base class with several virtual |
| 249 | methods). The technique involves using template trampoline classes, as |
| 250 | follows: |
| 251 | |
| 252 | .. code-block:: cpp |
| 253 | |
| 254 | template <class AnimalBase = Animal> class PyAnimal : public AnimalBase { |
myd7349 | 9b815ad | 2017-01-13 18:15:52 +0800 | [diff] [blame] | 255 | public: |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 256 | using AnimalBase::AnimalBase; // Inherit constructors |
| 257 | std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, AnimalBase, go, n_times); } |
| 258 | std::string name() override { PYBIND11_OVERLOAD(std::string, AnimalBase, name, ); } |
| 259 | }; |
| 260 | template <class DogBase = Dog> class PyDog : public PyAnimal<DogBase> { |
myd7349 | 9b815ad | 2017-01-13 18:15:52 +0800 | [diff] [blame] | 261 | public: |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 262 | using PyAnimal<DogBase>::PyAnimal; // Inherit constructors |
| 263 | // Override PyAnimal's pure virtual go() with a non-pure one: |
| 264 | std::string go(int n_times) override { PYBIND11_OVERLOAD(std::string, DogBase, go, n_times); } |
| 265 | std::string bark() override { PYBIND11_OVERLOAD(std::string, DogBase, bark, ); } |
| 266 | }; |
| 267 | |
| 268 | This technique has the advantage of requiring just one trampoline method to be |
| 269 | declared per virtual method and pure virtual method override. It does, |
| 270 | however, require the compiler to generate at least as many methods (and |
| 271 | possibly more, if both pure virtual and overridden pure virtual methods are |
| 272 | exposed, as above). |
| 273 | |
| 274 | The classes are then registered with pybind11 using: |
| 275 | |
| 276 | .. code-block:: cpp |
| 277 | |
| 278 | py::class_<Animal, PyAnimal<>> animal(m, "Animal"); |
| 279 | py::class_<Dog, PyDog<>> dog(m, "Dog"); |
| 280 | py::class_<Husky, PyDog<Husky>> husky(m, "Husky"); |
| 281 | // ... add animal, dog, husky definitions |
| 282 | |
| 283 | Note that ``Husky`` did not require a dedicated trampoline template class at |
| 284 | all, since it neither declares any new virtual methods nor provides any pure |
| 285 | virtual method implementations. |
| 286 | |
| 287 | With either the repeated-virtuals or templated trampoline methods in place, you |
| 288 | can now create a python class that inherits from ``Dog``: |
| 289 | |
| 290 | .. code-block:: python |
| 291 | |
| 292 | class ShihTzu(Dog): |
| 293 | def bark(self): |
| 294 | return "yip!" |
| 295 | |
| 296 | .. seealso:: |
| 297 | |
| 298 | See the file :file:`tests/test_virtual_functions.cpp` for complete examples |
| 299 | using both the duplication and templated trampoline approaches. |
| 300 | |
| 301 | Extended trampoline class functionality |
| 302 | ======================================= |
| 303 | |
| 304 | The trampoline classes described in the previous sections are, by default, only |
| 305 | initialized when needed. More specifically, they are initialized when a python |
| 306 | class actually inherits from a registered type (instead of merely creating an |
| 307 | instance of the registered type), or when a registered constructor is only |
| 308 | valid for the trampoline class but not the registered class. This is primarily |
| 309 | for performance reasons: when the trampoline class is not needed for anything |
| 310 | except virtual method dispatching, not initializing the trampoline class |
| 311 | improves performance by avoiding needing to do a run-time check to see if the |
| 312 | inheriting python instance has an overloaded method. |
| 313 | |
| 314 | Sometimes, however, it is useful to always initialize a trampoline class as an |
| 315 | intermediate class that does more than just handle virtual method dispatching. |
| 316 | For example, such a class might perform extra class initialization, extra |
| 317 | destruction operations, and might define new members and methods to enable a |
| 318 | more python-like interface to a class. |
| 319 | |
| 320 | In order to tell pybind11 that it should *always* initialize the trampoline |
| 321 | class when creating new instances of a type, the class constructors should be |
| 322 | declared using ``py::init_alias<Args, ...>()`` instead of the usual |
| 323 | ``py::init<Args, ...>()``. This forces construction via the trampoline class, |
| 324 | ensuring member initialization and (eventual) destruction. |
| 325 | |
| 326 | .. seealso:: |
| 327 | |
Dean Moldovan | 0bc272b | 2017-06-22 23:42:11 +0200 | [diff] [blame] | 328 | See the file :file:`tests/test_virtual_functions.cpp` for complete examples |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 329 | showing both normal and forced trampoline instantiation. |
| 330 | |
| 331 | .. _custom_constructors: |
| 332 | |
| 333 | Custom constructors |
| 334 | =================== |
| 335 | |
| 336 | The syntax for binding constructors was previously introduced, but it only |
| 337 | works when a constructor with the given parameters actually exists on the C++ |
| 338 | side. To extend this to more general cases, let's take a look at what actually |
| 339 | happens under the hood: the following statement |
| 340 | |
| 341 | .. code-block:: cpp |
| 342 | |
| 343 | py::class_<Example>(m, "Example") |
| 344 | .def(py::init<int>()); |
| 345 | |
| 346 | is short hand notation for |
| 347 | |
| 348 | .. code-block:: cpp |
| 349 | |
| 350 | py::class_<Example>(m, "Example") |
| 351 | .def("__init__", |
| 352 | [](Example &instance, int arg) { |
| 353 | new (&instance) Example(arg); |
| 354 | } |
| 355 | ); |
| 356 | |
| 357 | In other words, :func:`init` creates an anonymous function that invokes an |
| 358 | in-place constructor. Memory allocation etc. is already take care of beforehand |
| 359 | within pybind11. |
| 360 | |
| 361 | .. _classes_with_non_public_destructors: |
| 362 | |
| 363 | Non-public destructors |
| 364 | ====================== |
| 365 | |
| 366 | If a class has a private or protected destructor (as might e.g. be the case in |
| 367 | a singleton pattern), a compile error will occur when creating bindings via |
| 368 | pybind11. The underlying issue is that the ``std::unique_ptr`` holder type that |
| 369 | is responsible for managing the lifetime of instances will reference the |
| 370 | destructor even if no deallocations ever take place. In order to expose classes |
| 371 | with private or protected destructors, it is possible to override the holder |
| 372 | type via a holder type argument to ``class_``. Pybind11 provides a helper class |
| 373 | ``py::nodelete`` that disables any destructor invocations. In this case, it is |
| 374 | crucial that instances are deallocated on the C++ side to avoid memory leaks. |
| 375 | |
| 376 | .. code-block:: cpp |
| 377 | |
| 378 | /* ... definition ... */ |
| 379 | |
| 380 | class MyClass { |
| 381 | private: |
| 382 | ~MyClass() { } |
| 383 | }; |
| 384 | |
| 385 | /* ... binding code ... */ |
| 386 | |
| 387 | py::class_<MyClass, std::unique_ptr<MyClass, py::nodelete>>(m, "MyClass") |
myd7349 | 9b815ad | 2017-01-13 18:15:52 +0800 | [diff] [blame] | 388 | .def(py::init<>()) |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 389 | |
Jason Rhinelander | abc29ca | 2017-01-23 03:50:00 -0500 | [diff] [blame] | 390 | .. _implicit_conversions: |
| 391 | |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 392 | Implicit conversions |
| 393 | ==================== |
| 394 | |
| 395 | Suppose that instances of two types ``A`` and ``B`` are used in a project, and |
| 396 | that an ``A`` can easily be converted into an instance of type ``B`` (examples of this |
| 397 | could be a fixed and an arbitrary precision number type). |
| 398 | |
| 399 | .. code-block:: cpp |
| 400 | |
| 401 | py::class_<A>(m, "A") |
| 402 | /// ... members ... |
| 403 | |
| 404 | py::class_<B>(m, "B") |
| 405 | .def(py::init<A>()) |
| 406 | /// ... members ... |
| 407 | |
| 408 | m.def("func", |
| 409 | [](const B &) { /* .... */ } |
| 410 | ); |
| 411 | |
| 412 | To invoke the function ``func`` using a variable ``a`` containing an ``A`` |
| 413 | instance, we'd have to write ``func(B(a))`` in Python. On the other hand, C++ |
| 414 | will automatically apply an implicit type conversion, which makes it possible |
| 415 | to directly write ``func(a)``. |
| 416 | |
| 417 | In this situation (i.e. where ``B`` has a constructor that converts from |
| 418 | ``A``), the following statement enables similar implicit conversions on the |
| 419 | Python side: |
| 420 | |
| 421 | .. code-block:: cpp |
| 422 | |
| 423 | py::implicitly_convertible<A, B>(); |
| 424 | |
| 425 | .. note:: |
| 426 | |
| 427 | Implicit conversions from ``A`` to ``B`` only work when ``B`` is a custom |
| 428 | data type that is exposed to Python via pybind11. |
| 429 | |
| 430 | .. _static_properties: |
| 431 | |
| 432 | Static properties |
| 433 | ================= |
| 434 | |
| 435 | The section on :ref:`properties` discussed the creation of instance properties |
| 436 | that are implemented in terms of C++ getters and setters. |
| 437 | |
| 438 | Static properties can also be created in a similar way to expose getters and |
Dean Moldovan | dd01665 | 2017-02-16 23:02:56 +0100 | [diff] [blame] | 439 | setters of static class attributes. Note that the implicit ``self`` argument |
| 440 | also exists in this case and is used to pass the Python ``type`` subclass |
| 441 | instance. This parameter will often not be needed by the C++ side, and the |
| 442 | following example illustrates how to instantiate a lambda getter function |
| 443 | that ignores it: |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 444 | |
| 445 | .. code-block:: cpp |
| 446 | |
Dean Moldovan | dd01665 | 2017-02-16 23:02:56 +0100 | [diff] [blame] | 447 | py::class_<Foo>(m, "Foo") |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 448 | .def_property_readonly_static("foo", [](py::object /* self */) { return Foo(); }); |
| 449 | |
| 450 | Operator overloading |
| 451 | ==================== |
| 452 | |
| 453 | Suppose that we're given the following ``Vector2`` class with a vector addition |
| 454 | and scalar multiplication operation, all implemented using overloaded operators |
| 455 | in C++. |
| 456 | |
| 457 | .. code-block:: cpp |
| 458 | |
| 459 | class Vector2 { |
| 460 | public: |
| 461 | Vector2(float x, float y) : x(x), y(y) { } |
| 462 | |
| 463 | Vector2 operator+(const Vector2 &v) const { return Vector2(x + v.x, y + v.y); } |
| 464 | Vector2 operator*(float value) const { return Vector2(x * value, y * value); } |
| 465 | Vector2& operator+=(const Vector2 &v) { x += v.x; y += v.y; return *this; } |
| 466 | Vector2& operator*=(float v) { x *= v; y *= v; return *this; } |
| 467 | |
| 468 | friend Vector2 operator*(float f, const Vector2 &v) { |
| 469 | return Vector2(f * v.x, f * v.y); |
| 470 | } |
| 471 | |
| 472 | std::string toString() const { |
| 473 | return "[" + std::to_string(x) + ", " + std::to_string(y) + "]"; |
| 474 | } |
| 475 | private: |
| 476 | float x, y; |
| 477 | }; |
| 478 | |
| 479 | The following snippet shows how the above operators can be conveniently exposed |
| 480 | to Python. |
| 481 | |
| 482 | .. code-block:: cpp |
| 483 | |
| 484 | #include <pybind11/operators.h> |
| 485 | |
Dean Moldovan | 443ab59 | 2017-04-24 01:51:44 +0200 | [diff] [blame] | 486 | PYBIND11_MODULE(example, m) { |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 487 | py::class_<Vector2>(m, "Vector2") |
| 488 | .def(py::init<float, float>()) |
| 489 | .def(py::self + py::self) |
| 490 | .def(py::self += py::self) |
| 491 | .def(py::self *= float()) |
| 492 | .def(float() * py::self) |
myd7349 | 9b815ad | 2017-01-13 18:15:52 +0800 | [diff] [blame] | 493 | .def(py::self * float()) |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 494 | .def("__repr__", &Vector2::toString); |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 495 | } |
| 496 | |
| 497 | Note that a line like |
| 498 | |
| 499 | .. code-block:: cpp |
| 500 | |
| 501 | .def(py::self * float()) |
| 502 | |
| 503 | is really just short hand notation for |
| 504 | |
| 505 | .. code-block:: cpp |
| 506 | |
| 507 | .def("__mul__", [](const Vector2 &a, float b) { |
| 508 | return a * b; |
| 509 | }, py::is_operator()) |
| 510 | |
| 511 | This can be useful for exposing additional operators that don't exist on the |
| 512 | C++ side, or to perform other types of customization. The ``py::is_operator`` |
| 513 | flag marker is needed to inform pybind11 that this is an operator, which |
| 514 | returns ``NotImplemented`` when invoked with incompatible arguments rather than |
| 515 | throwing a type error. |
| 516 | |
| 517 | .. note:: |
| 518 | |
| 519 | To use the more convenient ``py::self`` notation, the additional |
| 520 | header file :file:`pybind11/operators.h` must be included. |
| 521 | |
| 522 | .. seealso:: |
| 523 | |
| 524 | The file :file:`tests/test_operator_overloading.cpp` contains a |
| 525 | complete example that demonstrates how to work with overloaded operators in |
| 526 | more detail. |
| 527 | |
| 528 | Pickling support |
| 529 | ================ |
| 530 | |
| 531 | Python's ``pickle`` module provides a powerful facility to serialize and |
| 532 | de-serialize a Python object graph into a binary data stream. To pickle and |
| 533 | unpickle C++ classes using pybind11, two additional functions must be provided. |
| 534 | Suppose the class in question has the following signature: |
| 535 | |
| 536 | .. code-block:: cpp |
| 537 | |
| 538 | class Pickleable { |
| 539 | public: |
| 540 | Pickleable(const std::string &value) : m_value(value) { } |
| 541 | const std::string &value() const { return m_value; } |
| 542 | |
| 543 | void setExtra(int extra) { m_extra = extra; } |
| 544 | int extra() const { return m_extra; } |
| 545 | private: |
| 546 | std::string m_value; |
| 547 | int m_extra = 0; |
| 548 | }; |
| 549 | |
| 550 | The binding code including the requisite ``__setstate__`` and ``__getstate__`` methods [#f3]_ |
| 551 | looks as follows: |
| 552 | |
| 553 | .. code-block:: cpp |
| 554 | |
| 555 | py::class_<Pickleable>(m, "Pickleable") |
| 556 | .def(py::init<std::string>()) |
| 557 | .def("value", &Pickleable::value) |
| 558 | .def("extra", &Pickleable::extra) |
| 559 | .def("setExtra", &Pickleable::setExtra) |
| 560 | .def("__getstate__", [](const Pickleable &p) { |
| 561 | /* Return a tuple that fully encodes the state of the object */ |
| 562 | return py::make_tuple(p.value(), p.extra()); |
| 563 | }) |
| 564 | .def("__setstate__", [](Pickleable &p, py::tuple t) { |
| 565 | if (t.size() != 2) |
| 566 | throw std::runtime_error("Invalid state!"); |
| 567 | |
| 568 | /* Invoke the in-place constructor. Note that this is needed even |
| 569 | when the object just has a trivial default constructor */ |
| 570 | new (&p) Pickleable(t[0].cast<std::string>()); |
| 571 | |
| 572 | /* Assign any additional state */ |
| 573 | p.setExtra(t[1].cast<int>()); |
| 574 | }); |
| 575 | |
| 576 | An instance can now be pickled as follows: |
| 577 | |
| 578 | .. code-block:: python |
| 579 | |
| 580 | try: |
| 581 | import cPickle as pickle # Use cPickle on Python 2.7 |
| 582 | except ImportError: |
| 583 | import pickle |
| 584 | |
| 585 | p = Pickleable("test_value") |
| 586 | p.setExtra(15) |
| 587 | data = pickle.dumps(p, 2) |
| 588 | |
| 589 | Note that only the cPickle module is supported on Python 2.7. The second |
| 590 | argument to ``dumps`` is also crucial: it selects the pickle protocol version |
| 591 | 2, since the older version 1 is not supported. Newer versions are also fineāfor |
| 592 | instance, specify ``-1`` to always use the latest available version. Beware: |
| 593 | failure to follow these instructions will cause important pybind11 memory |
| 594 | allocation routines to be skipped during unpickling, which will likely lead to |
| 595 | memory corruption and/or segmentation faults. |
| 596 | |
| 597 | .. seealso:: |
| 598 | |
| 599 | The file :file:`tests/test_pickling.cpp` contains a complete example |
| 600 | that demonstrates how to pickle and unpickle types using pybind11 in more |
| 601 | detail. |
| 602 | |
| 603 | .. [#f3] http://docs.python.org/3/library/pickle.html#pickling-class-instances |
| 604 | |
| 605 | Multiple Inheritance |
| 606 | ==================== |
| 607 | |
| 608 | pybind11 can create bindings for types that derive from multiple base types |
| 609 | (aka. *multiple inheritance*). To do so, specify all bases in the template |
| 610 | arguments of the ``class_`` declaration: |
| 611 | |
| 612 | .. code-block:: cpp |
| 613 | |
| 614 | py::class_<MyType, BaseType1, BaseType2, BaseType3>(m, "MyType") |
| 615 | ... |
| 616 | |
| 617 | The base types can be specified in arbitrary order, and they can even be |
| 618 | interspersed with alias types and holder types (discussed earlier in this |
| 619 | document)---pybind11 will automatically find out which is which. The only |
| 620 | requirement is that the first template argument is the type to be declared. |
| 621 | |
Jason Rhinelander | e45c211 | 2017-02-22 21:36:09 -0500 | [diff] [blame] | 622 | It is also permitted to inherit multiply from exported C++ classes in Python, |
| 623 | as well as inheriting from multiple Python and/or pybind-exported classes. |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 624 | |
Jason Rhinelander | e45c211 | 2017-02-22 21:36:09 -0500 | [diff] [blame] | 625 | There is one caveat regarding the implementation of this feature: |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 626 | |
Jason Rhinelander | e45c211 | 2017-02-22 21:36:09 -0500 | [diff] [blame] | 627 | When only one base type is specified for a C++ type that actually has multiple |
| 628 | bases, pybind11 will assume that it does not participate in multiple |
| 629 | inheritance, which can lead to undefined behavior. In such cases, add the tag |
| 630 | ``multiple_inheritance`` to the class constructor: |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 631 | |
Jason Rhinelander | e45c211 | 2017-02-22 21:36:09 -0500 | [diff] [blame] | 632 | .. code-block:: cpp |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 633 | |
Jason Rhinelander | e45c211 | 2017-02-22 21:36:09 -0500 | [diff] [blame] | 634 | py::class_<MyType, BaseType2>(m, "MyType", py::multiple_inheritance()); |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 635 | |
Jason Rhinelander | e45c211 | 2017-02-22 21:36:09 -0500 | [diff] [blame] | 636 | The tag is redundant and does not need to be specified when multiple base types |
| 637 | are listed. |
Jason Rhinelander | 7437c69 | 2017-07-28 22:03:44 -0400 | [diff] [blame] | 638 | |
| 639 | .. _module_local: |
| 640 | |
| 641 | Module-local class bindings |
| 642 | =========================== |
| 643 | |
| 644 | When creating a binding for a class, pybind by default makes that binding |
| 645 | "global" across modules. What this means is that a type defined in one module |
| 646 | can be passed to functions of other modules that expect the same C++ type. For |
| 647 | example, this allows the following: |
| 648 | |
| 649 | .. code-block:: cpp |
| 650 | |
| 651 | // In the module1.cpp binding code for module1: |
| 652 | py::class_<Pet>(m, "Pet") |
| 653 | .def(py::init<std::string>()); |
| 654 | |
| 655 | .. code-block:: cpp |
| 656 | |
| 657 | // In the module2.cpp binding code for module2: |
| 658 | m.def("pet_name", [](Pet &p) { return p.name(); }); |
| 659 | |
| 660 | .. code-block:: pycon |
| 661 | |
| 662 | >>> from module1 import Pet |
| 663 | >>> from module2 import pet_name |
| 664 | >>> mypet = Pet("Kitty") |
| 665 | >>> pet_name(mypet) |
| 666 | 'Kitty' |
| 667 | |
| 668 | When writing binding code for a library, this is usually desirable: this |
| 669 | allows, for example, splitting up a complex library into multiple Python |
| 670 | modules. |
| 671 | |
| 672 | In some cases, however, this can cause conflicts. For example, suppose two |
| 673 | unrelated modules make use of an external C++ library and each provide custom |
| 674 | bindings for one of that library's classes. This will result in an error when |
| 675 | a Python program attempts to import both modules (directly or indirectly) |
| 676 | because of conflicting definitions on the external type: |
| 677 | |
| 678 | .. code-block:: cpp |
| 679 | |
| 680 | // dogs.cpp |
| 681 | |
| 682 | // Binding for external library class: |
| 683 | py::class<pets::Pet>(m, "Pet") |
| 684 | .def("name", &pets::Pet::name); |
| 685 | |
| 686 | // Binding for local extension class: |
| 687 | py::class<Dog, pets::Pet>(m, "Dog") |
| 688 | .def(py::init<std::string>()); |
| 689 | |
| 690 | .. code-block:: cpp |
| 691 | |
| 692 | // cats.cpp, in a completely separate project from the above dogs.cpp. |
| 693 | |
| 694 | // Binding for external library class: |
| 695 | py::class<pets::Pet>(m, "Pet") |
| 696 | .def("get_name", &pets::Pet::name); |
| 697 | |
| 698 | // Binding for local extending class: |
| 699 | py::class<Cat, pets::Pet>(m, "Cat") |
| 700 | .def(py::init<std::string>()); |
| 701 | |
| 702 | .. code-block:: pycon |
| 703 | |
| 704 | >>> import cats |
| 705 | >>> import dogs |
| 706 | Traceback (most recent call last): |
| 707 | File "<stdin>", line 1, in <module> |
| 708 | ImportError: generic_type: type "Pet" is already registered! |
| 709 | |
| 710 | To get around this, you can tell pybind11 to keep the external class binding |
| 711 | localized to the module by passing the ``py::module_local()`` attribute into |
| 712 | the ``py::class_`` constructor: |
| 713 | |
| 714 | .. code-block:: cpp |
| 715 | |
| 716 | // Pet binding in dogs.cpp: |
| 717 | py::class<pets::Pet>(m, "Pet", py::module_local()) |
| 718 | .def("name", &pets::Pet::name); |
| 719 | |
| 720 | .. code-block:: cpp |
| 721 | |
| 722 | // Pet binding in cats.cpp: |
| 723 | py::class<pets::Pet>(m, "Pet", py::module_local()) |
| 724 | .def("get_name", &pets::Pet::name); |
| 725 | |
| 726 | This makes the Python-side ``dogs.Pet`` and ``cats.Pet`` into distinct classes |
| 727 | that can only be accepted as ``Pet`` arguments within those classes. This |
| 728 | avoids the conflict and allows both modules to be loaded. |
| 729 | |
| 730 | One limitation of this approach is that because ``py::module_local`` types are |
| 731 | distinct on the Python side, it is not possible to pass such a module-local |
| 732 | type as a C++ ``Pet``-taking function outside that module. For example, if the |
| 733 | above ``cats`` and ``dogs`` module are each extended with a function: |
| 734 | |
| 735 | .. code-block:: cpp |
| 736 | |
| 737 | m.def("petname", [](pets::Pet &p) { return p.name(); }); |
| 738 | |
| 739 | you will only be able to call the function with the local module's class: |
| 740 | |
| 741 | .. code-block:: pycon |
| 742 | |
| 743 | >>> import cats, dogs # No error because of the added py::module_local() |
| 744 | >>> mycat, mydog = cats.Cat("Fluffy"), dogs.Dog("Rover") |
| 745 | >>> (cats.petname(mycat), dogs.petname(mydog)) |
| 746 | ('Fluffy', 'Rover') |
| 747 | >>> cats.petname(mydog) |
| 748 | Traceback (most recent call last): |
| 749 | File "<stdin>", line 1, in <module> |
| 750 | TypeError: petname(): incompatible function arguments. The following argument types are supported: |
| 751 | 1. (arg0: cats.Pet) -> str |
| 752 | |
| 753 | Invoked with: <dogs.Dog object at 0x123> |
| 754 | |
Jason Rhinelander | 4b15923 | 2017-08-04 13:05:12 -0400 | [diff] [blame^] | 755 | It is possible to use ``py::module_local()`` registrations in one module even if another module |
| 756 | registers the same type globally: within the module with the module-local definition, all C++ |
| 757 | instances will be cast to the associated bound Python type. Outside the module, any such values |
| 758 | are converted to the global Python type created elsewhere. |
| 759 | |
Jason Rhinelander | 7437c69 | 2017-07-28 22:03:44 -0400 | [diff] [blame] | 760 | .. note:: |
| 761 | |
| 762 | STL bindings (as provided via the optional :file:`pybind11/stl_bind.h` |
| 763 | header) apply ``py::module_local`` by default when the bound type might |
| 764 | conflict with other modules; see :ref:`stl_bind` for details. |
| 765 | |
| 766 | .. note:: |
| 767 | |
| 768 | The localization of the bound types is actually tied to the shared object |
| 769 | or binary generated by the compiler/linker. For typical modules created |
| 770 | with ``PYBIND11_MODULE()``, this distinction is not significant. It is |
| 771 | possible, however, when :ref:`embedding` to embed multiple modules in the |
| 772 | same binary (see :ref:`embedding_modules`). In such a case, the |
| 773 | localization will apply across all embedded modules within the same binary. |
| 774 | |
| 775 | .. seealso:: |
| 776 | |
| 777 | The file :file:`tests/test_local_bindings.cpp` contains additional examples |
| 778 | that demonstrate how ``py::module_local()`` works. |