Replace PYBIND11_PLUGIN with PYBIND11_MODULE
This commit also adds `doc()` to `object_api` as a shortcut for the
`attr("__doc__")` accessor.
The module macro changes from:
```c++
PYBIND11_PLUGIN(example) {
pybind11::module m("example", "pybind11 example plugin");
m.def("add", [](int a, int b) { return a + b; });
return m.ptr();
}
```
to:
```c++
PYBIND11_MODULE(example, m) {
m.doc() = "pybind11 example plugin";
m.def("add", [](int a, int b) { return a + b; });
}
```
Using the old macro results in a deprecation warning. The warning
actually points to the `pybind11_init` function (since attributes
don't bind to macros), but the message should be quite clear:
"PYBIND11_PLUGIN is deprecated, use PYBIND11_MODULE".
diff --git a/docs/advanced/classes.rst b/docs/advanced/classes.rst
index 8896441..b6e0a2f 100644
--- a/docs/advanced/classes.rst
+++ b/docs/advanced/classes.rst
@@ -45,9 +45,7 @@
.. code-block:: cpp
- PYBIND11_PLUGIN(example) {
- py::module m("example", "pybind11 example plugin");
-
+ PYBIND11_MODULE(example, m) {
py::class_<Animal> animal(m, "Animal");
animal
.def("go", &Animal::go);
@@ -56,8 +54,6 @@
.def(py::init<>());
m.def("call_go", &call_go);
-
- return m.ptr();
}
However, these bindings are impossible to extend: ``Animal`` is not
@@ -97,11 +93,9 @@
The binding code also needs a few minor adaptations (highlighted):
.. code-block:: cpp
- :emphasize-lines: 4,6,7
+ :emphasize-lines: 2,4,5
- PYBIND11_PLUGIN(example) {
- py::module m("example", "pybind11 example plugin");
-
+ PYBIND11_MODULE(example, m) {
py::class_<Animal, PyAnimal /* <--- trampoline*/> animal(m, "Animal");
animal
.def(py::init<>())
@@ -111,8 +105,6 @@
.def(py::init<>());
m.def("call_go", &call_go);
-
- return m.ptr();
}
Importantly, pybind11 is made aware of the trampoline helper class by
@@ -491,9 +483,7 @@
#include <pybind11/operators.h>
- PYBIND11_PLUGIN(example) {
- py::module m("example", "pybind11 example plugin");
-
+ PYBIND11_MODULE(example, m) {
py::class_<Vector2>(m, "Vector2")
.def(py::init<float, float>())
.def(py::self + py::self)
@@ -502,8 +492,6 @@
.def(float() * py::self)
.def(py::self * float())
.def("__repr__", &Vector2::toString);
-
- return m.ptr();
}
Note that a line like