assertItemsEqual was added to unittest.TestCase in Python 2.7 (according to the documentation), but is not present in Python 3.3.

I'd expect it to be present in 3.3 as well, or for it to be mentioned in documentation as not being present (either in the 2.7 documentation or the Misc/NEWS file for py3k)

I don't remember how it went exactly, but there were a few similar methods (assertItemsEqual, assertSameElements, assertCountEqual).  In 3.x we eventually decide to remove the first 2 because it wasn't clear what they were doing, and only assertCountEqual survived.  In 2.7 this wasn't possible, so assertItemsEqual survived.
assertDictContainsSubset is another method that was in 2.7 but is not in 3.x anymore.
Do you think the docs for 2.x should mention this?

I do think this should be mentioned in the 2.7 docs, assertDictContainsSubset is mentioned as "deprecated since 3.2" in the 2.7 docs.  The only problem with that is that there doesn't seem to be a "versionremoved" directive in sphinx, the best alternative seems to be deprecated-removed.

I'm not to happy about the removal though, assertCountEqual is not in 2.7 which means it is unnecessarily hard to port tests from 2.7 to 3.3. I also don't quite understand the difference between assertCountEqual and assetItemsEqual, the documentation for the two (in the 3.3 and 2.7 docs) appears to indicate they have the same behavior (both assert that two sequence have the same contents when the order of items is ignored).

I think they might actually be the same (i.e. the name changed but not the implementation).  See #10242.
If this is true the new name could be mentioned in 2.7.

You're right, according to #10242 the method was renamed in 3.2.

Something like the attached patch?


I'm somewhat flabbergasted that #10242 came to the conclusion that it would be a good idea to rename this method, given the folks that contributed the discussion.   It not that the new name is very good, I've seen it in the 3.3 docs and didn't notice that it was relevant for what I was trying to do until you mentioned the method and I actually read the description. When I first saw the method I thought it was related to list.count.

Apparently assertItemsEqual was added to 2.7 and 3.2 and, after the release of 2.7 but before the release of 3.2, assertItemsEqual has been renamed assertCountEqual (596239da3db7) and initially the assertItemsEqual was available too.  However, since the method was new in 3.2 the old alias got removed shortly after (bdd57841f5e2).  Eventually 3.2 was released with only assertCountEqual.

Looks like we wrote a similar patch at the same time :)
We don't usually use versionchanged in the 2.x docs for things that changed in 3.x.  Using "named" instead of "renamed" is better, since in 3.x the name was assertCountEqual since the beginning, however saying "In Python 3.2" might be confusing (people might think that it's different for 3.3+).  I suggest to replace it with simply "Python 3", or perhaps "Python 3.2+".

Your patch looks good.

New changeset d9921cb6e3cd by Ezio Melotti in branch '2.7':
#17866: mention that in Python 3, assertItemsEqual is named assertCountEqual.
http://hg.python.org/cpython/rev/d9921cb6e3cd

Applied.

Python 2.7 documentation is VERY misleading about the functionality of assertItemsEqual. It actually claims to compare not only the counts, but the actual sorted elements themselves. This documentation mislead my group to use this method for comparing the elements. See https://hg.python.org/cpython/file/d9921cb6e3cd/Doc/library/unittest.rst:

   .. 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.

I opened http://bugs.python.org/issue27060 regarding the erroneous documentation of assertItemsEqual in python 2.7.

Folks, assertCountEqual sounds like a really bad name. It misleads users into thinking that it only compares the number of elements in each sequence, whereas it actually asserts that equivalent items are present in both sequences, regardless of order. The original name from 2.7 assertItemsEqual was so much better and more meaningful.

At the time I wanted it to be named assertCountsEqual, which is better (IMO) than either assertItemsEqual or assertCountEqual.  I lost that naming contest, though :(.  On the third hand, I don't think there exists a good two word name for what the function does.