(original) (raw)

On 29/10/2010 23:56, Michael Foord wrote:

On 29/10/2010 23:29, Michael Foord wrote:
\[snip...\]

Besides de-documenting those four redundant methods,

I propose that assertItemsEqual() be deprecated just like

its brother assertSameElements(). I haven't found anyone

who accurately guesses what those methods entail based

on their method names ("items" usually implies key/value

pairs elsewhere in the language; nor is it clear whether order is

important, whether the elements need to be hashable or

orderable or just define equality tests, nor is is clear whether

duplicates cause the test to fail).

Given the purpose of the unittest module, it's important that

the reader have a crystal clear understanding of what a test

is doing. Their attention needs to be focused on the subject

of the test, not on questioning the semantics of the test method.

assertItemsEqual compares two iterables and tests that they have the same elements irrespective of order. A relatively straightforward definition. Hopefully the docstring and documentation make this clear.

If the members are all of the same type then indeed comparing two sorted lists is only slightly more typing. If the members are of different types checking that the members are the same is a much harder problem in Python 3, and this method can be very useful.

Just to clarify. The following fails in Python 3:

sorted(\[3, 1, 2, None\])

If you want to compare that two iterables containing heterogeneous types have the same members then it is tricky to implement correctly and assertItemsEqual does it for you.

I agree that the name is not ideal and would be happy to change the name (deprecating the old name as it was released in 2.7). API churn is as bad as API bloat, but at least changing the name is something only done once.

Sorry for the noise. Suggested alternative name:

assertElementsEqual

The docs need updating to make it clear that the method isn't just a synonym for assertEqual(sorted(iter1), sorted(iter2)) and that it works with unorderable types.

As for "assertLessEqual" and friends, I don't find those names intuitive. In fact whilst typing this email I initially called the method "assertLessThan".

For "assertRegexpMatches" I don't find it hard to understand (in natural English it makes sense even if the standard terminology for regular expressions is different). I would have preferred "assertRegex" though.

All the best,

Michael

All the best,

Michael
-1 for deprecating.

All the best,

Michael Foord

IMO, users are far better-off sticking with assertEqual() so they

can be specific about the nature of the test:

   # hashable elements; ignore dups

   assertEqual(set(a), set(b))

   # orderable elements; dups matter, order doesn't

   assertEqual(sorted(a), sorted(b))

   # eq tested elements, dups matter, order matters

   assertEqual(list(a), list(b))

   # hashable keys, eq tested values

   # ignore dups, ignore order

   assertEqual(dict(a), dict(b))

These take just a few more characters than assertSameElements()

and assertItemsEqual(), but they are far more clear about their meaning.

You won't have to second guess what semantics are hidden

behind the abstraction.
There are a couple other problems with the new API but it is probably

too late to do anything about it.

\* elsewhere in Python we spell comparison names with abbreviations

   like eq, ne, lt, le, gt, ge. In unittest, those are spelled in an awkward,

   not easily remembered manner: assertLessEqual(a, b), etc.

   Fortunately, it's clear what the mean; however, it's not easy to guess

   their spelling.

\* the names for assertRegexpMatches() and assertNotRegexpMatches

   are deeply misleading since they are implemented in terms of

   re.search(), not re.match().

Raymond

P.S. I also looked ar assertDictContainsSubset(a,b). It is a bit

over-specialized, but at least it is crystal clear what is does

and it beats the awkward alternative using dict views:

   assertLessEqual(a.items(), b.items())
  
\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_  
Python-Dev mailing list  
Python-Dev@python.org  
http://mail.python.org/mailman/listinfo/python-dev  
Unsubscribe: http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.uk  
--   
http://www.voidspace.org.uk/
  
\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_  
Python-Dev mailing list  
Python-Dev@python.org  
http://mail.python.org/mailman/listinfo/python-dev  
Unsubscribe: http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.uk  
--   
http://www.voidspace.org.uk/
  
  
\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_  
Python-Dev mailing list  
Python-Dev@python.org  
http://mail.python.org/mailman/listinfo/python-dev  
Unsubscribe: http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.uk  

--   
http://www.voidspace.org.uk/