From ffd64737d00277eea1c4721d278a0951168d07ca Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Fri, 7 Nov 2025 14:17:47 +0100 Subject: [PATCH 1/4] Clarify argument/result ownership/validity for PyModule_* functions (GH-141159) Co-authored-by: Peter Bierma --- Doc/c-api/module.rst | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst index ed2a7663375920d..1994a3c7d01ca75 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. @@ -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) From 920286d6b296f9971fc79e14ec22966f8f7a7b90 Mon Sep 17 00:00:00 2001 From: "W. H. Wang" Date: Fri, 7 Nov 2025 21:34:49 +0800 Subject: [PATCH 2/4] Update NaNs handling description in `c-api/float.rst` (#141179) Clarified the behavior of NaNs on IEEE platforms regarding signaling and quiet NaNs. --- Doc/c-api/float.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/float.rst b/Doc/c-api/float.rst index 1085c32a5370712..edee498a0b80f39 100644 --- a/Doc/c-api/float.rst +++ b/Doc/c-api/float.rst @@ -113,8 +113,8 @@ NaNs (if such things exist on the platform) isn't handled correctly, and attempting to unpack a bytes string containing an IEEE INF or NaN will raise an exception. -Note that NaNs type may not be preserved on IEEE platforms (silent NaN become -quiet), for example on x86 systems in 32-bit mode. +Note that NaNs type may not be preserved on IEEE platforms (signaling NaN become +quiet NaN), for example on x86 systems in 32-bit mode. On non-IEEE platforms with more precision, or larger dynamic range, than IEEE 754 supports, not all values can be packed; on non-IEEE platforms with less From 7af9b5354dd7633df422b9f720633989b3090199 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Fri, 7 Nov 2025 09:09:38 -0500 Subject: [PATCH 3/4] gh-141004: Document `PyCapsule_Type` (GH-141079) --- Doc/c-api/capsule.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Doc/c-api/capsule.rst b/Doc/c-api/capsule.rst index 6da020efc7f27cd..03a848d68ed7aba 100644 --- a/Doc/c-api/capsule.rst +++ b/Doc/c-api/capsule.rst @@ -22,6 +22,12 @@ Refer to :ref:`using-capsules` for more information on using these objects. loaded modules. +.. c:var:: PyTypeObject PyCapsule_Type + + The type object corresponding to capsule objects. This is the same object + as :class:`types.CapsuleType` in the Python layer. + + .. c:type:: PyCapsule_Destructor The type of a destructor callback for a capsule. Defined as:: From 9420795b47ac88f31315a8d1041e2c66c2cd9a8b Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Fri, 7 Nov 2025 11:19:14 -0500 Subject: [PATCH 4/4] gh-141004: Document `PyErr_WarnExplicitFormat` (GH-141187) --- Doc/c-api/exceptions.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 9c75f66f6831958..b6f9399337eb86c 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -394,6 +394,15 @@ an error value). .. versionadded:: 3.2 +.. c:function:: int PyErr_WarnExplicitFormat(PyObject *category, const char *filename, int lineno, const char *module, PyObject *registry, const char *format, ...) + + Similar to :c:func:`PyErr_WarnExplicit`, but uses + :c:func:`PyUnicode_FromFormat` to format the warning message. *format* is + an ASCII-encoded string. + + .. versionadded:: 3.2 + + .. c:function:: int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...) Function similar to :c:func:`PyErr_WarnFormat`, but *category* is