#4614: document PyModule_Create and PyModuleDef struct.

1 files changed, 95 insertions, 1 deletions

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*.
-