bpo-37526: Add support.catch_threading_exception() (GH-14664)

Context manager catching threading.Thread exception using
threading.excepthook.

3 files changed, 92 insertions, 0 deletions

diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index 920c018084..7d62a94d83 100644
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -1081,6 +1081,39 @@ The :mod:`test.support` module defines the following functions:
    :exc:`PermissionError` is raised.
 
 
+.. function:: catch_threading_exception()
+
+   Context manager catching :class:`threading.Thread` exception using
+   :func:`threading.excepthook`.
+
+   Attributes set when an exception is catched:
+
+   * ``exc_type``
+   * ``exc_value``
+   * ``exc_traceback``
+   * ``thread``
+
+   See :func:`threading.excepthook` documentation.
+
+   These attributes are deleted at the context manager exit.
+
+   Usage::
+
+       with support.catch_threading_exception() as cm:
+           # code spawning a thread which raises an exception
+           ...
+
+           # check the thread exception, use cm attributes:
+           # exc_type, exc_value, exc_traceback, thread
+           ...
+
+       # exc_type, exc_value, exc_traceback, thread attributes of cm no longer
+       # exists at this point
+       # (to avoid reference cycles)
+
+   .. versionadded:: 3.8
+
+
 .. function:: catch_unraisable_exception()
 
    Context manager catching unraisable exception using
diff --git a/Lib/test/support/__init__.py b/Lib/test/support/__init__.py
index 611c1cc977..423bb3ebd8 100644
--- a/Lib/test/support/__init__.py
+++ b/Lib/test/support/__init__.py
@@ -3159,3 +3159,60 @@ class catch_unraisable_exception:
     def __exit__(self, *exc_info):
         sys.unraisablehook = self._old_hook
         del self.unraisable
+
+
+class catch_threading_exception:
+    """
+    Context manager catching threading.Thread exception using
+    threading.excepthook.
+
+    Attributes set when an exception is catched:
+
+    * exc_type
+    * exc_value
+    * exc_traceback
+    * thread
+
+    See threading.excepthook() documentation for these attributes.
+
+    These attributes are deleted at the context manager exit.
+
+    Usage:
+
+        with support.catch_threading_exception() as cm:
+            # code spawning a thread which raises an exception
+            ...
+
+            # check the thread exception, use cm attributes:
+            # exc_type, exc_value, exc_traceback, thread
+            ...
+
+        # exc_type, exc_value, exc_traceback, thread attributes of cm no longer
+        # exists at this point
+        # (to avoid reference cycles)
+    """
+
+    def __init__(self):
+        self.exc_type = None
+        self.exc_value = None
+        self.exc_traceback = None
+        self.thread = None
+        self._old_hook = None
+
+    def _hook(self, args):
+        self.exc_type = args.exc_type
+        self.exc_value = args.exc_value
+        self.exc_traceback = args.exc_traceback
+        self.thread = args.thread
+
+    def __enter__(self):
+        self._old_hook = threading.excepthook
+        threading.excepthook = self._hook
+        return self
+
+    def __exit__(self, *exc_info):
+        threading.excepthook = self._old_hook
+        del self.exc_type
+        del self.exc_value
+        del self.exc_traceback
+        del self.thread
diff --git a/Misc/NEWS.d/next/Tests/2019-07-09-12-33-18.bpo-37526.vmm5y7.rst b/Misc/NEWS.d/next/Tests/2019-07-09-12-33-18.bpo-37526.vmm5y7.rst
new file mode 100644
index 0000000000..aff6b6d1f1
--- /dev/null
+++ b/Misc/NEWS.d/next/Tests/2019-07-09-12-33-18.bpo-37526.vmm5y7.rst
@@ -0,0 +1,2 @@
+Add :func:`test.support.catch_threading_exception`: context manager catching
+:class:`threading.Thread` exception using :func:`threading.excepthook`.