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..."

I will submit a documentation only fix for this in the next day or so.

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.

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.

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".

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.

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."

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