bpo-36829: Document test.support.catch_unraisable_exception() (GH-13554)

catch_unraisable_exception() now also removes its 'unraisable'
attribute at the context manager exit.

1 files changed, 20 insertions, 0 deletions

diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index 054521d..b7a2595 100644
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -1081,6 +1081,26 @@ The :mod:`test.support` module defines the following functions:
    :exc:`PermissionError` is raised.
 
 
+.. function:: catch_unraisable_exception()
+
+   Context manager catching unraisable exception using
+   :func:`sys.unraisablehook`.
+
+   Usage::
+
+       with support.catch_unraisable_exception() as cm:
+           # code creating an "unraisable exception"
+           ...
+
+           # check the unraisable exception: use cm.unraisable
+           ...
+
+       # cm.unraisable attribute no longer exists at this point
+       # (to break a reference cycle)
+
+   .. versionadded:: 3.8
+
+
 .. function:: find_unused_port(family=socket.AF_INET, socktype=socket.SOCK_STREAM)
 
    Returns an unused port that should be suitable for binding.  This is