fix: rename `pybind11::module` to `pybind11::module_` (#2489)

Support C++20. For backwards compatibility, we provide an alias for the old name.
This change is necessary to easily avoid errors when a compiler thinks
`module` is used as a keyword.

docs/changelog.rst

@@ -11,6 +11,11 @@ v2.6.0 (IN PROGRESS)
 
 
 See :ref:`upgrade-guide-2.6` for help upgrading to the new version.
 See :ref:`upgrade-guide-2.6` for help upgrading to the new version.
 
 
+* Provide an additional spelling of ``py::module`` - ``py::module_`` (with a
+  trailing underscore), for C++20 compatibility. Only relevant when used
+  unqualified.
+  `#2489 <https://github.com/pybind/pybind11/pull/2489>`_
+
 * ``pybind11_add_module()`` now accepts an optional ``OPT_SIZE`` flag that
 * ``pybind11_add_module()`` now accepts an optional ``OPT_SIZE`` flag that
   switches the binding target to size-based optimization regardless global
   switches the binding target to size-based optimization regardless global
   CMake build type (except in debug mode, where optimizations remain disabled).
   CMake build type (except in debug mode, where optimizations remain disabled).

docs/reference.rst

@@ -46,7 +46,7 @@ With reference counting
 Convenience classes for specific Python types
 Convenience classes for specific Python types
 =============================================
 =============================================
 
 
-.. doxygenclass:: module
+.. doxygenclass:: module_
     :members:
     :members:
 
 
 .. doxygengroup:: pytypes
 .. doxygengroup:: pytypes

include/pybind11/numpy.h

@@ -222,7 +222,7 @@ private:
     };
     };
 
 
     static npy_api lookup() {
     static npy_api lookup() {
-        module m = module::import("numpy.core.multiarray");
+        module_ m = module::import("numpy.core.multiarray");
         auto c = m.attr("_ARRAY_API");
         auto c = m.attr("_ARRAY_API");
 #if PY_MAJOR_VERSION >= 3
 #if PY_MAJOR_VERSION >= 3
         void **api_ptr = (void **) PyCapsule_GetPointer(c.ptr(), NULL);
         void **api_ptr = (void **) PyCapsule_GetPointer(c.ptr(), NULL);

include/pybind11/pybind11.h

@@ -852,12 +852,12 @@ protected:
 };
 };
 
 
 /// Wrapper for Python extension modules
 /// Wrapper for Python extension modules
-class module : public object {
+class module_ : public object {
 public:
 public:
-    PYBIND11_OBJECT_DEFAULT(module, object, PyModule_Check)
+    PYBIND11_OBJECT_DEFAULT(module_, object, PyModule_Check)
 
 
     /// Create a new top-level Python module with the given name and docstring
     /// Create a new top-level Python module with the given name and docstring
-    explicit module(const char *name, const char *doc = nullptr) {
+    explicit module_(const char *name, const char *doc = nullptr) {
         if (!options::show_user_defined_docstrings()) doc = nullptr;
         if (!options::show_user_defined_docstrings()) doc = nullptr;
 #if PY_MAJOR_VERSION >= 3
 #if PY_MAJOR_VERSION >= 3
         auto *def = new PyModuleDef();
         auto *def = new PyModuleDef();
@@ -871,7 +871,7 @@ public:
         m_ptr = Py_InitModule3(name, nullptr, doc);
         m_ptr = Py_InitModule3(name, nullptr, doc);
 #endif
 #endif
         if (m_ptr == nullptr)
         if (m_ptr == nullptr)
-            pybind11_fail("Internal error in module::module()");
+            pybind11_fail("Internal error in module_::module_()");
         inc_ref();
         inc_ref();
     }
     }
 
 
@@ -881,7 +881,7 @@ public:
         details on the ``Extra&& ... extra`` argument, see section :ref:`extras`.
         details on the ``Extra&& ... extra`` argument, see section :ref:`extras`.
     \endrst */
     \endrst */
     template <typename Func, typename... Extra>
     template <typename Func, typename... Extra>
-    module &def(const char *name_, Func &&f, const Extra& ... extra) {
+    module_ &def(const char *name_, Func &&f, const Extra& ... extra) {
         cpp_function func(std::forward<Func>(f), name(name_), scope(*this),
         cpp_function func(std::forward<Func>(f), name(name_), scope(*this),
                           sibling(getattr(*this, name_, none())), extra...);
                           sibling(getattr(*this, name_, none())), extra...);
         // NB: allow overwriting here because cpp_function sets up a chain with the intention of
         // NB: allow overwriting here because cpp_function sets up a chain with the intention of
@@ -900,10 +900,10 @@ public:
             py::module m2 = m.def_submodule("sub", "A submodule of 'example'");
             py::module m2 = m.def_submodule("sub", "A submodule of 'example'");
             py::module m3 = m2.def_submodule("subsub", "A submodule of 'example.sub'");
             py::module m3 = m2.def_submodule("subsub", "A submodule of 'example.sub'");
     \endrst */
     \endrst */
-    module def_submodule(const char *name, const char *doc = nullptr) {
+    module_ def_submodule(const char *name, const char *doc = nullptr) {
         std::string full_name = std::string(PyModule_GetName(m_ptr))
         std::string full_name = std::string(PyModule_GetName(m_ptr))
             + std::string(".") + std::string(name);
             + std::string(".") + std::string(name);
-        auto result = reinterpret_borrow<module>(PyImport_AddModule(full_name.c_str()));
+        auto result = reinterpret_borrow<module_>(PyImport_AddModule(full_name.c_str()));
         if (doc && options::show_user_defined_docstrings())
         if (doc && options::show_user_defined_docstrings())
             result.attr("__doc__") = pybind11::str(doc);
             result.attr("__doc__") = pybind11::str(doc);
         attr(name) = result;
         attr(name) = result;
@@ -911,11 +911,11 @@ public:
     }
     }
 
 
     /// Import and return a module or throws `error_already_set`.
     /// Import and return a module or throws `error_already_set`.
-    static module import(const char *name) {
+    static module_ import(const char *name) {
         PyObject *obj = PyImport_ImportModule(name);
         PyObject *obj = PyImport_ImportModule(name);
         if (!obj)
         if (!obj)
             throw error_already_set();
             throw error_already_set();
-        return reinterpret_steal<module>(obj);
+        return reinterpret_steal<module_>(obj);
     }
     }
 
 
     /// Reload the module or throws `error_already_set`.
     /// Reload the module or throws `error_already_set`.
@@ -923,7 +923,7 @@ public:
         PyObject *obj = PyImport_ReloadModule(ptr());
         PyObject *obj = PyImport_ReloadModule(ptr());
         if (!obj)
         if (!obj)
             throw error_already_set();
             throw error_already_set();
-        *this = reinterpret_steal<module>(obj);
+        *this = reinterpret_steal<module_>(obj);
     }
     }
 
 
     // Adds an object to the module using the given name.  Throws if an object with the given name
     // Adds an object to the module using the given name.  Throws if an object with the given name
@@ -940,6 +940,8 @@ public:
     }
     }
 };
 };
 
 
+using module = module_;
+
 /// \ingroup python_builtins
 /// \ingroup python_builtins
 /// Return a dictionary representing the global variables in the current execution frame,
 /// Return a dictionary representing the global variables in the current execution frame,
 /// or ``__main__.__dict__`` if there is no frame (usually when the interpreter is embedded).
 /// or ``__main__.__dict__`` if there is no frame (usually when the interpreter is embedded).