Clarify argument/result ownership/validity for PyModule_* functions (GH-141159)

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
index ed2a7663375920d88ba07f760601659485ee7436..1994a3c7d01ca75da67f4a918cfd22da94cbd98a 100644 (file)
--- a/Doc/c-api/module.rst
+++ b/Doc/c-api/module.rst
@@ -13,7 +13,7 @@ Module Objects
    .. index:: single: ModuleType (in module types)
 
    This instance of :c:type:`PyTypeObject` represents the Python module type.  This
-   is exposed to Python programs as ``types.ModuleType``.
+   is exposed to Python programs as :py:class:`types.ModuleType`.
 
 
 .. c:function:: int PyModule_Check(PyObject *p)
@@ -71,6 +71,9 @@ Module Objects
    ``PyObject_*`` functions rather than directly manipulate a module's
    :attr:`~object.__dict__`.
 
+   The returned reference is borrowed from the module; it is valid until
+   the module is destroyed.
+
 
 .. c:function:: PyObject* PyModule_GetNameObject(PyObject *module)
 
@@ -90,6 +93,10 @@ Module Objects
    Similar to :c:func:`PyModule_GetNameObject` but return the name encoded to
    ``'utf-8'``.
 
+   The returned buffer is only valid until the module is renamed or destroyed.
+   Note that Python code may rename a module by setting its :py:attr:`~module.__name__`
+   attribute.
+
 .. c:function:: void* PyModule_GetState(PyObject *module)
 
    Return the "state" of the module, that is, a pointer to the block of memory
@@ -126,6 +133,9 @@ Module Objects
    Similar to :c:func:`PyModule_GetFilenameObject` but return the filename
    encoded to 'utf-8'.
 
+   The returned buffer is only valid until the module's :py:attr:`~module.__file__` attribute
+   is reassigned or the module is destroyed.
+
    .. deprecated:: 3.2
       :c:func:`PyModule_GetFilename` raises :exc:`UnicodeEncodeError` on
       unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead.
@@ -671,6 +681,9 @@ or code that creates modules dynamically.
    :c:type:`PyMethodDef` arrays; in that case they should call this function
    directly.
 
+   The *functions* array must be statically allocated (or otherwise guaranteed
+   to outlive the module object).
+
    .. versionadded:: 3.5
 
 .. c:function:: int PyModule_SetDocString(PyObject *module, const char *docstring)