Title: Doc list.sort(cmp=,key=) result.
Type: Stage: needs patch
Components: Documentation Versions: Python 2.7
Status: closed Resolution: wont fix
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: docs@python, rhettinger, terry.reedy
Priority: low Keywords: easy, patch

Created on 2011-03-29 19:28 by terry.reedy, last changed 2011-03-30 00:40 by rhettinger. This issue is now closed.

Messages (5)
msg132507 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-03-29 19:28
l.sort(cmp=lambda x,y:y-x, key=lambda x: x)

With CPython 2.7 this
1) could raise an exception like TypeError: conflicting arguments passed;
2) could ignore cmp= and print [1,2,3] on the basis that the new should override the old;
3) does ignore key= and prints [3,2,1] (why does not matter now),
but as near as I can tell, this is not documented.

Suggestion: in 5.6.4. Mutable Sequence Types, in footnote 8, after
"key specifies a function of one argument that is used to extract a comparison key from each list element: key=str.lower. The default value is None."
add "Ignored if *cmp* is also given."
msg132551 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-03-29 23:01
On pydev, Mathew Woodcraft says the actual rule is
4) Neither 'wins': cmp is applied to the output of key.
which is consistent with my experiment also.
msg132556 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-03-29 23:40
There's no need to guess what it does ;-)  We don't document by experiment when source and test suites are available.  

Mathew was correct, it works as documented:  the key function is applied  at the outset (as it always does) and then cmp function is used whenever a comparison is made (as it always does).  There is no special change in behavior when the two are used together; they are effectively orthogonal (the actual implementation is a bit more complicated).  IMO, the docs are correct as-is.

There is some question about whether to specifically elaborate on what happens when both are used together.  For the most part, users are better-off using either key-functions or cmp-functions but not both at the same time.  We may be doing them a disservice by suggesting otherwise.  

This has been out for several years now and no one has either noticed or cared, so I recommend closing with no change.
msg132559 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-03-30 00:15
The 2.7 doc actually says that the two arguments to cmp are list items, rather than list items or keys "cmp specifies a custom comparison function of two arguments (list items)". And this "In general, the key and reverse conversion processes are much faster than specifying an equivalent cmp function." sort of suggests one or the other (but not both). That said, given the absence of overt problems, I agree with 
> We may be doing them a disservice by suggesting otherwise.
msg132563 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-03-30 00:40
Thank you.
Date User Action Args
2011-03-30 00:40:01rhettingersetmessages: + msg132563
2011-03-30 00:15:20terry.reedysetstatus: open -> closed
resolution: wont fix
messages: + msg132559
2011-03-29 23:40:24rhettingersetmessages: + msg132556
2011-03-29 23:01:18terry.reedysetmessages: + msg132551
2011-03-29 19:41:37rhettingersetpriority: normal -> low
assignee: docs@python -> rhettinger

nosy: + rhettinger
2011-03-29 19:28:41terry.reedycreate