[ python-Bugs-1162912 ] typesseq-mutable lacks note on combined key/cmp usage

[SourceForge.net]

Bugs item #1162912, was opened at 2005-03-14 12:20
Message generated for change (Settings changed) made by birkenfeld
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1162912&group_id=5470

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: Documentation
Group: None
>Status: Closed
>Resolution: Rejected
Priority: 5
Submitted By: Stefan Behnel (scoder)
>Assigned to: Nobody/Anonymous (nobody)
Summary: typesseq-mutable lacks note on combined key/cmp usage

Initial Comment:
The documentation about list.sort() and sorted() does
not state how the keyword arguments cmp and key
interact. Aparently, if key is supplied, cmp works on
the result of the key function and no longer on the
item itself. This should be documented.

----------------------------------------------------------------------

>Comment By: Reinhold Birkenfeld (birkenfeld)
Date: 2005-07-04 16:20

Message:
Logged In: YES 
user_id=1188172

Done. Doc/lib/libstdtypes.tex r1.170.2.13, r1.184.

----------------------------------------------------------------------

Comment By: Raymond Hettinger (rhettinger)
Date: 2005-07-04 16:03

Message:
Logged In: YES 
user_id=80475

The docs are not meant to capture all implementation
details.  Building lookalike objects only need to match the
documented, promised behavior -- the rest can be arbitrary.

And, yes, it does matter that using the two together is
almost always the wrong thing to do.  The docs are supposed
to point people in the right direction -- it makes Python
easier to use.

Please revert this patch.

----------------------------------------------------------------------

Comment By: Reinhold Birkenfeld (birkenfeld)
Date: 2005-07-04 12:21

Message:
Logged In: YES 
user_id=1188172

But in this case, don't you think that the implementor would
in every case look up how it's done in the source code?

Raymond, please decide.

----------------------------------------------------------------------

Comment By: Stefan Behnel (scoder)
Date: 2005-07-04 11:52

Message:
Logged In: YES 
user_id=313935

... except, for example, when implementing classes that
behave like builtins and stdlib. So, if it's an
implementation detail, why not document that and give the
hint that the current CPython implementation applies key
before cmp?

I do not think it matters that using them together is
"almost always the wrong thing to do". In that case, it
should either become impossible or at least merit an
understandable warning in the documentation.

----------------------------------------------------------------------

Comment By: Raymond Hettinger (rhettinger)
Date: 2005-07-04 06:13

Message:
Logged In: YES 
user_id=80475

Actually, it should NOT be documented because 1) it is an
implementation specific detail and 2) using key and cmp
together is almost always the wrong thing to do.

----------------------------------------------------------------------

Comment By: Reinhold Birkenfeld (birkenfeld)
Date: 2005-07-03 22:22

Message:
Logged In: YES 
user_id=1188172

Thanks for the report and the patch.

Committed as Doc/lib/libstdtypes.tex r1.183, r1.170.2.12.

----------------------------------------------------------------------

Comment By: Peter van Kampen (pterk)
Date: 2005-07-03 22:00

Message:
Logged In: YES 
user_id=174455

I have submittted a doc patch (#1231890)  that adds a note
that reads:

If both key and cmp are supplied the key function is
applied before the cmp function.

(You can check listsort in listobject.c to verify)

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1162912&group_id=5470