This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: typesseq-mutable lacks note on combined key/cmp usage
Type: Stage:
Components: Documentation Versions:
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: Nosy List: georg.brandl, pterk, rhettinger, scoder
Priority: normal Keywords:

Created on 2005-03-14 11:20 by scoder, last changed 2022-04-11 14:56 by admin. This issue is now closed.

Messages (8)
msg24579 - (view) Author: Stefan Behnel (scoder) * (Python committer) Date: 2005-03-14 11:20
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.
msg24580 - (view) Author: Peter van Kampen (pterk) Date: 2005-07-03 20:00
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)
msg24581 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2005-07-03 20:22
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.
msg24582 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2005-07-04 04:13
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.
msg24583 - (view) Author: Stefan Behnel (scoder) * (Python committer) Date: 2005-07-04 09:52
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.
msg24584 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2005-07-04 10:21
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.
msg24585 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2005-07-04 14:03
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.
msg24586 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2005-07-04 14:20
Logged In: YES 
user_id=1188172

Done. Doc/lib/libstdtypes.tex r1.170.2.13, r1.184.
History
Date User Action Args
2022-04-11 14:56:10adminsetgithub: 41694
2005-03-14 11:20:06scodercreate