[3.13] Clarify argument/result ownership/validity for PyModule_* functions (GH-141159...

(cherry picked from commit ffd64737d00277eea1c4721d278a0951168d07ca)

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

diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
index 70d0c9298dee34d2284017b4563f33959648379f..927fc3afe58a458264d3efca7402fa900ba595e5 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.
@@ -528,6 +538,9 @@ objects dynamically. Note that both ``PyModule_FromDefAndSpec`` and
    ``PyModuleDef``, using either ``PyModule_Create`` or
    ``PyModule_FromDefAndSpec``.
 
+   The *functions* array must be statically allocated (or otherwise guaranteed
+   to outlive the module object).
+
    .. versionadded:: 3.5
 
 Support functions