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/cast/functional.rst b/docs/advanced/cast/functional.rst
index 5d0a01d..d9b4605 100644
--- a/docs/advanced/cast/functional.rst
+++ b/docs/advanced/cast/functional.rst
@@ -56,14 +56,10 @@
#include <pybind11/functional.h>
- PYBIND11_PLUGIN(example) {
- py::module m("example", "pybind11 example plugin");
-
+ PYBIND11_MODULE(example, m) {
m.def("func_arg", &func_arg);
m.def("func_ret", &func_ret);
m.def("func_cpp", &func_cpp);
-
- return m.ptr();
}
The following interactive session shows how to call them from Python.
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
diff --git a/docs/advanced/misc.rst b/docs/advanced/misc.rst
index 6ebc0c3..8751faf 100644
--- a/docs/advanced/misc.rst
+++ b/docs/advanced/misc.rst
@@ -28,7 +28,7 @@
could be realized as follows (important changes highlighted):
.. code-block:: cpp
- :emphasize-lines: 8,9,33,34
+ :emphasize-lines: 8,9,31,32
class PyAnimal : public Animal {
public:
@@ -49,9 +49,7 @@
}
};
- PYBIND11_PLUGIN(example) {
- py::module m("example", "pybind11 example plugin");
-
+ PYBIND11_MODULE(example, m) {
py::class_<Animal, PyAnimal> animal(m, "Animal");
animal
.def(py::init<>())
@@ -65,8 +63,6 @@
py::gil_scoped_release release;
return call_go(animal);
});
-
- return m.ptr();
}
The ``call_go`` wrapper can also be simplified using the `call_guard` policy
@@ -233,15 +229,11 @@
.. code-block:: cpp
- PYBIND11_PLUGIN(example) {
- py::module m("example", "pybind11 example plugin");
-
+ PYBIND11_MODULE(example, m) {
py::options options;
options.disable_function_signatures();
-
+
m.def("add", [](int a, int b) { return a + b; }, "A function which adds two numbers");
-
- return m.ptr();
}
Note that changes to the settings affect only function bindings created during the
diff --git a/docs/advanced/pycpp/numpy.rst b/docs/advanced/pycpp/numpy.rst
index 964b182..98b0c25 100644
--- a/docs/advanced/pycpp/numpy.rst
+++ b/docs/advanced/pycpp/numpy.rst
@@ -190,7 +190,7 @@
};
// ...
- PYBIND11_PLUGIN(test) {
+ PYBIND11_MODULE(test, m) {
// ...
PYBIND11_NUMPY_DTYPE(A, x, y);
@@ -284,10 +284,8 @@
return result;
}
- PYBIND11_PLUGIN(test) {
- py::module m("test");
+ PYBIND11_MODULE(test, m) {
m.def("add_arrays", &add_arrays, "Add two NumPy arrays");
- return m.ptr();
}
.. seealso::
diff --git a/docs/advanced/smart_ptrs.rst b/docs/advanced/smart_ptrs.rst
index e4a2386..da57748 100644
--- a/docs/advanced/smart_ptrs.rst
+++ b/docs/advanced/smart_ptrs.rst
@@ -63,16 +63,12 @@
std::shared_ptr<Child> child;
};
- PYBIND11_PLUGIN(example) {
- py::module m("example");
-
+ PYBIND11_MODULE(example, m) {
py::class_<Child, std::shared_ptr<Child>>(m, "Child");
py::class_<Parent, std::shared_ptr<Parent>>(m, "Parent")
.def(py::init<>())
.def("get_child", &Parent::get_child);
-
- return m.ptr();
}
The following Python code will cause undefined behavior (and likely a
diff --git a/docs/basics.rst b/docs/basics.rst
index 33c6004..aa98680 100644
--- a/docs/basics.rst
+++ b/docs/basics.rst
@@ -96,25 +96,21 @@
return i + j;
}
- namespace py = pybind11;
-
- PYBIND11_PLUGIN(example) {
- py::module m("example", "pybind11 example plugin");
+ PYBIND11_MODULE(example, m) {
+ m.doc() = "pybind11 example plugin"; // optional module docstring
m.def("add", &add, "A function which adds two numbers");
-
- return m.ptr();
}
.. [#f1] In practice, implementation and binding code will generally be located
in separate files.
-The :func:`PYBIND11_PLUGIN` macro creates a function that will be called when an
-``import`` statement is issued from within Python. The next line creates a
-module named ``example`` (with the supplied docstring). The method
-:func:`module::def` generates binding code that exposes the
-``add()`` function to Python. The last line returns the internal Python object
-associated with ``m`` to the Python interpreter.
+The :func:`PYBIND11_MODULE` macro creates a function that will be called when an
+``import`` statement is issued from within Python. The module name (``example``)
+is given as the fist macro argument (it should not be in quotes). The second
+argument (``m``) defines a variable of type :class:`py::module <module>` which
+is the main interface for creating bindings. The method :func:`module::def`
+generates binding code that exposes the ``add()`` function to Python.
.. note::
@@ -261,12 +257,10 @@
.. code-block:: cpp
- PYBIND11_PLUGIN(example) {
- py::module m("example", "pybind11 example plugin");
+ PYBIND11_MODULE(example, m) {
m.attr("the_answer") = 42;
py::object world = py::cast("World");
m.attr("what") = world;
- return m.ptr();
}
These are then accessible from Python:
diff --git a/docs/benchmark.py b/docs/benchmark.py
index 6f02e92..6dc0604 100644
--- a/docs/benchmark.py
+++ b/docs/benchmark.py
@@ -33,10 +33,8 @@
result = "#include <pybind11/pybind11.h>\n\n"
result += "namespace py = pybind11;\n\n"
result += decl + '\n'
- result += "PYBIND11_PLUGIN(example) {\n"
- result += " py::module m(\"example\");"
+ result += "PYBIND11_MODULE(example, m) {\n"
result += bindings
- result += " return m.ptr();"
result += "}"
return result
diff --git a/docs/benchmark.rst b/docs/benchmark.rst
index 8babaa3..59d533d 100644
--- a/docs/benchmark.rst
+++ b/docs/benchmark.rst
@@ -31,8 +31,7 @@
};
...
- PYBIND11_PLUGIN(example) {
- py::module m("example");
+ PYBIND11_MODULE(example, m) {
...
py::class_<cl034>(m, "cl034")
.def("fn_000", &cl034::fn_000)
@@ -40,7 +39,6 @@
.def("fn_002", &cl034::fn_002)
.def("fn_003", &cl034::fn_003)
...
- return m.ptr();
}
The Boost.Python version looks almost identical except that a return value
diff --git a/docs/classes.rst b/docs/classes.rst
index 30fb2a2..7696c60 100644
--- a/docs/classes.rst
+++ b/docs/classes.rst
@@ -27,15 +27,11 @@
namespace py = pybind11;
- PYBIND11_PLUGIN(example) {
- py::module m("example", "pybind11 example plugin");
-
+ PYBIND11_MODULE(example, m) {
py::class_<Pet>(m, "Pet")
.def(py::init<const std::string &>())
.def("setName", &Pet::setName)
.def("getName", &Pet::getName);
-
- return m.ptr();
}
:class:`class_` creates bindings for a C++ *class* or *struct*-style data
diff --git a/docs/faq.rst b/docs/faq.rst
index 34002b4..072b157 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -4,30 +4,24 @@
"ImportError: dynamic module does not define init function"
===========================================================
-1. Make sure that the name specified in ``pybind::module`` and
- ``PYBIND11_PLUGIN`` is consistent and identical to the filename of the
- extension library. The latter should not contain any extra prefixes (e.g.
- ``test.so`` instead of ``libtest.so``).
-
-2. If the above did not fix your issue, then you are likely using an
- incompatible version of Python (for instance, the extension library was
- compiled against Python 2, while the interpreter is running on top of some
- version of Python 3, or vice versa)
+You are likely using an incompatible version of Python (for instance, the
+extension library was compiled against Python 2, while the interpreter is
+running on top of some version of Python 3, or vice versa).
"Symbol not found: ``__Py_ZeroStruct`` / ``_PyInstanceMethod_Type``"
========================================================================
-See item 2 of the first answer.
+See the first answer.
"SystemError: dynamic module not initialized properly"
======================================================
-See item 2 of the first answer.
+See the first answer.
The Python interpreter immediately crashes when importing my module
===================================================================
-See item 2 of the first answer.
+See the first answer.
CMake doesn't detect the right Python version
=============================================
@@ -104,14 +98,10 @@
void init_ex2(py::module &);
/* ... */
- PYBIND11_PLUGIN(example) {
- py::module m("example", "pybind example plugin");
-
+ PYBIND11_MODULE(example, m) {
init_ex1(m);
init_ex2(m);
/* ... */
-
- return m.ptr();
}
:file:`ex1.cpp`:
diff --git a/docs/reference.rst b/docs/reference.rst
index f375791..d9dc961 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -12,7 +12,7 @@
Macros
======
-.. doxygendefine:: PYBIND11_PLUGIN
+.. doxygendefine:: PYBIND11_MODULE
.. _core_types: