classification
Title: Key in sort -> Callable Object instead of function
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.9, Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: Carlos Segura González, Juhana.Jauhiainen, anthony-flury, docs@python, rhettinger, terry.reedy, veky
Priority: low Keywords: easy, newcomer friendly, patch

Created on 2020-01-17 23:11 by Carlos Segura González, last changed 2020-01-26 03:07 by rhettinger. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 18177 merged python-dev, 2020-01-25 06:57
Messages (8)
msg360219 - (view) Author: Carlos Segura González (Carlos Segura González) Date: 2020-01-17 23:11
In the Documentation, the "Sorting HOW TO" (https://docs.python.org/3/howto/sorting.html) states that "have a key parameter to specify a function to be called". However, it might be other callable objects. In fact, some of the examples given in the documentation are not with functions.

I suggest: "have a key parameter to specify a callable object that is called..."
msg360220 - (view) Author: Anthony Flury (anthony-flury) * Date: 2020-01-17 23:23
I will submit a documentation only fix for this in the next day or so.
msg360228 - (view) Author: Vedran Čačić (veky) * Date: 2020-01-18 03:01
I think that "HOW TO"s are fundamentally different from the "regular" documentation, in that they focus on explaining only the usual use cases and valuing simple explanations over the correct ones. Of course this _can_ be fixed, but I don't think that it must be done.
msg360231 - (view) Author: Carlos Segura González (Carlos Segura González) Date: 2020-01-18 03:21
The thing is that even in the "Language Reference" is not correct. In "https://docs.python.org/3/library/functions.html#sorted" it is stated "key specifies a function of one argument that is used to extract a comparison key..."

I think that it is better to use the term callable object. In the case of the HOW-TO, maybe it would be good to clarify that a function is an example of a callable object or include a reference or something like that.
msg360272 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-01-19 21:40
Go ahead and make a PR for this:

   function -> function (or other callable)

Let's keep the word "function" because it does a much better job of communicating that an the more abstract word "callable".
msg360657 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2020-01-24 21:35
I agree that we should keep 'function', as it is often used at least somewhat generically (as in Library Manual 'Built-in Functions' chapter). I marked this as an easy first PR.
msg360673 - (view) Author: Juhana Jauhiainen (Juhana.Jauhiainen) * Date: 2020-01-25 07:12
I created a pull request for this issue. It adds the description "(or other callable)" to two places in sorting documentation.

"function (or other callable) to be called on each list element prior to making
comparisons."

and later

"The value of the *key* parameter should be a function (or other callable) that takes a single argument and returns a key to use for sorting purposes."
msg360713 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-01-25 22:19
New changeset 8271441d8b6e1f8eae1457c437da24e775801d9f by Raymond Hettinger (Juhana Jauhiainen) in branch 'master':
bpo-39374: Updated sorting documentation (GH-18177)
https://github.com/python/cpython/commit/8271441d8b6e1f8eae1457c437da24e775801d9f
History
Date User Action Args
2020-01-26 03:07:22rhettingersetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2020-01-25 22:19:09rhettingersetmessages: + msg360713
2020-01-25 07:12:57Juhana.Jauhiainensetnosy: + Juhana.Jauhiainen
messages: + msg360673
2020-01-25 06:57:59python-devsetkeywords: + patch
stage: patch review
pull_requests: + pull_request17560
2020-01-24 21:35:50terry.reedysetkeywords: + easy, newcomer friendly
nosy: + terry.reedy
messages: + msg360657

2020-01-19 21:40:21rhettingersetpriority: normal -> low
assignee: docs@python -> rhettinger
messages: + msg360272

versions: - Python 3.5, Python 3.6
2020-01-18 03:21:31Carlos Segura Gonzálezsetmessages: + msg360231
2020-01-18 03:19:17xtreaksetnosy: + rhettinger
2020-01-18 03:01:21vekysetnosy: + veky
messages: + msg360228
2020-01-17 23:23:43anthony-flurysetnosy: + anthony-flury
messages: + msg360220
2020-01-17 23:12:33Carlos Segura Gonzálezsettype: enhancement
2020-01-17 23:11:22Carlos Segura Gonzálezcreate