From ac9d31e13fd15f2a8e3deeccd840e5038c028da8 Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Mon, 24 Feb 2025 12:10:38 -0800 Subject: [PATCH] Systematically change most py::class_ to py::classh under docs/ --- docs/advanced/cast/eigen.rst | 4 +- docs/advanced/cast/overview.rst | 14 ++-- docs/advanced/cast/stl.rst | 6 +- docs/advanced/classes.rst | 135 ++++++++++++++------------------ docs/advanced/functions.rst | 22 +++--- docs/advanced/misc.rst | 26 +++--- docs/advanced/pycpp/numpy.rst | 6 +- docs/classes.rst | 40 +++++----- 8 files changed, 116 insertions(+), 137 deletions(-) diff --git a/docs/advanced/cast/eigen.rst b/docs/advanced/cast/eigen.rst index 894ce97f3..0e6be8a14 100644 --- a/docs/advanced/cast/eigen.rst +++ b/docs/advanced/cast/eigen.rst @@ -102,7 +102,7 @@ example: }; // Later, in binding code: - py::class_(m, "MyClass") + py::classh(m, "MyClass") .def(py::init<>()) .def("copy_matrix", &MyClass::getMatrix) // Makes a copy! .def("get_matrix", &MyClass::getMatrix, py::return_value_policy::reference_internal) @@ -250,7 +250,7 @@ copying to take place: // The associated binding code: using namespace pybind11::literals; // for "arg"_a - py::class_(m, "MyClass") + py::classh(m, "MyClass") // ... other class definitions .def("some_method", &MyClass::some_method, py::arg().noconvert()); diff --git a/docs/advanced/cast/overview.rst b/docs/advanced/cast/overview.rst index d5a34ef94..2594924b7 100644 --- a/docs/advanced/cast/overview.rst +++ b/docs/advanced/cast/overview.rst @@ -3,13 +3,13 @@ Overview .. rubric:: 1. Native type in C++, wrapper in Python -Exposing a custom C++ type using :class:`py::class_` was covered in detail -in the :doc:`/classes` section. There, the underlying data structure is -always the original C++ class while the :class:`py::class_` wrapper provides -a Python interface. Internally, when an object like this is sent from C++ to -Python, pybind11 will just add the outer wrapper layer over the native C++ -object. Getting it back from Python is just a matter of peeling off the -wrapper. +Exposing a custom C++ type using ``py::classh`` (or ``py::class_``) was +covered in detail in the :doc:`/classes` section. There, the underlying +data structure is always the original C++ class while the ``py::classh`` +wrapper provides a Python interface. Internally, when an object like this +is sent from C++ to Python, pybind11 will just add the outer wrapper layer +over the native C++ object. Getting it back from Python is just a matter of +peeling off the wrapper. .. rubric:: 2. Wrapper in C++, native type in Python diff --git a/docs/advanced/cast/stl.rst b/docs/advanced/cast/stl.rst index 42b85532d..169c17d7d 100644 --- a/docs/advanced/cast/stl.rst +++ b/docs/advanced/cast/stl.rst @@ -135,7 +135,7 @@ functions: /* ... binding code ... */ - py::class_(m, "MyClass") + py::classh(m, "MyClass") .def(py::init<>()) .def_readwrite("contents", &MyClass::contents); @@ -169,12 +169,12 @@ macro must be specified at the top level (and outside of any namespaces), since it adds a template instantiation of ``type_caster``. If your binding code consists of multiple compilation units, it must be present in every file (typically via a common header) preceding any usage of ``std::vector``. Opaque types must -also have a corresponding ``class_`` declaration to associate them with a name +also have a corresponding ``py::classh`` declaration to associate them with a name in Python, and to define a set of available operations, e.g.: .. code-block:: cpp - py::class_>(m, "IntVector") + py::classh>(m, "IntVector") .def(py::init<>()) .def("clear", &std::vector::clear) .def("pop_back", &std::vector::pop_back) diff --git a/docs/advanced/classes.rst b/docs/advanced/classes.rst index 45c038ef7..dbe4a6f39 100644 --- a/docs/advanced/classes.rst +++ b/docs/advanced/classes.rst @@ -46,10 +46,10 @@ Normally, the binding code for these classes would look as follows: .. code-block:: cpp PYBIND11_MODULE(example, m) { - py::class_(m, "Animal") + py::classh(m, "Animal") .def("go", &Animal::go); - py::class_(m, "Dog") + py::classh(m, "Dog") .def(py::init<>()); m.def("call_go", &call_go); @@ -64,7 +64,7 @@ helper class that is defined as follows: .. code-block:: cpp - class PyAnimal : public Animal { + class PyAnimal : public Animal, py::trampoline_self_life_support { public: /* Inherit the constructors */ using Animal::Animal; @@ -80,6 +80,11 @@ helper class that is defined as follows: } }; +The ``py::trampoline_self_life_support`` base class is needed to ensure that a +``std::unique_ptr`` can safely be passed between Python and C++. It is best +practice to always use the base class, although it may not strictly be needed +in all use cases. + The macro :c:macro:`PYBIND11_OVERRIDE_PURE` should be used for pure virtual functions, and :c:macro:`PYBIND11_OVERRIDE` should be used for functions which have a default implementation. There are also two alternate macros @@ -95,28 +100,30 @@ The binding code also needs a few minor adaptations (highlighted): :emphasize-lines: 2,3 PYBIND11_MODULE(example, m) { - py::class_(m, "Animal") + py::classh(m, "Animal") .def(py::init<>()) .def("go", &Animal::go); - py::class_(m, "Dog") + py::classh(m, "Dog") .def(py::init<>()); m.def("call_go", &call_go); } Importantly, pybind11 is made aware of the trampoline helper class by -specifying it as an extra template argument to :class:`class_`. (This can also -be combined with other template arguments such as a custom holder type; the -order of template types does not matter). Following this, we are able to -define a constructor as usual. +specifying it as an extra template argument to ``py::classh``. (This can also +be combined with other template arguments; the order of template types does +not matter). Using ``py::classh`` (vs ``py::class_``) is to ensure that that +a ``std::unique_ptr`` can safely be passed between Python and C++ (see +:ref:`smart_holder`). -Bindings should be made against the actual class, not the trampoline helper class. +A constructor can be defined as usual. Bindings should be made against the +actual class, not the trampoline helper class. .. code-block:: cpp :emphasize-lines: 3 - py::class_(m, "Animal"); + py::classh(m, "Animal"); .def(py::init<>()) .def("go", &PyAnimal::go); /* <--- THIS IS WRONG, use &Animal::go */ @@ -125,32 +132,6 @@ extend ``Animal``, but not ``Dog``: see :ref:`virtual_and_inheritance` for the necessary steps required to providing proper overriding support for inherited classes. -To enable safely passing a ``std::unique_ptr`` to a trampoline object between -Python and C++, - -1. the C++ type (``Animal`` above) must be wrapped with ``py::classh`` - (see :ref:`smart_holder`), and - -2. the trampoline helper class must inherit from - ``py::trampoline_self_life_support``. - -I.e. the example above needs these two changes: - -.. code-block:: cpp - - class PyAnimal : public Animal, public py::trampoline_self_life_support { - ... - }; - -.. code-block:: cpp - - py::classh(m, "Animal"); - -.. seealso:: - - A fairly minimal but complete example is in - :file:`tests/test_class_sh_trampoline_unique_ptr.cpp`. - The Python session below shows how to override ``Animal::go`` and invoke it via a virtual method call. @@ -337,9 +318,9 @@ The classes are then registered with pybind11 using: .. code-block:: cpp - py::class_> animal(m, "Animal"); - py::class_> dog(m, "Dog"); - py::class_> husky(m, "Husky"); + py::classh> animal(m, "Animal"); + py::classh> dog(m, "Dog"); + py::classh> husky(m, "Husky"); // ... add animal, dog, husky definitions Note that ``Husky`` did not require a dedicated trampoline template class at @@ -456,7 +437,7 @@ class like this: static Example create(int a) { return Example(a); } }; - py::class_(m, "Example") + py::classh(m, "Example") .def(py::init(&Example::create)); While it is possible to create a straightforward binding of the static @@ -483,7 +464,7 @@ The following example shows the different approaches: Example(std::string); }; - py::class_(m, "Example") + py::classh(m, "Example") // Bind the factory function as a constructor: .def(py::init(&Example::create)) // Bind a lambda function returning a pointer wrapped in a holder: @@ -530,7 +511,7 @@ an alias: using Example::Example; PyExample(Example &&base) : Example(std::move(base)) {} }; - py::class_(m, "Example") + py::classh(m, "Example") // Returns an Example pointer. If a PyExample is needed, the Example // instance will be moved via the extra constructor in PyExample, above. .def(py::init([]() { return new Example(); })) @@ -555,7 +536,7 @@ constructor of the target class. This means that it can be used to bind std::string b; }; - py::class_(m, "Aggregate") + py::classh(m, "Aggregate") .def(py::init()); .. note:: @@ -572,13 +553,11 @@ Non-public destructors If a class has a private or protected destructor (as might e.g. be the case in a singleton pattern), a compile error will occur when creating bindings via -pybind11. The underlying issue is that the ``std::unique_ptr`` holder type that -is responsible for managing the lifetime of instances will reference the -destructor even if no deallocations ever take place. In order to expose classes -with private or protected destructors, it is possible to override the holder -type via a holder type argument to ``class_``. Pybind11 provides a helper class -``py::nodelete`` that disables any destructor invocations. In this case, it is -crucial that instances are deallocated on the C++ side to avoid memory leaks. +pybind11. In order to expose classes with private or protected destructors, +it is possible to override the holder type via a holder type argument to +``class_``. Pybind11 provides a helper class ``py::nodelete`` that disables +any destructor invocations. (If the instance is not a singleton, it is +crucial that is deallocated on the C++ side to avoid memory leaks.) .. code-block:: cpp @@ -645,10 +624,10 @@ could be a fixed and an arbitrary precision number type). .. code-block:: cpp - py::class_(m, "A") + py::classh(m, "A") /// ... members ... - py::class_(m, "B") + py::classh(m, "B") .def(py::init()) /// ... members ... @@ -695,7 +674,7 @@ that ignores it: .. code-block:: cpp - py::class_(m, "Foo") + py::classh(m, "Foo") .def_property_readonly_static("foo", [](py::object /* self */) { return Foo(); }); Operator overloading @@ -735,7 +714,7 @@ to Python. #include PYBIND11_MODULE(example, m) { - py::class_(m, "Vector2") + py::classh(m, "Vector2") .def(py::init()) .def(py::self + py::self) .def(py::self += py::self) @@ -807,7 +786,7 @@ to bind these two functions: .. code-block:: cpp - py::class_(m, "Pickleable") + py::classh(m, "Pickleable") .def(py::init()) .def("value", &Pickleable::value) .def("extra", &Pickleable::extra) @@ -878,7 +857,7 @@ which should look as follows: .. code-block:: cpp - py::class_(m, "Copyable") + py::classh(m, "Copyable") .def("__copy__", [](const Copyable &self) { return Copyable(self); }) @@ -897,11 +876,11 @@ Multiple Inheritance pybind11 can create bindings for types that derive from multiple base types (aka. *multiple inheritance*). To do so, specify all bases in the template -arguments of the ``class_`` declaration: +arguments of the ``py::classh`` declaration: .. code-block:: cpp - py::class_(m, "MyType") + py::classh(m, "MyType") ... The base types can be specified in arbitrary order, and they can even be @@ -921,7 +900,7 @@ inheritance, which can lead to undefined behavior. In such cases, add the tag .. code-block:: cpp - py::class_(m, "MyType", py::multiple_inheritance()); + py::classh(m, "MyType", py::multiple_inheritance()); The tag is redundant and does not need to be specified when multiple base types are listed. @@ -939,7 +918,7 @@ example, this allows the following: .. code-block:: cpp // In the module1.cpp binding code for module1: - py::class_(m, "Pet") + py::classh(m, "Pet") .def(py::init()) .def_readonly("name", &Pet::name); @@ -972,11 +951,11 @@ because of conflicting definitions on the external type: // dogs.cpp // Binding for external library class: - py::class(m, "Pet") + py::classh(m, "Pet") .def("name", &pets::Pet::name); // Binding for local extension class: - py::class(m, "Dog") + py::classh(m, "Dog") .def(py::init()); .. code-block:: cpp @@ -984,11 +963,11 @@ because of conflicting definitions on the external type: // cats.cpp, in a completely separate project from the above dogs.cpp. // Binding for external library class: - py::class(m, "Pet") + py::classh(m, "Pet") .def("get_name", &pets::Pet::name); // Binding for local extending class: - py::class(m, "Cat") + py::classh(m, "Cat") .def(py::init()); .. code-block:: pycon @@ -1001,18 +980,18 @@ because of conflicting definitions on the external type: To get around this, you can tell pybind11 to keep the external class binding localized to the module by passing the ``py::module_local()`` attribute into -the ``py::class_`` constructor: +the ``py::classh`` constructor: .. code-block:: cpp // Pet binding in dogs.cpp: - py::class(m, "Pet", py::module_local()) + py::classh(m, "Pet", py::module_local()) .def("name", &pets::Pet::name); .. code-block:: cpp // Pet binding in cats.cpp: - py::class(m, "Pet", py::module_local()) + py::classh(m, "Pet", py::module_local()) .def("get_name", &pets::Pet::name); This makes the Python-side ``dogs.Pet`` and ``cats.Pet`` into distinct classes, @@ -1087,7 +1066,7 @@ It's normally not possible to expose ``protected`` member functions to Python: int foo() const { return 42; } }; - py::class_(m, "A") + py::classh(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 @@ -1108,7 +1087,7 @@ The following pattern makes this possible: using A::foo; // inherited with different access modifier }; - py::class_(m, "A") // bind the primary class + py::classh(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 @@ -1140,7 +1119,7 @@ described trampoline: using A::foo; }; - py::class_(m, "A") // <-- `Trampoline` here + py::classh(m, "A") // <-- `Trampoline` here .def("foo", &Publicist::foo); // <-- `Publicist` here, not `Trampoline`! Binding final classes @@ -1156,7 +1135,7 @@ to be declared final. class IsFinal final {}; - py::class_(m, "IsFinal", py::is_final()); + py::classh(m, "IsFinal", py::is_final()); When you try to inherit from such a class in Python, you will now get this error: @@ -1194,7 +1173,7 @@ wrap instantiated templated classes. You cannot wrap a non-instantiated template .. code-block:: cpp // BROKEN (this will not compile) - py::class_(m, "Cage"); + py::classh(m, "Cage"); .def("get", &Cage::get); You must explicitly specify each template/type combination that you want to @@ -1203,11 +1182,11 @@ wrap separately. .. code-block:: cpp // ok - py::class_>(m, "CatCage") + py::classh>(m, "CatCage") .def("get", &Cage::get); // ok - py::class_>(m, "DogCage") + py::classh>(m, "DogCage") .def("get", &Cage::get); If your class methods have template parameters you can wrap those as well, @@ -1221,7 +1200,7 @@ but once again each instantiation must be explicitly specified: T fn(V v); }; - py::class>(m, "MyClassT") + py::classh>(m, "MyClassT") .def("fn", &MyClass::fn); Custom automatic downcasters @@ -1330,7 +1309,7 @@ Custom type setup For advanced use cases, such as enabling garbage collection support, you may wish to directly manipulate the ``PyHeapTypeObject`` corresponding to a -``py::class_`` definition. +``py::classh`` definition. You can do that using ``py::custom_type_setup``: @@ -1339,7 +1318,7 @@ You can do that using ``py::custom_type_setup``: struct OwnsPythonObjects { py::object value = py::none(); }; - py::class_ cls( + py::classh cls( m, "OwnsPythonObjects", py::custom_type_setup([](PyHeapTypeObject *heap_type) { auto *type = &heap_type->ht_type; type->tp_flags |= Py_TPFLAGS_HAVE_GC; diff --git a/docs/advanced/functions.rst b/docs/advanced/functions.rst index ff00c9c8a..4313c1b41 100644 --- a/docs/advanced/functions.rst +++ b/docs/advanced/functions.rst @@ -110,7 +110,7 @@ Return value policies can also be applied to properties: .. code-block:: cpp - class_(m, "MyClass") + py::classh(m, "MyClass") .def_property("data", &MyClass::getData, &MyClass::setData, py::return_value_policy::copy); @@ -121,7 +121,7 @@ targeted arguments can be passed through the :class:`cpp_function` constructor: .. code-block:: cpp - class_(m, "MyClass") + py::classh(m, "MyClass") .def_property("data", py::cpp_function(&MyClass::getData, py::return_value_policy::copy), py::cpp_function(&MyClass::setData) @@ -194,7 +194,7 @@ container: .. code-block:: cpp - py::class_(m, "List") + py::classh(m, "List") .def("append", &List::append, py::keep_alive<1, 2>()); For consistency, the argument indexing is identical for constructors. Index @@ -205,7 +205,7 @@ ties the lifetime of the constructor element to the constructed object: .. code-block:: cpp - py::class_(m, "Nurse") + py::classh(m, "Nurse") .def(py::init(), py::keep_alive<1, 2>()); .. note:: @@ -332,11 +332,11 @@ Consider the following example: .. code-block:: cpp - py::class_("MyClass") + py::classh("MyClass") .def("myFunction", py::arg("arg") = SomeType(123)); In this case, pybind11 must already be set up to deal with values of the type -``SomeType`` (via a prior instantiation of ``py::class_``), or an +``SomeType`` (via a prior instantiation of ``py::classh``), or an exception will be thrown. Another aspect worth highlighting is that the "preview" of the default argument @@ -357,7 +357,7 @@ default argument manually using the ``arg_v`` notation: .. code-block:: cpp - py::class_("MyClass") + py::classh("MyClass") .def("myFunction", py::arg_v("arg", SomeType(123), "SomeType(123)")); Sometimes it may be necessary to pass a null pointer value as a default @@ -366,7 +366,7 @@ like so: .. code-block:: cpp - py::class_("MyClass") + py::classh("MyClass") .def("myFunction", py::arg("arg") = static_cast(nullptr)); .. _keyword_only_arguments: @@ -489,7 +489,7 @@ name, i.e. by specifying ``py::arg().noconvert()``. Allow/Prohibiting None arguments ================================ -When a C++ type registered with :class:`py::class_` is passed as an argument to +When a C++ type registered with :class:`py::classh` is passed as an argument to a function taking the instance as pointer or shared holder (e.g. ``shared_ptr`` or a custom, copyable holder as described in :ref:`smart_pointers`), pybind allows ``None`` to be passed from Python which results in calling the C++ @@ -500,8 +500,8 @@ To explicitly enable or disable this behaviour, using the .. code-block:: cpp - py::class_(m, "Dog").def(py::init<>()); - py::class_(m, "Cat").def(py::init<>()); + py::classh(m, "Dog").def(py::init<>()); + py::classh(m, "Cat").def(py::init<>()); m.def("bark", [](Dog *dog) -> std::string { if (dog) return "woof!"; /* Called with a Dog instance */ else return "(no dog)"; /* Called with None, dog == nullptr */ diff --git a/docs/advanced/misc.rst b/docs/advanced/misc.rst index a256da54a..0ba310869 100644 --- a/docs/advanced/misc.rst +++ b/docs/advanced/misc.rst @@ -80,7 +80,7 @@ could be realized as follows (important changes highlighted): .. code-block:: cpp :emphasize-lines: 8,30,31 - class PyAnimal : public Animal { + class PyAnimal : public Animal, py::trampoline_self_life_support { public: /* Inherit the constructors */ using Animal::Animal; @@ -98,12 +98,12 @@ could be realized as follows (important changes highlighted): }; PYBIND11_MODULE(example, m) { - py::class_ animal(m, "Animal"); + py::classh animal(m, "Animal"); animal .def(py::init<>()) .def("go", &Animal::go); - py::class_(m, "Dog", animal) + py::classh(m, "Dog", animal) .def(py::init<>()); m.def("call_go", [](Animal *animal) -> std::string { @@ -177,30 +177,30 @@ from Section :ref:`inheritance`. .. code-block:: cpp - py::class_ pet(m, "Pet"); + py::classh pet(m, "Pet"); pet.def(py::init()) .def_readwrite("name", &Pet::name); - py::class_(m, "Dog", pet /* <- specify parent */) + py::classh(m, "Dog", pet /* <- specify parent */) .def(py::init()) .def("bark", &Dog::bark); Suppose now that ``Pet`` bindings are defined in a module named ``basic``, whereas the ``Dog`` bindings are defined somewhere else. The challenge is of course that the variable ``pet`` is not available anymore though it is needed -to indicate the inheritance relationship to the constructor of ``class_``. -However, it can be acquired as follows: +to indicate the inheritance relationship to the constructor of +``py::classh``. However, it can be acquired as follows: .. code-block:: cpp py::object pet = (py::object) py::module_::import("basic").attr("Pet"); - py::class_(m, "Dog", pet) + py::classh(m, "Dog", pet) .def(py::init()) .def("bark", &Dog::bark); Alternatively, you can specify the base class as a template parameter option to -``class_``, which performs an automated lookup of the corresponding Python +``py::classh``, which performs an automated lookup of the corresponding Python type. Like the above code, however, this also requires invoking the ``import`` function once to ensure that the pybind11 binding code of the module ``basic`` has been executed: @@ -209,7 +209,7 @@ has been executed: py::module_::import("basic"); - py::class_(m, "Dog") + py::classh(m, "Dog") .def(py::init()) .def("bark", &Dog::bark); @@ -382,7 +382,7 @@ Avoiding C++ types in docstrings Docstrings are generated at the time of the declaration, e.g. when ``.def(...)`` is called. At this point parameter and return types should be known to pybind11. -If a custom type is not exposed yet through a ``py::class_`` constructor or a custom type caster, +If a custom type is not exposed yet through a ``py::classh`` constructor or a custom type caster, its C++ type name will be used instead to generate the signature in the docstring: .. code-block:: text @@ -399,8 +399,8 @@ before they are used as a parameter or return type of a function: PYBIND11_MODULE(example, m) { - auto pyFoo = py::class_(m, "Foo"); - auto pyBar = py::class_(m, "Bar"); + auto pyFoo = py::classh(m, "Foo"); + auto pyBar = py::classh(m, "Bar"); pyFoo.def(py::init()); pyBar.def(py::init()); diff --git a/docs/advanced/pycpp/numpy.rst b/docs/advanced/pycpp/numpy.rst index d09a2cea2..f734b0bde 100644 --- a/docs/advanced/pycpp/numpy.rst +++ b/docs/advanced/pycpp/numpy.rst @@ -33,7 +33,7 @@ completely avoid copy operations with Python expressions like .. code-block:: cpp - py::class_(m, "Matrix", py::buffer_protocol()) + py::classh(m, "Matrix", py::buffer_protocol()) .def_buffer([](Matrix &m) -> py::buffer_info { return py::buffer_info( m.data(), /* Pointer to buffer */ @@ -47,7 +47,7 @@ completely avoid copy operations with Python expressions like }); Supporting the buffer protocol in a new type involves specifying the special -``py::buffer_protocol()`` tag in the ``py::class_`` constructor and calling the +``py::buffer_protocol()`` tag in the ``py::classh`` constructor and calling the ``def_buffer()`` method with a lambda function that creates a ``py::buffer_info`` description record on demand describing a given matrix instance. The contents of ``py::buffer_info`` mirror the Python buffer protocol @@ -80,7 +80,7 @@ buffer objects (e.g. a NumPy matrix). typedef Matrix::Scalar Scalar; constexpr bool rowMajor = Matrix::Flags & Eigen::RowMajorBit; - py::class_(m, "Matrix", py::buffer_protocol()) + py::classh(m, "Matrix", py::buffer_protocol()) .def(py::init([](py::buffer b) { typedef Eigen::Stride Strides; diff --git a/docs/classes.rst b/docs/classes.rst index 4ae47053c..6741d73a5 100644 --- a/docs/classes.rst +++ b/docs/classes.rst @@ -28,13 +28,13 @@ The binding code for ``Pet`` looks as follows: namespace py = pybind11; PYBIND11_MODULE(example, m) { - py::class_(m, "Pet") + py::classh(m, "Pet") .def(py::init()) .def("setName", &Pet::setName) .def("getName", &Pet::getName); } -:class:`class_` creates bindings for a C++ *class* or *struct*-style data +``py::classh`` creates bindings for a C++ *class* or *struct*-style data structure. :func:`init` is a convenience function that takes the types of a constructor's parameters as template arguments and wraps the corresponding constructor (see the :ref:`custom_constructors` section for details). @@ -98,7 +98,7 @@ Lambda function instead: .. code-block:: cpp - py::class_(m, "Pet") + py::classh(m, "Pet") .def(py::init()) .def("setName", &Pet::setName) .def("getName", &Pet::getName) @@ -129,7 +129,7 @@ method also exists for ``const`` fields. .. code-block:: cpp - py::class_(m, "Pet") + py::classh(m, "Pet") .def(py::init()) .def_readwrite("name", &Pet::name) // ... remainder ... @@ -166,7 +166,7 @@ the setter and getter functions: .. code-block:: cpp - py::class_(m, "Pet") + py::classh(m, "Pet") .def(py::init()) .def_property("name", &Pet::getName, &Pet::setName) // ... remainder ... @@ -202,7 +202,7 @@ or :func:`class_::def_property`. .. code-block:: cpp - py::class_(m, "Pet") + py::classh(m, "Pet") .def(py::init<>()) .def_readwrite("name", &Pet::name); @@ -220,7 +220,7 @@ must be added to the :class:`py::class_` constructor: .. code-block:: cpp - py::class_(m, "Pet", py::dynamic_attr()) + py::classh(m, "Pet", py::dynamic_attr()) .def(py::init<>()) .def_readwrite("name", &Pet::name); @@ -268,12 +268,12 @@ parameter of the :class:`class_`: .. code-block:: cpp - py::class_(m, "Pet") + py::classh(m, "Pet") .def(py::init()) .def_readwrite("name", &Pet::name); // Method 1: template parameter: - py::class_(m, "Dog") + py::classh(m, "Dog") .def(py::init()) .def("bark", &Dog::bark); @@ -282,12 +282,12 @@ Alternatively, we can also assign a name to the previously bound ``Pet`` .. code-block:: cpp - py::class_ pet(m, "Pet"); + py::classh pet(m, "Pet"); pet.def(py::init()) .def_readwrite("name", &Pet::name); - // Method 2: pass parent class_ object: - py::class_(m, "Dog", pet /* <- specify Python parent type */) + // Method 2: pass parent py::classh object: + py::classh(m, "Dog", pet /* <- specify Python parent type */) .def(py::init()) .def("bark", &Dog::bark); @@ -334,8 +334,8 @@ will automatically recognize this: }; // Same binding code - py::class_(m, "PolymorphicPet"); - py::class_(m, "PolymorphicDog") + py::classh(m, "PolymorphicPet"); + py::classh(m, "PolymorphicDog") .def(py::init<>()) .def("bark", &PolymorphicDog::bark); @@ -387,7 +387,7 @@ sequence. .. code-block:: cpp - py::class_(m, "Pet") + py::classh(m, "Pet") .def(py::init()) .def("set", static_cast(&Pet::set), "Set the pet's age") .def("set", static_cast(&Pet::set), "Set the pet's name"); @@ -418,7 +418,7 @@ syntax to cast the overloaded function: .. code-block:: cpp - py::class_(m, "Pet") + py::classh(m, "Pet") .def("set", py::overload_cast(&Pet::set), "Set the pet's age") .def("set", py::overload_cast(&Pet::set), "Set the pet's name"); @@ -434,7 +434,7 @@ on constness, the ``py::const_`` tag should be used: int foo(int x, float y) const; }; - py::class_(m, "Widget") + py::classh(m, "Widget") .def("foo_mutable", py::overload_cast(&Widget::foo)) .def("foo_const", py::overload_cast(&Widget::foo, py::const_)); @@ -446,7 +446,7 @@ you can use ``py::detail::overload_cast_impl`` with an additional set of parenth template using overload_cast_ = pybind11::detail::overload_cast_impl; - py::class_(m, "Pet") + py::classh(m, "Pet") .def("set", overload_cast_()(&Pet::set), "Set the pet's age") .def("set", overload_cast_()(&Pet::set), "Set the pet's name"); @@ -486,7 +486,7 @@ The binding code for this example looks as follows: .. code-block:: cpp - py::class_ pet(m, "Pet"); + py::classh pet(m, "Pet"); pet.def(py::init()) .def_readwrite("name", &Pet::name) @@ -498,7 +498,7 @@ The binding code for this example looks as follows: .value("Cat", Pet::Kind::Cat) .export_values(); - py::class_(pet, "Attributes") + py::classh(pet, "Attributes") .def(py::init<>()) .def_readwrite("age", &Pet::Attributes::age);