bpo-37261: Document sys.unraisablehook corner cases (GH-14059)
Document reference cycle and resurrected objects issues in
sys.unraisablehook() and threading.excepthook() documentation.
Fix test.support.catch_unraisable_exception(): __exit__() no longer
ignores unraisable exceptions.
Fix test_io test_writer_close_error_on_close(): use a second
catch_unraisable_exception() to catch the BufferedWriter unraisable
exception.
(cherry picked from commit 212646cae6b7c4ddc8d98c8b9b6d39a5f259e864)
Co-authored-by: Victor Stinner <vstinner@redhat.com>
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 5bde687..817c3f1 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -1514,13 +1514,21 @@
* *err_msg*: Error message, can be ``None``.
* *object*: Object causing the exception, can be ``None``.
- :func:`sys.unraisablehook` can be overridden to control how unraisable
- exceptions are handled.
-
The default hook formats *err_msg* and *object* as:
``f'{err_msg}: {object!r}'``; use "Exception ignored in" error message
if *err_msg* is ``None``.
+ :func:`sys.unraisablehook` can be overridden to control how unraisable
+ exceptions are handled.
+
+ Storing *exc_value* using a custom hook can create a reference cycle. It
+ should be cleared explicitly to break the reference cycle when the
+ exception is no longer needed.
+
+ Storing *object* using a custom hook can resurrect it if it is set to an
+ object which is being finalized. Avoid storing *object* after the custom
+ hook completes to avoid resurrecting objects.
+
See also :func:`excepthook` which handles uncaught exceptions.
.. versionadded:: 3.8