.. _classes: .. cpp:namespace:: nanobind Classes ======= The material below builds on the section on :ref:`binding custom types ` and reviews advanced scenarios involving object-oriented code. Frequently used --------------- Click on the following :cpp:class:`nb::class_\<..\>::def_* ` members for examples on how to bind various different kinds of methods, fields, etc. .. list-table:: :widths: 40 60 :header-rows: 1 * - Type - method * - Methods & constructors - :cpp:func:`.def() ` * - Fields - :cpp:func:`.def_ro() `, :cpp:func:`.def_rw() ` * - Properties - :cpp:func:`.def_prop_ro() `, :cpp:func:`.def_prop_rw() ` * - Static methods - :cpp:func:`.def_static() ` * - Static fields - :cpp:func:`.def_ro_static() `, :cpp:func:`.def_rw_static() ` * - Static properties - :cpp:func:`.def_prop_ro_static() `, :cpp:func:`.def_prop_rw_static() ` .. _inheritance: Subclasses ---------- Consider the following two data structures with an inheritance relationship: .. code-block:: cpp struct Pet { std::string name; }; struct Dog : Pet { std::string bark() const { return name + ": woof!"; } }; To indicate the inheritance relationship to nanobind, specify the C++ base class as an extra template parameter of :cpp:class:`nb::class_\<..\> `: .. code-block:: cpp :emphasize-lines: 8 #include NB_MODULE(my_ext, m) { nb::class_(m, "Pet") .def(nb::init()) .def_rw("name", &Pet::name); nb::class_(m, "Dog") .def(nb::init()) .def("bark", &Dog::bark); } Alternatively, you can also pass the type object as an ordinary parameter. .. code-block:: cpp :emphasize-lines: 5 auto pet = nb::class_(m, "Pet") .def(nb::init()) .def_rw("name", &Pet::name); nb::class_(m, "Dog", pet /* <- Parent type object */) .def(nb::init()) .def("bark", &Dog::bark); Instances expose fields and methods of both types as expected: .. code-block:: pycon >>> d = my_ext.Dog("Molly") >>> d.name 'Molly' >>> d.bark() 'Molly: woof!' .. _automatic_downcasting: Automatic downcasting --------------------- nanobind obeys signatures when returning regular non-polymorphic C++ objects from functions: building on the :ref:`previous example `, consider the following function that returns a ``Dog`` object as a ``Pet`` base pointer. .. code-block:: cpp m.def("pet_store", []() { return (Pet *) new Dog{"Molly"}; }); nanobind cannot safely determine that this is in fact an instance of the ``Dog`` subclass. Consequently, only fields and methods of the base type remain accessible: .. code-block:: pycon >>> p = my_ext.pet_store() >>> type(p) >>> p.bark() AttributeError: 'Pet' object has no attribute 'bark' In C++, a type is only considered `polymorphic `_ if it (or one of its base classes) has at least one *virtual function*. Let's add a virtual default destructor to make ``Pet`` and its subtypes polymorphic. .. code-block:: cpp struct Pet { virtual ~Pet() = default; std::string name; }; With this change, nanobind is able to inspect the returned C++ instance's `virtual table `_ and infer that it can be represented by a more specialized Python object of type ``my_ext.Dog``. .. code-block:: pycon >>> p = my_ext.pet_store() >>> type(p) >>> p.bark() 'Molly: woof!' .. note:: Automatic downcasting of polymorphic instances is only supported when the subtype has been registered using :cpp:class:`nb::class_\<..\> `. Otherwise, the return type listed in the function signature takes precedence. .. _overloaded_methods: Overloaded methods ------------------ Sometimes there are several overloaded C++ methods with the same name taking different kinds of input arguments: .. code-block:: cpp struct Pet { Pet(const std::string &name, int age) : name(name), age(age) { } void set(int age_) { age = age_; } void set(const std::string &name_) { name = name_; } std::string name; int age; }; Attempting to bind ``Pet::set`` will cause an error since the compiler does not know which method the user intended to select. We can disambiguate by casting them to function pointers. Binding multiple functions to the same Python name automatically creates a chain of function overloads that will be tried in sequence. .. code-block:: cpp nb::class_(m, "Pet") .def(nb::init()) .def("set", nb::overload_cast(&Pet::set), "Set the pet's age") .def("set", nb::overload_cast(&Pet::set), "Set the pet's name"); Here, :cpp:func:`nb::overload_cast ` only requires the parameter types to be specified, and it deduces the return type. .. note:: In cases where a function overloads by ``const``-ness, an additional ``nb::const_`` parameter is needed to select the right overload, e.g., ``nb::overload_cast(&Pet::get, nb::const_)``. To define overloaded constructors, simply declare one after the other using the normal :cpp:class:`.def(nb::init\<...\>()) ` syntax. The overload signatures are also visible in the method's docstring: .. code-block:: pycon >>> help(my_ext.Pet) class Pet(builtins.object) | Methods defined here: | | __init__(...) | __init__(self, arg0: str, arg1: int, /) -> None | | set(...) | set(self, arg: int, /) -> None | set(self, arg: str, /) -> None | | Overloaded function. | | 1. ``set(self, arg: int, /) -> None`` | | Set the pet's age | | 2. ``set(self, arg: str, /) -> None`` | | Set the pet's name The format of the docstring with a leading overload list followed by a repeated list with details is designed to be compatible with the `Sphinx `_ documentation generator. .. _enumerations_and_internal: Enumerations and internal types ------------------------------- Let's now suppose that the example class contains internal types like enumerations, e.g.: .. code-block:: cpp struct Pet { enum Kind { Dog = 0, Cat }; struct Attributes { float age = 0; }; Pet(const std::string &name, Kind type) : name(name), type(type) { } std::string name; Kind type; Attributes attr; }; The binding code for this example looks as follows: .. code-block:: cpp nb::class_ pet(m, "Pet"); pet.def(nb::init()) .def_rw("name", &Pet::name) .def_rw("type", &Pet::type) .def_rw("attr", &Pet::attr); nb::enum_(pet, "Kind") .value("Dog", Pet::Kind::Dog) .value("Cat", Pet::Kind::Cat) .export_values(); nb::class_(pet, "Attributes") .def(nb::init<>()) .def_rw("age", &Pet::Attributes::age); To ensure that the nested types ``Kind`` and ``Attributes`` are created within the scope of ``Pet``, the ``pet`` type object is passed as the ``scope`` argument of the subsequent :cpp:class:`nb::enum_\ ` and :cpp:class:`nb::class_\ ` binding declarations. The :cpp:func:`.export_values() ` function exports the enumeration entries into the parent scope, which should be skipped for newer C++11-style strongly typed enumerations. .. code-block:: pycon >>> from my_ext import Pet >>> p = Pet("Lucy", Pet.Cat) >>> p.attr.age = 3 >>> p.type my_ext.Kind.Cat >>> p.type.__name__ 'Cat' >>> int(p.type) 1 .. note:: When the annotation :cpp:class:`nb::is_arithmetic() ` is passed to :cpp:class:`nb::enum_\ `, the resulting Python type will support arithmetic and bit-level operations (and, or, xor, negation). The operands of these operations may be either enumerators. When the annotation :cpp:class:`nb::is_flag() ` is passed to :cpp:class:`nb::enum_\ `, the resulting Python type will be a class derived from ``enum.Flag``, meaning its enumerators can be combined using bit-wise operators in a type-safe way: the result will have the same enumeration type as the operands, and only enumerators of the same type can be combined. When passing both ``is_arithmetic`` and ``is_flag``, the resulting Python type will be ``enum.IntFlag``, supporting both arithmetic and bit-wise operations. .. code-block:: cpp nb::enum_(pet, "Kind", nb::is_arithmetic()) ... By default, these are omitted. .. _dynamic_attributes: Dynamic attributes ------------------ Native Python classes can pick up new attributes dynamically: .. code-block:: pycon >>> class Pet: ... name = "Molly" ... >>> p = Pet() >>> p.name = "Charly" # overwrite existing >>> p.age = 2 # dynamically add a new attribute By default, classes exported from C++ do not support this and the only writable attributes are the ones explicitly defined using :func:`class_::def_rw` or :func:`class_::def_prop_rw`. .. code-block:: cpp nb::class_(m, "Pet") .def(nb::init<>()) .def_rw("name", &Pet::name); Trying to set any other attribute results in an error: .. code-block:: pycon >>> p = my_ext.Pet() >>> p.name = "Charly" # OK, attribute defined in C++ >>> p.age = 2 # fail AttributeError: 'Pet' object has no attribute 'age' To enable dynamic attributes for C++ classes, the :class:`nb::dynamic_attr ` tag must be added to the :class:`nb::class_ ` constructor: .. code-block:: cpp nb::class_(m, "Pet", nb::dynamic_attr()) .def(nb::init<>()) .def_rw("name", &Pet::name); Now everything works as expected: .. code-block:: pycon >>> p = my_ext.Pet() >>> p.name = "Charly" # OK, overwrite value in C++ >>> p.age = 2 # OK, dynamically add a new attribute Note that there is a small runtime cost for a class with dynamic attributes. Not only because of the addition of an instance dictionary, but also because of more expensive garbage collection tracking which must be activated to resolve possible circular references. Native Python classes incur this same cost by default, so this is not anything to worry about. By default, nanobind classes are more efficient than native Python classes. Enabling dynamic attributes just brings them on par. .. _weak_refs: Weak references --------------- By default, nanobind instances cannot be referenced via Python's ``weakref`` class, and attempting to do so will raise an exception. To support this, add the :class:`nb::is_weak_referenceable ` tag to the :class:`nb::class_ ` constructor. Note that this will increase the size of every instance by ``sizeof(void*)`` due to the need to store a weak reference list. .. code-block:: cpp nb::class_(m, "Pet", nb::is_weak_referenceable()); .. _inheriting_in_python: Extending C++ classes in Python ------------------------------- Bound C++ types can be extended within Python, which is helpful to dynamically extend compiled code with further fields and other functionality. Bind classes with the :cpp:class:`is_final` annotation to forbid subclassing. Consider the following example bindings of a ``Dog`` and ``DogHouse`` class. .. code-block:: cpp #include namespace nb = nanobind; struct Dog { std::string name; std::string bark() const { return name + ": woof!"; } }; struct DogHouse { Dog dog; }; NB_MODULE(my_ext, m) { nb::class_(m, "Dog") .def(nb::init()) .def("bark", &Dog::bark) .def_rw("name", &Dog::name); nb::class_(m, "DogHouse") .def(nb::init()) .def_rw("dog", &DogHouse::dog); } The following Python snippet creates a new ``GuardDog`` type that extends ``Dog`` with an ``.alarm()`` method. .. code-block:: pycon >>> import my_ext >>> class GuardDog(my_ext.Dog): ... def alarm(self, count = 3): ... for i in range(count): ... print(self.bark()) ... >>> gd = GuardDog("Max") >>> gd.alarm() Max: woof! Max: woof! Max: woof! This Python subclass is best thought of as a "rich wrapper" around an existing C++ base object. By default, that wrapper will disappear when nanobind makes a copy or transfers ownership to C++. .. code-block:: pycon >>> d = my_ext.DogHouse() >>> d.dog = gd >>> d.dog.alarm() AttributeError: 'Dog' object has no attribute 'alarm' To preserve it, adopt a shared ownership model using :ref:`shared pointers ` or :ref:`intrusive reference counting `. For example, updating the code as follows fixes the problem: .. code-block:: cpp #include struct DogHouse { std::shared_ptr dog; }; .. code-block:: pycon >>> d = my_ext.DogHouse() >>> d.dog = gd >>> d.dog.alarm() Max: woof! Max: woof! Max: woof! .. _trampolines: Overriding virtual functions in Python -------------------------------------- Building on the previous example on :ref:`inheriting C++ types in Python `, let's investigate how a C++ *virtual function* can be overridden in Python. In the code below, the virtual method ``bark()`` is called by a global ``alarm()`` function (now written in C++). .. code-block:: cpp :emphasize-lines: 6 #include struct Dog { std::string name; Dog(const std::string &name) : name(name) { } virtual std::string bark() const { return name + ": woof!"; } }; void alarm(Dog *dog, size_t count = 3) { for (size_t i = 0; i < count; ++i) std::cout << dog->bark() << std::endl; } Normally, the binding code would look as follows: .. code-block:: cpp #include namespace nb = nanobind; using namespace nb::literals; NB_MODULE(my_ext, m) { nb::class_(m, "Dog") .def(nb::init()) .def("bark", &Dog::bark) .def_rw("name", &Dog::name); m.def("alarm", &alarm, "dog"_a, "count"_a = 3); } However, this don't work as expected. We can subclass and override without problems, but virtual function calls originating from C++ aren't being propagated to Python: .. code-block:: pycon >>> class ShihTzu(my_ext.Dog): ... def bark(self): ... return self.name + ": yip!" ... >>> dog = ShihTzu("Mr. Fluffles") >>> dog.bark() Mr. Fluffles: yip! >>> my_ext.alarm(dog) Mr. Fluffles: woof! # <-- oops, alarm() is calling the base implementation Mr. Fluffles: woof! Mr. Fluffles: woof! To fix this behavior, you must implement a *trampoline class*. A trampoline has the sole purpose of capturing virtual function calls in C++ and forwarding them to Python. .. code-block:: cpp #include struct PyDog : Dog { NB_TRAMPOLINE(Dog, 1); std::string bark() const override { NB_OVERRIDE(bark); } }; This involves an additional include directive and the line :c:macro:`NB_TRAMPOLINE(Dog, 1) ` to mark the class as a trampoline for the ``Dog`` base type. The count (``1``) denotes to the total number of virtual method slots that can be overridden within Python. .. note:: The number of virtual method slots is used to preallocate memory. Trampoline declarations with an insufficient size may eventually trigger a Python ``RuntimeError`` exception with a descriptive label, e.g.: .. code-block:: text nanobind::detail::get_trampoline('PyDog::bark()'): the trampoline ran out of slots (you will need to increase the value provided to the NB_TRAMPOLINE() macro) The macro :c:macro:`NB_OVERRIDE(bark) ` intercepts the virtual function call, checks if a Python override exists, and forwards the call in that case. If no override was found, it falls back to the base class implementation. You will need to replicate this pattern for every method that should support overriding in Python. The macro accepts an variable argument list to pass additional parameters. For example, suppose that the virtual function ``bark()`` had an additional ``int volume`` parameter---in that case, the syntax would need to be adapted as follows: .. code-block:: cpp std::string bark(int volume) const override { NB_OVERRIDE(bark, volume); } The macro :c:macro:`NB_OVERRIDE_PURE() ` should be used for pure virtual functions, and :c:macro:`NB_OVERRIDE() ` should be used for functions which have a default implementation. There are also two alternate macros :c:macro:`NB_OVERRIDE_PURE_NAME() ` and :c:macro:`NB_OVERRIDE_NAME() ` which take a string as first argument to specify the name of function in Python. This is useful when the C++ and Python versions of the function have different names (e.g., ``operator+`` vs ``__add__``). The binding code needs a tiny adaptation (highlighted) to inform nanobind of the trampoline that will be used whenever Python code extends the C++ class. .. code-block:: cpp nb::class_(m, "Dog") If the :cpp:class:`nb::class_\<..\> ` declaration also specifies a base class, you may specify it and the trampoline in either order. Also, note that binding declarations should be made against the actual class, not the trampoline: .. code-block:: cpp nb::class_(m, "Dog") .def(nb::init()) .def("bark", &PyDog::bark); /* <--- THIS IS WRONG, use &Dog::bark */ With the trampoline in place, our example works as expected: .. code-block:: pycon >>> my_ext.alarm(dog) Mr. Fluffles: yip! Mr. Fluffles: yip! Mr. Fluffles: yip! The following special case needs to be mentioned: you *may not* implement a Python trampoline for a method that returns a reference or pointer to a type requiring :ref:`type casting `. For example, attempting to expose a hypothetical virtual method ``const std::string &get_name() const`` as follows .. code-block:: cpp const std::string &get_name() const override { NB_OVERRIDE(get_name); } will fail with a static assertion failure: .. code-block:: text include/nanobind/nb_cast.h:352:13: error: static_assert failed due to requirement '...' "nanobind::cast(): cannot return a reference to a temporary." This is not a fluke. The Python would return a ``str`` object that nanobind can easily type-cast into a temporary ``std::string`` instance. However, when the virtual function call returns on the C++ side, that temporary will already have expired. There isn't a good solution to this problem, and nanobind therefore simply refuses to do it. You will need to change your approach by either using :ref:`bindings ` instead of :ref:`type casters ` or changing your virtual method interfaces to return by value. .. _operator_overloading: Operator overloading -------------------- Suppose that we're given the following ``Vector2`` class with a vector addition and scalar multiplication operation, all implemented using overloaded operators in C++. .. code-block:: cpp class Vector2 { public: Vector2(float x, float y) : x(x), y(y) { } Vector2 operator+(const Vector2 &v) const { return Vector2(x + v.x, y + v.y); } Vector2 operator*(float value) const { return Vector2(x * value, y * value); } Vector2 operator-() const { return Vector2(-x, -y); } Vector2& operator+=(const Vector2 &v) { x += v.x; y += v.y; return *this; } Vector2& operator*=(float v) { x *= v; y *= v; return *this; } friend Vector2 operator*(float f, const Vector2 &v) { return Vector2(f * v.x, f * v.y); } std::string to_string() const { return "[" + std::to_string(x) + ", " + std::to_string(y) + "]"; } private: float x, y; }; The following snippet shows how the above operators can be conveniently exposed to Python. .. code-block:: cpp #include NB_MODULE(my_ext, m) { nb::class_(m, "Vector2") .def(nb::init()) .def(nb::self + nb::self) .def(nb::self += nb::self) .def(nb::self *= float()) .def(float() * nb::self) .def(nb::self * float()) .def(-nb::self) .def("__repr__", &Vector2::to_string); } Note that a line involving :cpp:var:`nb::self ` like .. code-block:: cpp .def(nb::self * float()) is really just short hand notation for .. code-block:: cpp .def("__mul__", [](const Vector2 &a, float b) { return a * b; }, nb::is_operator()) This can be useful for exposing additional operators that don't exist on the C++ side, or to perform other types of customization. The :cpp:class:`nb::is_operator() ` flag marker is needed to inform nanobind that this is an operator, which returns ``NotImplemented`` when invoked with incompatible arguments rather than throwing a type error. When binding *in-place* operators such as ``operator+=``, and when their implementation is guaranteed to end with ``return *this``, it is recommended that you set a return value policy of :cpp:enumerator:`rv_policy::none`, i.e., .. code-block:: cpp .def(nb::self += nb::self, nb::rv_policy::none) Otherwise, the function binding will return a new copy of the object, which is usually not desired. Binding protected member functions ---------------------------------- It's normally not possible to expose ``protected`` member functions to Python: .. code-block:: cpp class A { protected: int foo() const { return 42; } }; nb::class_(m, "A") .def("foo", &A::foo); // error: 'foo' is a protected member of 'A' On one hand, this is good because non-``public`` members aren't meant to be accessed from the outside. But we may want to make use of ``protected`` functions in derived Python classes. The following pattern makes this possible: .. code-block:: cpp class A { protected: int foo() const { return 42; } }; class Publicist : public A { // helper type for exposing protected functions public: using A::foo; // inherited with different access modifier }; nb::class_(m, "A") // bind the primary class .def("foo", &Publicist::foo); // expose protected methods via the publicist This works because ``&Publicist::foo`` is exactly the same function as ``&A::foo`` (same signature and address), just with a different access modifier. The only purpose of the ``Publicist`` helper class is to make the function name ``public``. If the intent is to expose ``protected`` ``virtual`` functions which can be overridden in Python, the publicist pattern can be combined with the previously described trampoline: .. code-block:: cpp class A { public: virtual ~A() = default; protected: virtual int foo() const { return 42; } }; class Trampoline : public A { public: NB_TRAMPOLINE(A, 1); int foo() const override { NB_OVERRIDE(foo); } }; class Publicist : public A { public: using A::foo; }; nb::class_(m, "A") // <-- `Trampoline` here .def("foo", &Publicist::foo); // <-- `Publicist` here, not `Trampoline`! Binding classes with template parameters ---------------------------------------- nanobind can also wrap classes that have template parameters. Consider these classes: .. code-block:: cpp struct Cat {}; struct Dog {}; template struct PetHouse { PetHouse(PetType& pet); PetType& get(); }; C++ templates may only be instantiated at compile time, so nanobind can only wrap instantiated templated classes. You cannot wrap a non-instantiated template: .. code-block:: cpp // BROKEN (this will not compile) nb::class_(m, "PetHouse"); .def("get", &PetHouse::get); You must explicitly specify each template/type combination that you want to wrap separately. .. code-block:: cpp // ok nb::class_>(m, "CatHouse") .def("get", &PetHouse::get); // ok nb::class_>(m, "DogHouse") .def("get", &PetHouse::get); If your class methods have template parameters you can wrap those as well, but once again each instantiation must be explicitly specified: .. code-block:: cpp typename struct MyClass { template T fn(V v); }; nb::class_>(m, "MyClassT") .def("fn", &MyClass::fn); .. _tag_based_polymorphism: Tag-based polymorphism ---------------------- The section on :ref:`automatic downcasting ` explained how nanobind can infer the type of polymorphic C++ objects at runtime. It can be desirable to extend this automatic downcasting behavior to non-polymorphic classes, for example to support *tag-based polymorphism*. In this case, instances expose a method or field to identify their type. For example, consider the following class hierarchy where ``Pet::kind`` serves this purpose: .. code-block:: cpp #include namespace nb = nanobind; enum class PetKind { Cat, Dog }; struct Pet { const PetKind kind; }; struct Dog : Pet { Dog() : Pet{PetKind::Dog} { } }; struct Cat : Pet { Cat() : Pet{PetKind::Cat} { } }; namespace nb = nanobind; NB_MODULE(my_ext, m) { nb::class_(m, "Pet"); nb::class_(m, "Dog"); nb::class_(m, "Cat"); nb::enum_(m, "PetKind") .value("Cat", PetKind::Cat) .value("Dog", PetKind::Dog); m.def("make_pet", [](PetKind kind) -> Pet* { switch (kind) { case PetKind::Dog: return new Dog(); case PetKind::Cat: return new Cat(); } }); } This code initially doesn't work as expected (the ``make_pet`` function binding always creates instances of the ``Pet`` base class). .. code-block:: pycon >>> my_ext.make_pet(my_ext.PetKind.Cat) >>> my_ext.make_pet(my_ext.PetKind.Dog) To fix this, partially specialize the ``type_hook`` class to provide the ``type_hook::get()`` method: .. code-block:: cpp namespace nanobind::detail { template <> struct type_hook { static const std::type_info *get(Pet *p) { if (p) { switch (p->kind) { case PetKind::Dog: return &typeid(Dog); case PetKind::Cat: return &typeid(Cat); } } return &typeid(Pet); } }; } // namespace nanobind::detail The method will be invoked whenever nanobind needs to convert a C++ pointer of type ``T*`` to a Python object. It should inspect the instance and return a pointer to a suitable RTTI record. With this override, downcasting works as expected: .. code-block:: pycon >>> my_ext.make_pet(my_ext.PetKind.Cat) >>> my_ext.make_pet(my_ext.PetKind.Dog) Binding unions -------------- :cpp:class:`nb::class_\<..\> ` can also be used to provide bindings for `unions `__. A basic and useless example: .. code-block:: cpp union Example { int ival; double dval; std::string to_string(size_t active_idx) const { return active_idx == 1 ? std::to_string(dval) : std::to_string(ival); } }; static_assert(sizeof(Example) == sizeof(double)); nb::class_(m, "Example") .def_rw("ival", &Example::ival) .def_rw("dval", &Example::dval) .def("to_string", &Example::to_string); .. code-block:: pycon >>> u = my_ext.Example() >>> u.ival = 42 >>> u.to_string(0) '42' >>> u.dval = 1.25 >>> u.to_string(1) '1.250000' Direct binding of union variant members is only safe if all members of the union are trivially copyable types (as in this example), but more complex unions can also be supported by binding lambdas or member functions that enforce the necessary invariants. This is a low-level feature and should be used with care; even when all members are trivially copyable, reading from a union member other than the most recently written one produces undefined behavior in C++. Unless you need to bind an existing API that uses union types, you're probably better off using ``std::variant<..>``, which knows what member is active and can thus enforce all the ncessary invariants for you. Pickling -------- To pickle and unpickle objects bound using nanobind, expose the ``__getstate__`` and ``__setstate__`` methods. They should return and retrieve the internal instance state using representations that themselves support pickling. The example below, e.g., does this using a tuple. The ``__setstate__`` method should construct the object in-place analogous to custom ``__init__``-style constructors. .. code-block:: cpp #include struct Pet { std::string name; int age; Pet(const std::string &name, int age) : name(name), age(age) { } }; NB_MODULE(my_ext, m) { nb::class_(m, "Pet") // ... .def("__getstate__", [](const Pet &pet) { return std::make_tuple(pet.name, pet.age); }) .def("__setstate__", [](Pet &pet, const std::tuple &state) { new (&pet) Pet( std::get<0>(state), std::get<1>(state) ); }); } .. _custom_new: Customizing Python object creation ---------------------------------- Sometimes you might need to bind a class that can't be constructed in the usual way: .. code-block:: cpp class Pet { private: Pet(/* ... */); public: static std::unique_ptr make(std::string name, int age); void speak(); }; You can use :cpp:func:`.def_static() ` to produce bindings that let you write ``Pet.make("Fido", 2)`` in Python, just like you would write ``Pet::make("Fido", 2)`` in C++. But sometimes it's nice to provide a more Pythonic interface than that, like ``Pet("Fido", 2)``. To do that, nanobind lets you override ``__new__``. Since this is a rarely-used feature in Python, let's recap. Object initialization in Python occurs in two phases: * the *constructor*, ``__new__``, allocates memory for the object; * the *initializer*, ``__init__``, sets up the object's initial state. So far, all the ways we've seen of binding C++ constructors (:cpp:struct:`nb::init\<..\>() `, ``.def("__init__", ...)``) produce Python object *initializers*. nanobind augments these with its own Python object constructor, which allocates a Python object that has space in its memory layout for the C++ object to slot in. The ``__init__`` method then fills in that space by calling a C++ constructor. This split between ``__new__`` and ``__init__`` has a lot of benefits, including a reduction in unnecessary allocations, but it does mean that anything created from Python must be able to control where its C++ innards are stored. Sometimes, as with the example of ``Pet`` above, that's not feasible. In such cases, you can go down one level and override ``__new__`` directly: .. code-block:: cpp nb::class_(m, "Pet") .def(nb::new_(&Pet::make), "name"_a, "age"_a) .def("speak", &Pet::speak); Passing :cpp:struct:`nb::new_ ` to :cpp:func:`.def() ` here creates two magic methods on ``Pet``: * A ``__new__`` that uses the given function to produce a new ``Pet``. It is converted to a Python object in the same way as the return value of any other function you might write bindings for. In particular, you can pass a :cpp:enum:`nb::rv_policy ` as an additional argument to :cpp:func:`.def() ` to control how this conversion occurs. * A ``__init__`` that takes the same arguments as ``__new__`` but performs no operation. This is necessary because Python automatically calls ``__init__`` on the object returned by ``__new__`` in most cases. You can provide a lambda as the argument of :cpp:struct:`nb::new_ `. This is most useful when the lambda returns a pointer or smart pointer; if it's returning a value, then ``.def("__init__", ...)`` will have better performance. Additionally, you can chain multiple calls to ``.def(nb::new_(...))`` in order to create an overload set. The following example demonstrates both of these capabilities: .. code-block:: cpp nb::class_(m, "Pet") .def(nb::new_([]() { return Pet::make(getRandomName(), 0); })) .def(nb::new_(&Pet::make), "name"_a, "age"_a) .def("speak", &Pet::speak); If you need even more control, perhaps because you need to access the type object that Python passes as the first argument of ``__new__`` (which :cpp:struct:`nb::new_ ` discards), you can write a ``.def_static("__new__", ...)`` and matching ``.def("__init__", ...)`` yourself. Two limitations of :cpp:struct:`nb::new_ ` are worth noting: * The possibilities for Python-side inheritance from C++ classes that are bound using :cpp:struct:`nb::new_ ` constructors are substantially reduced. Simple inheritance situations (``class PyPet(Pet): ...``) should work OK, but you can't :ref:`override virtual functions ` in Python (because the C++ object returned by :cpp:struct:`new_ ` doesn't contain the Python trampoline glue), and if :cpp:struct:`new_ ` is used to implement a polymorphic factory (like if ``Pet::make()`` could return an instance of ``Cat``) then Python-side inheritance won't work at all. * A given C++ class must expose all of its constructors via ``__new__`` or all via ``__init__``, rather than a mixture of the two. The only case where a class should bind both of these methods is if the ``__init__`` methods are all stubs that do nothing. This is because nanobind internally optimizes object instantiation by caching the method that should be used for constructing instances of each given type, and that optimization doesn't support trying both methods. If you really need to combine nontrivial ``__new__`` and nontrivial ``__init__`` in the same type, you can disable the optimization by defining a :ref:`custom type slot ` of ``Py_tp_new`` or ``Py_tp_init``. .. note:: Unpickling an object of type ``Foo`` normally requires that ``Foo.__new__(Foo)`` produce something that ``__setstate__`` can be called on. Any custom :cpp:struct:`nb::new_ ` methods will not satisfy this requirement, because they return a fully-constructed object. In order to maintain pickle compatibility, nanobind by default will add an additional ``__new__`` overload that takes no extra arguments and calls the nanobind built-in :cpp:func:`inst_alloc`. This won't make your class constructible with no arguments, because there's no corresponding ``__init__``; it just helps unpickling work. If your first :cpp:struct:`nb::new_ ` method is one that takes no arguments, then nanobind won't add its own, and you'll have to deal with unpickling some other way. Preventing object destruction ----------------------------- In rare cases, you may need to bind a class that should never be destructed by nanobind: .. code-block:: cpp class Singleton { public: static Singleton &get_instance(); }; You may use the :cpp:class:`nb::never_destruct ` annotation to make nanobind aware of this. This feature is particularly helpful when attempts to bind the destructor would fail with a compilation error (e.g., because this would require access to implementation details that are not available in the current compilation unit). .. code-block:: cpp nb::class_(m, "Singleton", nb::never_destruct()) .def_static("get_instance", &Singleton::get_instance, nb::rv_policy::reference); .. warning:: Instance class marked with :cpp:class:`nb::never_destruct ` must be returned using the :cpp:enumerator:`reference ` return value policy. Otherwise, nanobind will assume ownership, which includes the requirement of destructing the object at a later point. Similarly, you must not bind constructors or copy constructors, as the eventual garbage collection of constructed instances would require calling the destructor. nanobind will abort with a fatal error if it is ever put into a situation where an object with the :cpp:class:`nb::never_destruct ` annotation must be destructed.