From af68b2e60d5a3d5106a4791b10ce2aa08c034187 Mon Sep 17 00:00:00 2001 From: Ilya Bazhenov <31971067+bazhil@users.noreply.github.com> Date: Thu, 1 Oct 2026 22:09:19 +0300 Subject: [PATCH 1/6] Document that regrtest loads tests with unittest and rejects test_main(). --- Doc/library/test.rst | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/Doc/library/test.rst b/Doc/library/test.rst index 765811eba32fd40..c0b8bfd428a6805 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -165,11 +165,16 @@ test suite, thanks to the :option:`-m` option: :program:`python -m test`. Under the hood, it uses :mod:`!test.regrtest`; the call :program:`python -m test.regrtest` used in previous Python versions still works. Running the script by itself automatically starts running all regression tests in the -:mod:`!test` package. It does this by finding all modules in the package whose -name starts with ``test_``, importing them, and executing the function -:func:`test_main` if present or loading the tests via -unittest.TestLoader.loadTestsFromModule if ``test_main`` does not exist. The -names of tests to execute may also be passed to the script. Specifying a single +:mod:`!test` package. It does this by finding modules and packages whose names +start with ``test_``, importing each one, and loading its tests with +:meth:`unittest.TestLoader.loadTestsFromModule`. The loader collects +:class:`unittest.TestCase` tests defined in the module. If the module defines +``load_tests``, the loader calls it with that suite and runs the suite the +function returns. Test packages use ``load_tests``, often via +:func:`test.support.load_package_tests`, to add tests discovered in +submodules. A module-level ``test_main()`` function is not called. If a test +module defines ``test_main``, :mod:`!test.regrtest` fails that test. The names of +tests to execute may also be passed to the script. Specifying a single regression test (:program:`python -m test test_spam`) will minimize output and only print whether the test passed or failed. @@ -882,9 +887,11 @@ The :mod:`!test.support` module defines the following functions: .. function:: reap_children() - Use this at the end of ``test_main`` whenever sub-processes are started. - This will help ensure that no extra children (zombies) stick around to - hog resources and create problems when looking for refleaks. + Call this from a test's :meth:`~unittest.TestCase.setUp`, + :meth:`~unittest.TestCase.tearDown`, or from ``tearDownModule`` when the + test starts subprocesses. This will help ensure that no extra children + (zombies) stick around to hog resources and create problems when looking + for refleaks. .. function:: get_attribute(obj, name) From 9890bcb1445260c2ab1862f4727774cf2de855da Mon Sep 17 00:00:00 2001 From: Ilya Bazhenov <31971067+bazhil@users.noreply.github.com> Date: Thu, 1 Oct 2026 22:22:53 +0300 Subject: [PATCH 2/6] Align reap_children() docstring with the regrtest documentation. --- Lib/test/support/__init__.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Lib/test/support/__init__.py b/Lib/test/support/__init__.py index f348c9a5bbb31cb..96f2e0916f715c2 100644 --- a/Lib/test/support/__init__.py +++ b/Lib/test/support/__init__.py @@ -1595,10 +1595,10 @@ def set_environment_altered(reason): def reap_children(): - """Use this function at the end of test_main() whenever sub-processes - are started. This will help ensure that no extra children (zombies) - stick around to hog resources and create problems when looking - for refleaks. + """Call this from a test's setUp(), tearDown(), or tearDownModule() + when the test starts subprocesses. This will help ensure that no extra + children (zombies) stick around to hog resources and create problems when + looking for refleaks. """ # Need os.waitpid(-1, os.WNOHANG): Windows is not supported if not (hasattr(os, 'waitpid') and hasattr(os, 'WNOHANG')): From 787c24004446a05c78a241bd68dfa5d2bfe883e1 Mon Sep 17 00:00:00 2001 From: "blurb-it[bot]" <43283697+blurb-it[bot]@users.noreply.github.com> Date: Sat, 3 Oct 2026 21:19:15 +0000 Subject: [PATCH 3/6] =?UTF-8?q?=F0=9F=93=9C=F0=9F=A4=96=20Added=20by=20blu?= =?UTF-8?q?rb=5Fit.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst diff --git a/Misc/NEWS.d/next/Documentation/2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst b/Misc/NEWS.d/next/Documentation/2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst new file mode 100644 index 000000000000000..19b4b6a997e60ee --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst @@ -0,0 +1,5 @@ +`Doc/library/test.rst` said that `python -m test` calls a module-level `test_main()` when it exists, and otherwise loads tests with `unittest.TestLoader.loadTestsFromModule`. It also told readers to call `test.support.reap_children()` at the end of `test_main`. The docstring of `reap_children()` said the same thing. + +`libregrtest` does not call `test_main()`. If the imported module defines it, `Lib/test/libregrtest/single.py` raises `Exception`. regrtest reports the module as failed with an uncaught exception (stderr: `test crashed`; summary: `failed (uncaught exception)`). Tests are loaded with `loadTestsFromModule`, which collects `TestCase` classes and, when the module defines `load_tests`, runs the suite that function returns. Packages use `load_tests`, usually via `test.support.load_package_tests`, to add tests from submodules. `reap_children()` is called from `setUp()`, `tearDown()`, and `tearDownModule()`. + +The runner is unchanged. This updates the library page and the `reap_children()` docstring. From 9290defff03b3ac48f24754233f9aaf411e3dd44 Mon Sep 17 00:00:00 2001 From: Ilya Bazhenov <31971067+bazhil@users.noreply.github.com> Date: Sun, 4 Oct 2026 18:37:46 +0300 Subject: [PATCH 4/6] Delete Misc/NEWS.d/next/Documentation/2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst --- .../2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst | 5 ----- 1 file changed, 5 deletions(-) delete mode 100644 Misc/NEWS.d/next/Documentation/2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst diff --git a/Misc/NEWS.d/next/Documentation/2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst b/Misc/NEWS.d/next/Documentation/2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst deleted file mode 100644 index 19b4b6a997e60ee..000000000000000 --- a/Misc/NEWS.d/next/Documentation/2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst +++ /dev/null @@ -1,5 +0,0 @@ -`Doc/library/test.rst` said that `python -m test` calls a module-level `test_main()` when it exists, and otherwise loads tests with `unittest.TestLoader.loadTestsFromModule`. It also told readers to call `test.support.reap_children()` at the end of `test_main`. The docstring of `reap_children()` said the same thing. - -`libregrtest` does not call `test_main()`. If the imported module defines it, `Lib/test/libregrtest/single.py` raises `Exception`. regrtest reports the module as failed with an uncaught exception (stderr: `test crashed`; summary: `failed (uncaught exception)`). Tests are loaded with `loadTestsFromModule`, which collects `TestCase` classes and, when the module defines `load_tests`, runs the suite that function returns. Packages use `load_tests`, usually via `test.support.load_package_tests`, to add tests from submodules. `reap_children()` is called from `setUp()`, `tearDown()`, and `tearDownModule()`. - -The runner is unchanged. This updates the library page and the `reap_children()` docstring. From aabe5eadaa7b0b056ee1dc902c1db32c49d89008 Mon Sep 17 00:00:00 2001 From: Ilya Bazhenov <31971067+bazhil@users.noreply.github.com> Date: Thu, 8 Oct 2026 00:34:16 +0300 Subject: [PATCH 5/6] Shorten the regrtest loading description and fix the reap_children wording. --- Doc/library/test.rst | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/Doc/library/test.rst b/Doc/library/test.rst index c0b8bfd428a6805..708d690124a0d83 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -167,13 +167,11 @@ test.regrtest` used in previous Python versions still works. Running the script by itself automatically starts running all regression tests in the :mod:`!test` package. It does this by finding modules and packages whose names start with ``test_``, importing each one, and loading its tests with -:meth:`unittest.TestLoader.loadTestsFromModule`. The loader collects -:class:`unittest.TestCase` tests defined in the module. If the module defines -``load_tests``, the loader calls it with that suite and runs the suite the -function returns. Test packages use ``load_tests``, often via -:func:`test.support.load_package_tests`, to add tests discovered in -submodules. A module-level ``test_main()`` function is not called. If a test -module defines ``test_main``, :mod:`!test.regrtest` fails that test. The names of +:meth:`unittest.TestLoader.loadTestsFromModule`. See the +:ref:`load_tests protocol ` for how a module or package +can customize what is loaded. A module-level ``test_main()`` function is not +called. If a test module defines ``test_main``, :mod:`!test.regrtest` fails +that test. The names of tests to execute may also be passed to the script. Specifying a single regression test (:program:`python -m test test_spam`) will minimize output and only print whether the test passed or failed. @@ -888,7 +886,7 @@ The :mod:`!test.support` module defines the following functions: .. function:: reap_children() Call this from a test's :meth:`~unittest.TestCase.setUp`, - :meth:`~unittest.TestCase.tearDown`, or from ``tearDownModule`` when the + :meth:`~unittest.TestCase.tearDown`, or ``tearDownModule`` when the test starts subprocesses. This will help ensure that no extra children (zombies) stick around to hog resources and create problems when looking for refleaks. From c19d22f73a356d59a5c9f9c02a43f04761089aa3 Mon Sep 17 00:00:00 2001 From: Ilya Bazhenov <31971067+bazhil@users.noreply.github.com> Date: Mon, 12 Oct 2026 09:44:58 +0300 Subject: [PATCH 6/6] Apply review wording for test_main and reap_children. --- Doc/library/test.rst | 13 ++++++------- Lib/test/support/__init__.py | 6 +++--- 2 files changed, 9 insertions(+), 10 deletions(-) diff --git a/Doc/library/test.rst b/Doc/library/test.rst index 708d690124a0d83..b4809fdd66c1834 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -169,10 +169,9 @@ script by itself automatically starts running all regression tests in the start with ``test_``, importing each one, and loading its tests with :meth:`unittest.TestLoader.loadTestsFromModule`. See the :ref:`load_tests protocol ` for how a module or package -can customize what is loaded. A module-level ``test_main()`` function is not -called. If a test module defines ``test_main``, :mod:`!test.regrtest` fails -that test. The names of -tests to execute may also be passed to the script. Specifying a single +can customize what is loaded. Defining a module-level ``test_main()`` function +is not supported and causes the test to fail. The names of tests to +execute may also be passed to the script. Specifying a single regression test (:program:`python -m test test_spam`) will minimize output and only print whether the test passed or failed. @@ -885,9 +884,9 @@ The :mod:`!test.support` module defines the following functions: .. function:: reap_children() - Call this from a test's :meth:`~unittest.TestCase.setUp`, - :meth:`~unittest.TestCase.tearDown`, or ``tearDownModule`` when the - test starts subprocesses. This will help ensure that no extra children + Call this from :meth:`~unittest.TestCase.setUp`, + :meth:`~unittest.TestCase.tearDown`, or ``tearDownModule()`` in tests + that start subprocesses. This will help ensure that no extra children (zombies) stick around to hog resources and create problems when looking for refleaks. diff --git a/Lib/test/support/__init__.py b/Lib/test/support/__init__.py index 49949b79af1d766..1d08b3e127d24fd 100644 --- a/Lib/test/support/__init__.py +++ b/Lib/test/support/__init__.py @@ -1595,9 +1595,9 @@ def set_environment_altered(reason): def reap_children(): - """Call this from a test's setUp(), tearDown(), or tearDownModule() - when the test starts subprocesses. This will help ensure that no extra - children (zombies) stick around to hog resources and create problems when + """Call this from setUp(), tearDown(), or tearDownModule() in tests + that start subprocesses. This will help ensure that no extra children + (zombies) stick around to hog resources and create problems when looking for refleaks. """ # Need os.waitpid(-1, os.WNOHANG): Windows is not supported