#9424: add a DeprecationWarning for assertEquals, assertNotEquals, assertAlmostEquals, assertNotAlmostEquals, and assert_

5 files changed, 62 insertions, 50 deletions

diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
index 640ed4b..91fede0 100644
--- a/Doc/library/unittest.rst
+++ b/Doc/library/unittest.rst
@@ -1401,6 +1401,8 @@ Test cases
    :mod:`unittest`-based test framework.
 
 
+.. _deprecated-aliases:
+
 Deprecated aliases
 ##################
 
@@ -1408,20 +1410,22 @@ 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(es)
-   ==============================  ===============================
-    :meth:`.assertEqual`            failUnlessEqual, assertEquals
-    :meth:`.assertNotEqual`         failIfEqual
-    :meth:`.assertTrue`             failUnless, assert\_
+   ==============================  ====================== ======================
+    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
-    :meth:`.assertNotAlmostEqual`   failIfAlmostEqual
-   ==============================  ===============================
-
-   .. deprecated:: 3.1
-         the aliases listed in the second column
+    :meth:`.assertAlmostEqual`      failUnlessAlmostEqual  assertAlmostEquals
+    :meth:`.assertNotAlmostEqual`   failIfAlmostEqual      assertNotAlmostEquals
+   ==============================  ====================== ======================
+
+   .. deprecated-removed:: 3.1 3.3
+         the fail* aliases listed in the second column.
+   .. deprecated:: 3.2
+         the assert* aliases listed in the third column.
 
 
 
diff --git a/Doc/whatsnew/3.2.rst b/Doc/whatsnew/3.2.rst
index dd47129..c4b5125 100644
--- a/Doc/whatsnew/3.2.rst
+++ b/Doc/whatsnew/3.2.rst
@@ -506,6 +506,18 @@ New, Improved, and Deprecated Modules
       with self.assertWarns(DeprecationWarning):
           legacy_function('XYZ')
 
+* The following :class:`unittest.TestCase` methods are now deprecated:
+   * :meth:`assert_` (use :meth:`.assertTrue` instead);
+   * :meth:`assertEquals` (use :meth:`.assertEqual` instead);
+   * :meth:`assertNotEquals` (use :meth:`.assertNotEqual` instead);
+   * :meth:`assertAlmostEquals` (use :meth:`.assertAlmostEqual` instead);
+   * :meth:`assertNotAlmostEquals` (use :meth:`.assertNotAlmostEqual` instead);
+
+  The ``TestCase.fail*`` methods deprecated in Python 3.1 will be removed in
+  Python 3.3. See also the :ref:`deprecated-aliases` section in the
+  :mod:`unittest` documentation.
+
+  (Contributed by Ezio Melotti; :issue:`9424`.)
 
 * The previously deprecated :func:`string.maketrans` function has been removed
   in favor of the static methods, :meth:`bytes.maketrans` and
diff --git a/Lib/unittest/case.py b/Lib/unittest/case.py
index 68f6715..dbf7aa2 100644
--- a/Lib/unittest/case.py
+++ b/Lib/unittest/case.py
@@ -687,19 +687,7 @@ class TestCase(object):
         msg = self._formatMessage(msg, standardMsg)
         raise self.failureException(msg)
 
