python · vstinner · Jun 9, 2025 · Sep 15, 2021 · Sep 15, 2021 · Apr 3, 2022
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
@@ -686,6 +686,26 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    instance, and call the type's :c:member:`~PyTypeObject.tp_free` function to
    free the object itself.
 
+   If you may call functions that may set the error indicator, you must use
+   :c:func:`PyErr_GetRaisedException` and :c:func:`PyErr_SetRaisedException`
+   to ensure you don't clobber a preexisting error indicator (the deallocation
+   could have occurred while processing a different error):
+
+   .. code-block:: c
+
+     static void
+     foo_dealloc(foo_object *self)
+     {
+         PyObject *et, *ev, *etb;
+         PyObject *exc = PyErr_GetRaisedException();
+         ...
+         PyErr_SetRaisedException(exc);
+     }
+
+   The dealloc handler itself must not raise an exception; if it hits an error
+   case it should call :c:func:`PyErr_FormatUnraisable` to log (and clear) an
+   unraisable exception.
+
    No guarantees are made about when an object is destroyed, except:
 
    * Python will destroy an object immediately or some time after the final

diff --git a/Misc/NEWS.d/next/Documentation/2021-09-15-13-07-25.bpo-45210.RtGk7i.rst b/Misc/NEWS.d/next/Documentation/2021-09-15-13-07-25.bpo-45210.RtGk7i.rst
@@ -0,0 +1,2 @@
+Document that error indicator may be set in tp_dealloc, and how to avoid
+clobbering it.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		Document that error indicator may be set in tp_dealloc, and how to avoid
		clobbering it.