Function def_submodule

include/pybind11/pybind11.h:1629–1663

\rst Create and return a new Python submodule with the given name and docstring. This also works recursively, i.e. .. code-block:: cpp py::module_ m("example", "pybind11 example plugin"); 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 */
    module_ def_submodule(const char *name, const char *doc = nullptr) {
        const char *this_name = PyModule_GetName(m_ptr);
        if (this_name == nullptr) {
            throw error_already_set();
        }
        std::string full_name = std::string(this_name) + '.' + name;
        handle submodule = PyImport_AddModule(full_name.c_str());
        if (!submodule) {
            throw error_already_set();
        }
        auto result = reinterpret_borrow<module_>(submodule);
        if (doc && options::show_user_defined_docstrings()) {
            result.attr("__doc__") = pybind11::str(doc);
        }

#if defined(GRAALVM_PYTHON) && (!defined(GRAALPY_VERSION_NUM) || GRAALPY_VERSION_NUM < 0x190000)
        // GraalPy doesn't support PyModule_GetFilenameObject,
        // so getting by attribute (see PR #5584)
        handle this_module = m_ptr;
        if (object this_file = getattr(this_module, "__file__", none())) {
            result.attr("__file__") = this_file;
        }
#else
        handle this_file = PyModule_GetFilenameObject(m_ptr);
        if (this_file) {
            result.attr("__file__") = this_file;
        } else if (PyErr_ExceptionMatches(PyExc_SystemError) != 0) {
            PyErr_Clear();
        } else {
            throw error_already_set();
        }
#endif
        attr(name) = result;
        return result;
    }

    /// Import and return a module or throws `error_already_set`.
    static module_ import(const char *name) {