#4614: document PyModule_Create and PyModuleDef struct.

2 files changed, 102 insertions, 33 deletions

diff --git a/Doc/c-api/allocation.rst b/Doc/c-api/allocation.rst
index cb78e79..60d7b44 100644
--- a/Doc/c-api/allocation.rst
+++ b/Doc/c-api/allocation.rst
@@ -54,40 +54,15 @@ Allocating Objects on the Heap
    accessed after this call as the memory is no longer a valid Python object.
 
 
-.. cfunction:: PyObject* Py_InitModule(char *name, PyMethodDef *methods)
-
-   Create a new module object based on a name and table of functions, returning
-   the new module object; the *methods* argument can be *NULL* if no methods are
-   to be defined for the module.
-
-
-.. cfunction:: PyObject* Py_InitModule3(char *name, PyMethodDef *methods, char *doc)
-
-   Create a new module object based on a name and table of functions, returning
-   the new module object.  The *methods* argument can be *NULL* if no methods
-   are to be defined for the module.  If *doc* is non-*NULL*, it will be used to
-   define the docstring for the module.
-
-
-.. cfunction:: PyObject* Py_InitModule4(char *name, PyMethodDef *methods, char *doc, PyObject *self, int apiver)
-
-   Create a new module object based on a name and table of functions, returning
-   the new module object.  The *methods* argument can be *NULL* if no methods
-   are to be defined for the module.  If *doc* is non-*NULL*, it will be used to
-   define the docstring for the module.  If *self* is non-*NULL*, it will passed
-   to the functions of the module as their (otherwise *NULL*) first parameter.
-   (This was added as an experimental feature, and there are no known uses in
-   the current version of Python.)  For *apiver*, the only value which should be
-   passed is defined by the constant :const:`PYTHON_API_VERSION`.
-
-   .. note::
-
-      Most uses of this function should probably be using the :cfunc:`Py_InitModule3`
-      instead; only use this if you are sure you need it.
-
-
 .. cvar:: PyObject _Py_NoneStruct
 
    Object which is visible in Python as ``None``.  This should only be accessed
    using the :cmacro:`Py_None` macro, which evaluates to a pointer to this
    object.
+
+
+.. seealso::
+
+   :cfunc:`PyModule_Create`
+      To allocate and create extension modules.
+
diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
index 3a612e0..2c7faf0 100644
--- a/Doc/c-api/module.rst
+++ b/Doc/c-api/module.rst
@@ -73,6 +73,101 @@ There are only a few functions special to module objects.
    raise :exc:`SystemError` and return *NULL*.
 
 
+.. cfunction:: void* PyModule_GetState(PyObject *module)
+
+   Return the "state" of the module, that is, a pointer to the block of memory
+   allocated at module creation time, or *NULL*.  See
+   :cmember:`PyModuleDef.m_size`.
+
+
+.. cfunction:: PyModuleDef* PyModule_GetDef(PyObject *module)
+
+   Return a pointer to the :ctype:`PyModuleDef` struct from which the module was
+   created, or *NULL* if the module wasn't created with
+   :cfunc:`PyModule_Create`.
+
+
+Initializing C modules
+^^^^^^^^^^^^^^^^^^^^^^
+
+These functions are usually used in the module initialization function.
+
+.. cfunction:: PyObject* PyModule_Create(PyModuleDef *module)
+
+   Create a new module object, given the definition in *module*.  This behaves
+   like :cfunc:`PyModule_Create2` with *module_api_version* set to
+   :const:`PYTHON_API_VERSION`.
+
+
+.. cfunction:: PyObject* PyModule_Create2(PyModuleDef *module, int module_api_version)
+
+   Create a new module object, given the definition in *module*, assuming the
+   API version *module_api_version*.  If that version does not match the version
+   of the running interpreter, a :exc:`RuntimeWarning` is emitted.
+
+   .. note::
+
+      Most uses of this function should be using :cfunc:`PyModule_Create`
+      instead; only use this if you are sure you need it.
+
+
+.. ctype:: PyModuleDef
+
+   This struct holds all information that is needed to create a module object.
+   There is usually only one static variable of that type for each module, which
+   is statically initialized and then passed to :cfunc:`PyModule_Create` in the
+   module initialization function.
+
+   .. cmember:: PyModuleDef_Base m_base
+
+      Always initialize this member to :const:`PyModuleDef_HEAD_INIT`.
+
+   .. cmember:: char* m_name
+
+      Name for the new module.
+
+   .. cmember:: char* m_doc
+
+      Docstring for the module; usually a docstring variable created with
+      :cfunc:`PyDoc_STRVAR` is used.
+
+   .. cmember:: Py_ssize_t m_size
+
+      If the module object needs additional memory, this should be set to the
+      number of bytes to allocate; a pointer to the block of memory can be
+      retrieved with :cfunc:`PyModule_GetState`.  If no memory is needed, set
+      this to ``-1``.
+
+      This memory should be used, rather than static globals, to hold per-module
+      state, since it is then safe for use in multiple sub-interpreters.  It is
+      freed when the module object is deallocated, after the :cmember:`m_free`
+      function has been called, if present.
+
+   .. cmember:: PyMethodDef* m_methods
+
+      A pointer to a table of module-level functions, described by
+      :ctype:`PyMethodDef` values.  Can be *NULL* if no functions are present.
+
+   .. cmember:: inquiry m_reload
+
+      Currently unused, should be *NULL*.
+
+   .. cmember:: traverseproc m_traverse
+
+      A traversal function to call during GC traversal of the module object, or
+      *NULL* if not needed.
+
+   .. cmember:: inquiry m_clear
+
+      A clear function to call during GC clearing of the module object, or
+      *NULL* if not needed.
+
+   .. cmember:: freefunc m_free
+
+      A function to call during deallocation of the module object, or *NULL* if
+      not needed.
+
+
 .. cfunction:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
 
    Add an object to *module* as *name*.  This is a convenience function which can
@@ -105,4 +200,3 @@ There are only a few functions special to module objects.
 .. cfunction:: int PyModule_AddStringMacro(PyObject *module, macro)
 
    Add a string constant to *module*.
-