https://github.com/python/cpython/commit/6384c7917db03b186fda163d0abef8dbe723f86b commit: 6384c7917db03b186fda163d0abef8dbe723f86b branch: 3.13 author: Petr Viktorin <[email protected]> committer: encukou <[email protected]> date: 2025-11-10T15:06:58+01:00 summary:
[3.13] Clarify argument/result ownership/validity for PyModule_* functions (GH-141159) (GH-141191) (cherry picked from commit ffd64737d00277eea1c4721d278a0951168d07ca) Co-authored-by: Peter Bierma <[email protected]> files: M Doc/c-api/module.rst diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst index 70d0c9298dee34..927fc3afe58a45 100644 --- 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 _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
