The unittest documentation, argument names and implementation need to be consistent about the order of (actual, expected) for TestCase.assert methods that take two arguments. 

This is particularly relevant for the methods that produce 'diffed' output on failure - as the order determines whether mismatched items are missing from the expected or additional to the expected.

The documentation, signatures and implementation of all two argument asserts need to be checked to ensure they are the same and implemented correctly.

Personally I prefer (actual, expected).

This should get fixed-up before the second beta.

Try to confirm the most common argument ordering using Google's code search to ascertain actual practice in real code.

FWIW, I also tend to use actual/expected and find the reverse to be a form Yoda-speak, "assert 5 == x", "perhaps misread the prophecy was", etc.

The attached patch changes the following things

- assertDictContainsSubset(expected, actual, msg=None)
+ assertDictContainsSubset(subset, dictionary, msg=None)
This doesn't change the order of the args, even though the name of the method might suggest the opposite.  In the output message I left expected and actual because imho it makes sense there (e.g. "key, expected: 3, actual: 5").  This could be changed to expected/got or something else.


- assertCountEqual(expected, actual, msg=None)
+ assertCountEqual(actual, expected, msg=None)
This changes the order of the args and as a consequence the list of 'missing' and 'unexpected' elements will be swapped.  The tests don't check the error message so they all pass without modification.  It should be noted that this method didn't exist in 3.1. However 2.7 has the equivalent assertItemsEqual with the args swapped, so maybe it should be documented somewhere that while porting from 2.7 to 3.2 the order of the args should be changed accordingly.


- assertDictEqual(expected, actual, msg=None)
+ assertDictEqual(dict1, dict2, msg=None)
This is just a doc change, the actual method already uses d1 and d2 as args and their order doesn't seem to matter.

The other methods (mainly the assert*Equal) are just documented with generic first/second or foo1/foo2.  The doc for these methods could be changed to use actual/expected as a preferred order.

If Michael and Raymond reach a consensus, this can go in before beta2.

These three changes look fine.   

The argument order for assertDictContainsSubset is problematic (doesn't match its own name and doesn't match the order for other __contains__ methods elsewhere in Python), but it's too late to change it now :-(

The argument order doesn't match the name (which isn't a huge deal I don't think) - but subset in dict does match the element in container order of assertIn.

Fixed in r87389. This can be backported to 3.1/2.7 where applicable.

The issue10573.diff file with the time stamp 20:03 has a lot of document changes that don't have corresponding code changes?

Not all the arg names in the doc match with the actual name of the args (probably because the methods are expected to be used with positional args only), that's why the changes affects only the doc.

There was a BDFL ruling on python-dev mailing list that assert argument names should be (first, second). 

See:

http://mail.python.org/pipermail/python-dev/2010-December/106954.html

I'm basically reverting the patch to go back to (first, second) in the docs and in assertCountEqual.

Note that I looked at making the sequence comparison code symmetric - but it generates nice diffs for even nested containers by using prettyprint and difflib. Switching to a symmetric output ("in first, not in second" etc) would be very difficult without losing functionality.

Generating these diffs can be very slow though, so it may be an issue that needs revisiting.

Patch to docs and minor change to assertCountEqual to not use actual / expected internally.

Code patch looks good to me.  Unittest tests pass.