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.

1 files changed, 11 insertions, 3 deletions

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 @@ always available.
    * *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