-    # Synonyms for assertion methods
-
-    # The plurals are undocumented.  Keep them that way to discourage use.
-    # Do not add more.  Do not remove.
-    # Going through a deprecation cycle on these would annoy many people.
-    assertEquals = assertEqual
-    assertNotEquals = assertNotEqual
-    assertAlmostEquals = assertAlmostEqual
-    assertNotAlmostEquals = assertNotAlmostEqual
-    assert_ = assertTrue
-
-    # These fail* assertion method names are pending deprecation and will
-    # be a DeprecationWarning in 3.2; http://bugs.python.org/issue2578
+
     def _deprecate(original_func):
         def deprecated_func(*args, **kwargs):
             warnings.warn(
@@ -708,11 +696,13 @@ class TestCase(object):
             return original_func(*args, **kwargs)
         return deprecated_func
 
-    failUnlessEqual = _deprecate(assertEqual)
-    failIfEqual = _deprecate(assertNotEqual)
-    failUnlessAlmostEqual = _deprecate(assertAlmostEqual)
-    failIfAlmostEqual = _deprecate(assertNotAlmostEqual)
-    failUnless = _deprecate(assertTrue)
+    # The fail* methods can be removed in 3.3, the 5 assert* methods will
+    # have to stay around for a few more versions.  See #9424.
+    failUnlessEqual = assertEquals = _deprecate(assertEqual)
+    failIfEqual = assertNotEquals = _deprecate(assertNotEqual)
+    failUnlessAlmostEqual = assertAlmostEquals = _deprecate(assertAlmostEqual)
+    failIfAlmostEqual = assertNotAlmostEquals = _deprecate(assertNotAlmostEqual)
+    failUnless = assert_ = _deprecate(assertTrue)
     failUnlessRaises = _deprecate(assertRaises)
     failIf = _deprecate(assertFalse)
 
diff --git a/Lib/unittest/test/test_case.py b/Lib/unittest/test/test_case.py
index 18c74e9..07904d4 100644
--- a/Lib/unittest/test/test_case.py
+++ b/Lib/unittest/test/test_case.py
@@ -1052,39 +1052,43 @@ test case
                 with self.assertWarnsRegexp(RuntimeWarning, "o+"):
                     _runtime_warn("barz")
 
-    def testSynonymAssertMethodNames(self):
-        """Test undocumented method name synonyms.
+    def testDeprecatedMethodNames(self):
+        """Test that the deprecated methods raise a DeprecationWarning.
 
-        Please do not use these methods names in your own code.
-
-        This test confirms their continued existence and functionality
-        in order to avoid breaking existing code.
-        """
-        self.assertNotEquals(3, 5)
-        self.assertEquals(3, 3)
-        self.assertAlmostEquals(2.0, 2.0)
-        self.assertNotAlmostEquals(3.0, 5.0)
-        self.assert_(True)
-
-    def testPendingDeprecationMethodNames(self):
-        """Test fail* methods pending deprecation, they will warn in 3.2.
-
-        Do not use these methods.  They will go away in 3.3.
+        The fail* methods will be removed in 3.3. The assert* methods will
+        have to stay around for a few more versions.  See #9424.
         """
         old = (
             (self.failIfEqual, (3, 5)),
+            (self.assertNotEquals, (3, 5)),
             (self.failUnlessEqual, (3, 3)),
+            (self.assertEquals, (3, 3)),
             (self.failUnlessAlmostEqual, (2.0, 2.0)),
+            (self.assertAlmostEquals, (2.0, 2.0)),
             (self.failIfAlmostEqual, (3.0, 5.0)),
+            (self.assertNotAlmostEquals, (3.0, 5.0)),
             (self.failUnless, (True,)),
+            (self.assert_, (True,)),
             (self.failUnlessRaises, (TypeError, lambda _: 3.14 + 'spam')),
             (self.failIf, (False,)),
             (self.assertSameElements, ([1, 1, 2, 3], [1, 2, 3]))
         )
         for meth, args in old:
-            with support.check_warnings(('', DeprecationWarning)) as w:
+            with self.assertWarns(DeprecationWarning):
                 meth(*args)
-            self.assertEqual(len(w.warnings), 1)
+
+    def testDeprecatedFailMethods(self):
+        """Test that the deprecated fail* methods get removed in 3.3"""
+        if sys.version_info[:2] < (3, 3):
+            return
+        deprecated_names = [
+            'failIfEqual', 'failUnlessEqual', 'failUnlessAlmostEqual',
+            'failIfAlmostEqual', 'failUnless', 'failUnlessRaises', 'failIf',
+            'assertSameElements'
+        ]
+        for deprecated_name in deprecated_names:
+            with self.assertRaises(AttributeError):
+                getattr(self, deprecated_name)  # remove these in 3.3
 
     def testDeepcopy(self):
         # Issue: 5660
diff --git a/Misc/NEWS b/Misc/NEWS
index efbae8b..b9ecb42 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -109,7 +109,9 @@ C-API
 Tests
 -----
 
-- Issue #9424: Replace deprecated assert* methods in the Python test suite.
+- Issue #9424: Deprecate the `unittest.TestCase` methods `assertEquals`,
+  `assertNotEquals`, `assertAlmostEquals`, `assertNotAlmostEquals` and `assert_`
+  and replace them with the correct methods in the Python test suite.
 
 - Do not fail test_socket when the IP address of the local hostname
   cannot be looked up.