bpo-40275: Adding threading_helper submodule in test.support (GH-20263)

1 files changed, 78 insertions, 67 deletions

diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index f7e6eba..7bee6e8 100644
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -838,18 +838,6 @@ The :mod:`test.support` module defines the following functions:
    .. versionadded:: 3.9
 
 
-.. function:: wait_threads_exit(timeout=60.0)
-
-   Context manager to wait until all threads created in the ``with`` statement
-   exit.
-
-
-.. function:: start_threads(threads, unlock=None)
-
-   Context manager to start *threads*.  It attempts to join the threads upon
-   exit.
-
-
 .. function:: calcobjsize(fmt)
 
    Return :func:`struct.calcsize` for ``nP{fmt}0n`` or, if ``gettotalrefcount``
@@ -988,11 +976,6 @@ The :mod:`test.support` module defines the following functions:
    the trace function.
 
 
-.. decorator:: reap_threads(func)
-
-   Decorator to ensure the threads are cleaned up even if the test fails.
-
-
 .. decorator:: bigmemtest(size, memuse, dry_run=True)
 
    Decorator for bigmem tests.
@@ -1110,23 +1093,6 @@ The :mod:`test.support` module defines the following functions:
    preserve internal cache.
 
 
-.. function:: threading_setup()
-
-   Return current thread count and copy of dangling threads.
-
-
-.. function:: threading_cleanup(*original_values)
-
-   Cleanup up threads not specified in *original_values*.  Designed to emit
-   a warning if a test leaves running threads in the background.
-
-
-.. function:: join_thread(thread, timeout=30.0)
-
-   Join a *thread* within *timeout*.  Raise an :exc:`AssertionError` if thread
-   is still alive after *timeout* seconds.
-
-
 .. function:: reap_children()
 
    Use this at the end of ``test_main`` whenever sub-processes are started.
@@ -1140,39 +1106,6 @@ The :mod:`test.support` module defines the following functions:
    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
@@ -1628,3 +1561,81 @@ The module defines the following class:
 .. method:: BytecodeTestCase.assertNotInBytecode(x, opname, argval=_UNSPECIFIED)
 
    Throws :exc:`AssertionError` if *opname* is found.
+
+
+:mod:`test.support.threading_helper` --- Utilities for threading tests
+======================================================================
+
+.. module:: test.support.threading_helper
+   :synopsis: Support for threading tests.
+
+The :mod:`test.support.threading_helper` module provides support for threading tests.
+
+.. versionadded:: 3.10
+
+
+.. function:: join_thread(thread, timeout=None)
+
+   Join a *thread* within *timeout*.  Raise an :exc:`AssertionError` if thread
+   is still alive after *timeout* seconds.
+
+
+.. decorator:: reap_threads(func)
+
+   Decorator to ensure the threads are cleaned up even if the test fails.
+
+
+.. function:: start_threads(threads, unlock=None)
+
+   Context manager to start *threads*.  It attempts to join the threads upon
+   exit.
+
+
+.. function:: threading_cleanup(*original_values)
+
+   Cleanup up threads not specified in *original_values*.  Designed to emit
+   a warning if a test leaves running threads in the background.
+
+
+.. function:: threading_setup()
+
+   Return current thread count and copy of dangling threads.
+
+
+.. function:: wait_threads_exit(timeout=None)
+
+   Context manager to wait until all threads created in the ``with`` statement
+   exit.
+
+
+.. 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 threading_helper.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