Currently, the tutorial for the list sort method does not show allowed arguments:


    list.sort()
        Sort the items of the list in place.

(see e.g. https://docs.python.org/3.4/tutorial/datastructures.html)

Is there a reason why we do not show the arguments there? For simplicity? One should note that a web search for Python's list methods ranks that page pretty high. We could list the defaults, as in the built-in help:

     L.sort(cmp=None, key=None, reverse=False)

And could link to https://docs.python.org/2/library/functions.html#sorted for an explanation.

I assume it is on purpose that the tutorial does not show all methods with all their arguments.  It could overwhelm readers with too much information, and would also duplicate the full doc that’s in the reference.

A link from this tutorial page to the list reference (and maybe the sorting howto) could be a good addition.

> Is there a reason why we do not show the arguments there?

It was likely an oversight.   I think it should be updated so that people know the options are there.

I have updated the patch with a cross-reference to the sorted() built-in, which explains the arguments.

W.r.t. to Éric's suggestion: the sorted() doc refers to the sorting howto in the wiki. Now everything is connected.

New changeset 1b96949bfc97 by Raymond Hettinger in branch 'default':
Issue 21575:  Show list.sort() arguments in the tutorial.
http://hg.python.org/cpython/rev/1b96949bfc97

New changeset be77b213ace0 by Raymond Hettinger in branch '2.7':
Issue 21575:  Show list.sort() arguments in the tutorial.
http://hg.python.org/cpython/rev/be77b213ace0

messages: + msg219144