[issue22830] functools.cmp_to_key: misleading key function description
New submission from Terry J. Reedy:
https://docs.python.org/3.4/library/functools.html#functools.cmp_to_key says " A key function is a callable that accepts one argument and returns another value indicating the position in the desired collation sequence." A python list poster (Veek M) 'value indicating the position' as meaning 0, 1, 2, ... and I would read it that way if I did not know better.
Entries for min() and max() say "The key argument specifies a one-argument ordering function like that used for list.sort()." This would be reused here. We also, now, have a Glossary entry for 'key function'. This could be referred to instead.
----------
assignee: docs@python
components: Documentation
messages: 230895
nosy: docs@python, terry.reedy
priority: normal
severity: normal
stage: needs patch
status: open
title: functools.cmp_to_key: misleading key function description
type: behavior
versions: Python 2.7, Python 3.4, Python 3.5
_______________________________________
Python tracker
Raymond Hettinger added the comment:
I'll add a link to the glossary entry for key function and to the sorting howto. Also, I'll change "value indicating the position" to "value to be used as the sort key".
The form sentence being discussed should probably remain close to how it is currently written. It is part of a two sentence paragraph that contrasts cmp functions versus key functions, so the parallel sentence structure is part of what it is trying to communicate.
FWIW, interpreting "value indicating position" as 0, 1, 2, etc isn't incorrect. That is a possible key function.
In general, I prefer doc changes to be very minor when they have a history of many people reading them correctly; otherwise, we risk moving away from something that was already working pretty well.
----------
assignee: docs@python -> rhettinger
nosy: +rhettinger
_______________________________________
Python tracker
Terry J. Reedy added the comment:
I agree with your comments and proposed changes and will leave this to you.
----------
_______________________________________
Python tracker
Roundup Robot added the comment:
New changeset dbe1744ec62e by Raymond Hettinger in branch '2.7':
Issue 22830: Clarify docs for functools.cmp_to_key().
https://hg.python.org/cpython/rev/dbe1744ec62e
----------
nosy: +python-dev
_______________________________________
Python tracker
Roundup Robot added the comment:
New changeset 63274cf1b40d by Raymond Hettinger in branch '3.4':
Issue 22830: Clarify docs for functools.cmp_to_key().
https://hg.python.org/cpython/rev/63274cf1b40d
----------
_______________________________________
Python tracker
Changes by Raymond Hettinger
participants (3)
-
Raymond Hettinger -
Roundup Robot
-
Terry J. Reedy