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

Author: shihai1991

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

Lib/test/_test_multiprocessing.py

@@ -27,6 +27,7 @@
 import test.support.script_helper
 from test import support
 from test.support import socket_helper
+from test.support import threading_helper
 
 
 # Skip tests if _multiprocessing wasn't built.
@@ -81,7 +82,7 @@ def close_queue(queue):
 def join_process(process):
     # Since multiprocessing.Process has the same API than threading.Thread
     # (join() and is_alive(), the support function can be reused
-    support.join_thread(process)
+    threading_helper.join_thread(process)
 
 
 if os.name == "posix":
@@ -4234,7 +4235,7 @@ def make_finalizers():
             gc.set_threshold(5, 5, 5)
             threads = [threading.Thread(target=run_finalizers),
                        threading.Thread(target=make_finalizers)]
-            with test.support.start_threads(threads):
+            with threading_helper.start_threads(threads):
                 time.sleep(4.0)  # Wait a bit to trigger race condition
                 finish = True
             if exc is not None:

Lib/test/fork_wait.py

@@ -12,6 +12,7 @@
 import os, sys, time, unittest
 import threading
 from test import support
+from test.support import threading_helper
 
 
 LONGSLEEP = 2
@@ -21,7 +22,7 @@
 class ForkWait(unittest.TestCase):
 
     def setUp(self):
-        self._threading_key = support.threading_setup()
+        self._threading_key = threading_helper.threading_setup()
         self.alive = {}
         self.stop = 0
         self.threads = []
@@ -33,7 +34,7 @@ def tearDown(self):
             thread.join()
         thread = None
         self.threads.clear()
-        support.threading_cleanup(*self._threading_key)
+        threading_helper.threading_cleanup(*self._threading_key)
 
     def f(self, id):
         while not self.stop:

Lib/test/lock_tests.py

@@ -11,6 +11,7 @@
 import weakref
 
 from test import support
+from test.support import threading_helper
 
 
 requires_fork = unittest.skipUnless(hasattr(os, 'fork'),
@@ -37,7 +38,7 @@ def __init__(self, f, n, wait_before_exit=False):
         self.started = []
         self.finished = []
         self._can_exit = not wait_before_exit
-        self.wait_thread = support.wait_threads_exit()
+        self.wait_thread = threading_helper.wait_threads_exit()
         self.wait_thread.__enter__()
 
         def task():
@@ -73,10 +74,10 @@ def do_finish(self):
 
 class BaseTestCase(unittest.TestCase):
     def setUp(self):
-        self._threads = support.threading_setup()
+        self._threads = threading_helper.threading_setup()
 
     def tearDown(self):
-        support.threading_cleanup(*self._threads)
+        threading_helper.threading_cleanup(*self._threads)
         support.reap_children()
 
     def assertTimeout(self, actual, expected):
@@ -239,7 +240,7 @@ def f():
             lock.acquire()
             phase.append(None)
 
-        with support.wait_threads_exit():
+        with threading_helper.wait_threads_exit():
             start_new_thread(f, ())
             while len(phase) == 0:
                 _wait()

Lib/test/pickletester.py

@@ -29,8 +29,9 @@
 from test import support
 from test.support import (
     TestFailed, TESTFN, run_with_locale, no_tracing,
-    _2G, _4G, bigmemtest, reap_threads, forget,
+    _2G, _4G, bigmemtest, forget,
     )
+from test.support import threading_helper
 
 from pickle import bytes_types
 
@@ -1350,7 +1351,7 @@ def test_truncated_data(self):
         for p in badpickles:
             self.check_unpickling_error(self.truncated_errors, p)
 
-    @reap_threads
+    @threading_helper.reap_threads
     def test_unpickle_module_race(self):
         # https://bugs.python.org/issue34572
         locker_module = dedent("""