Issue 7832. Document changes to unittest.TestCase.assertSameElements and assertItemsEqual

Doc/library/unittest.rst

@@ -785,7 +785,7 @@ Test cases
       will be included in the error message. This method is used by default
       when comparing strings with :meth:`assertEqual`.
 
-      If specified *msg* will be used as the error message on failure.
+      If specified, *msg* will be used as the error message on failure.
 
       .. versionadded:: 3.1
 
@@ -806,7 +806,7 @@ Test cases
       Tests that *first* is or is not in *second* with an explanatory error
       message as appropriate.
 
-      If specified *msg* will be used as the error message on failure.
+      If specified, *msg* will be used as the error message on failure.
 
       .. versionadded:: 3.1
 
@@ -819,12 +819,31 @@ Test cases
 
       Duplicate elements are ignored when comparing *actual* and *expected*.
       It is the equivalent of ``assertEqual(set(expected), set(actual))``
-      but it works with sequences of unhashable objects as well.
+      but it works with sequences of unhashable objects as well. Because
+      duplicates are ignored, this method has been deprecated in favour of
+      :meth:`assertItemsEqual`.
 
-      If specified *msg* will be used as the error message on failure.
+      If specified, *msg* will be used as the error message on failure.
 
       .. versionadded:: 3.1
 
+      .. deprecated:: 3.2
+
+   .. method:: assertItemsEqual(actual, expected, msg=None)
+
+      Test that sequence *expected* contains the same elements as *actual*,
+      regardless of their order. When they don't, an error message listing the
+      differences between the sequences will be generated.
+
+      Duplicate elements are *not* ignored when comparing *actual* and
+      *expected*. It verifies if each element has the same count in both
+      sequences. It is the equivalent of ``assertEqual(sorted(expected),
+      sorted(actual))`` but it works with sequences of unhashable objects as
+      well.
+
+      If specified, *msg* will be used as the error message on failure.
+
+      .. versionadded:: 3.2
 
    .. method:: assertSetEqual(set1, set2, msg=None)
 
@@ -835,7 +854,7 @@ Test cases
       Fails if either of *set1* or *set2* does not have a :meth:`set.difference`
       method.
 
-      If specified *msg* will be used as the error message on failure.
+      If specified, *msg* will be used as the error message on failure.
 
       .. versionadded:: 3.1
 
@@ -847,7 +866,7 @@ Test cases
       method will be used by default to compare dictionaries in
       calls to :meth:`assertEqual`.
 
-      If specified *msg* will be used as the error message on failure.
+      If specified, *msg* will be used as the error message on failure.
 
       .. versionadded:: 3.1
 
@@ -858,7 +877,7 @@ Test cases
       superset of those in *expected*.  If not, an error message listing
       the missing keys and mismatched values is generated.
 
-      If specified *msg* will be used as the error message on failure.
+      If specified, *msg* will be used as the error message on failure.
 
       .. versionadded:: 3.1
 
@@ -872,7 +891,7 @@ Test cases
       These methods are used by default when comparing lists or tuples with
       :meth:`assertEqual`.
 
-      If specified *msg* will be used as the error message on failure.
+      If specified, *msg* will be used as the error message on failure.
 
       .. versionadded:: 3.1
 
@@ -884,7 +903,7 @@ Test cases
       be raised.  If the sequences are different an error message is
       constructed that shows the difference between the two.
 
-      If specified *msg* will be used as the error message on failure.
+      If specified, *msg* will be used as the error message on failure.
 
       This method is used to implement :meth:`assertListEqual` and
       :meth:`assertTupleEqual`.
@@ -1225,7 +1244,7 @@ Loading and running tests
 
    :class:`TestLoader` objects have the following methods:
 
-
+a
    .. method:: loadTestsFromTestCase(testCaseClass)
 
       Return a suite of all tests cases contained in the :class:`TestCase`\ -derived

Doc/whatsnew/2.7.rst

@@ -960,7 +960,7 @@ GvR worked on merging them into Python's version of :mod:`unittest`.
 * :meth:`assertIn` and :meth:`assertNotIn` tests whether
   *first* is or is not in  *second*.
 
-* :meth:`assertSameElements` tests whether two provided sequences
+* :meth:`assertItemsEqual` tests whether two provided sequences
   contain the same elements.
 
 * :meth:`assertSetEqual` compares whether two sets are equal, and

Lib/test/test_cgi.py

@@ -131,7 +131,7 @@ def test_strict(self):
             if isinstance(expect, dict):
                 # test dict interface
                 self.assertEqual(len(expect), len(fs))
-                self.assertEqual(norm(expect.keys()), norm(fs.keys()))
+                self.assertItemsEqual(expect.keys(), fs.keys())
                 ##self.assertEqual(norm(expect.values()), norm(fs.values()))
                 ##self.assertEqual(norm(expect.items()), norm(fs.items()))
                 self.assertEqual(fs.getvalue("nonexistent field", "default"), "default")

Tools/scripts/reindent-rst.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python
 
 # Make a reST file compliant to our pre-commit hook.
 # Currently just remove trailing whitespace.