bpo-45162: Revert "Remove many old deprecated unittest features" (GH-30935)

Revert "bpo-45162: Remove many old deprecated unittest features (GH-28268)"

This reverts commit b0a6ede3d0bd6fa4ffe413ab4dfc1059201df25b.

We're deferring this change until 3.12 while upstream projects that use
the legacy assertion method names are fixed.  See the issue for links
to the discussion. Many upstream projects now have issues and PRs
filed.

1 files changed, 48 insertions, 7 deletions

diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
index b5a5331..06df8ce 100644
--- a/Doc/library/unittest.rst
+++ b/Doc/library/unittest.rst
@@ -1255,6 +1255,9 @@ Test cases
          :meth:`.assertRegex`.
       .. versionadded:: 3.2
          :meth:`.assertNotRegex`.
+      .. versionadded:: 3.5
+         The name ``assertNotRegexpMatches`` is a deprecated alias
+         for :meth:`.assertNotRegex`.
 
 
    .. method:: assertCountEqual(first, second, msg=None)
@@ -1620,6 +1623,40 @@ Test cases
    :mod:`unittest`-based test framework.
 
 
+.. _deprecated-aliases:
+
+Deprecated aliases
+##################
+
+For historical reasons, some of the :class:`TestCase` methods had one or more
+aliases that are now deprecated.  The following table lists the correct names
+along with their deprecated aliases:
+
+   ==============================  ====================== =======================
+    Method Name                     Deprecated alias       Deprecated alias
+   ==============================  ====================== =======================
+    :meth:`.assertEqual`            failUnlessEqual        assertEquals
+    :meth:`.assertNotEqual`         failIfEqual            assertNotEquals
+    :meth:`.assertTrue`             failUnless             assert\_
+    :meth:`.assertFalse`            failIf
+    :meth:`.assertRaises`           failUnlessRaises
+    :meth:`.assertAlmostEqual`      failUnlessAlmostEqual  assertAlmostEquals
+    :meth:`.assertNotAlmostEqual`   failIfAlmostEqual      assertNotAlmostEquals
+    :meth:`.assertRegex`                                   assertRegexpMatches
+    :meth:`.assertNotRegex`                                assertNotRegexpMatches
+    :meth:`.assertRaisesRegex`                             assertRaisesRegexp
+   ==============================  ====================== =======================
+
+   .. deprecated:: 3.1
+         The fail* aliases listed in the second column have been deprecated.
+   .. deprecated:: 3.2
+         The assert* aliases listed in the third column have been deprecated.
+   .. deprecated:: 3.2
+         ``assertRegexpMatches`` and ``assertRaisesRegexp`` have been renamed to
+         :meth:`.assertRegex` and :meth:`.assertRaisesRegex`.
+   .. deprecated:: 3.5
+         The ``assertNotRegexpMatches`` name is deprecated in favor of :meth:`.assertNotRegex`.
+
 .. _testsuite-objects:
 
 Grouping tests
@@ -1745,7 +1782,7 @@ Loading and running tests
       case is created for that method instead.
 
 
-   .. method:: loadTestsFromModule(module, *, pattern=None)
+   .. method:: loadTestsFromModule(module, pattern=None)
 
       Return a suite of all test cases contained in the given module. This
       method searches *module* for classes derived from :class:`TestCase` and
@@ -1769,11 +1806,10 @@ Loading and running tests
          Support for ``load_tests`` added.
 
       .. versionchanged:: 3.5
-         Support for a keyword-only argument *pattern* has been added.
-
-      .. versionchanged:: 3.11
-         The undocumented and unofficial *use_load_tests* parameter has been
-         removed.
+         The undocumented and unofficial *use_load_tests* default argument is
+         deprecated and ignored, although it is still accepted for backward
+         compatibility.  The method also now accepts a keyword-only argument
+         *pattern* which is passed to ``load_tests`` as the third argument.
 
 
    .. method:: loadTestsFromName(name, module=None)
@@ -2130,6 +2166,8 @@ Loading and running tests
    :class:`TextTestRunner`.
 
    .. versionadded:: 3.2
+      This class was previously named ``_TextTestResult``. The old name still
+      exists as an alias but is deprecated.
 
 
 .. data:: defaultTestLoader
@@ -2152,7 +2190,10 @@ Loading and running tests
    By default this runner shows :exc:`DeprecationWarning`,
    :exc:`PendingDeprecationWarning`, :exc:`ResourceWarning` and
    :exc:`ImportWarning` even if they are :ref:`ignored by default
-   <warning-ignored>`.  This behavior can
+   <warning-ignored>`. Deprecation warnings caused by :ref:`deprecated unittest
+   methods <deprecated-aliases>` are also special-cased and, when the warning
+   filters are ``'default'`` or ``'always'``, they will appear only once
+   per-module, in order to avoid too many warning messages.  This behavior can
    be overridden using Python's :option:`!-Wd` or :option:`!-Wa` options
    (see :ref:`Warning control <using-on-warnings>`) and leaving
    *warnings* to ``None``.