classification
Title: list.sort() should show arguments in tutorial
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: docs@python, eric.araujo, ezio.melotti, georg.brandl, jgehrcke, python-dev, rhettinger
Priority: normal Keywords: patch

Created on 2014-05-25 12:36 by jgehrcke, last changed 2014-06-29 10:07 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
sort_tut.diff rhettinger, 2014-05-26 01:45 Minor tutorial edit review
sort_tut_02.diff jgehrcke, 2014-05-26 08:15 Refer to sorted() built-in. review
Messages (6)
msg219085 - (view) Author: Jan-Philip Gehrcke (jgehrcke) * Date: 2014-05-25 12:36
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.
msg219100 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-05-25 19:08
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.
msg219120 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-05-26 01:41
> 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.
msg219144 - (view) Author: Jan-Philip Gehrcke (jgehrcke) * Date: 2014-05-26 08:15
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.
msg219192 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-05-27 01:44
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
msg219194 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-05-27 01:49
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
History
Date User Action Args
2014-06-29 10:07:59ezio.melottisettype: enhancement
stage: resolved
2014-05-27 01:50:09rhettingersetstatus: open -> closed
resolution: fixed
2014-05-27 01:49:36python-devsetmessages: + msg219194
2014-05-27 01:44:12python-devsetnosy: + python-dev
messages: + msg219192
2014-05-26 08:16:00rhettingersetassignee: docs@python -> rhettinger
2014-05-26 08:15:16jgehrckesetfiles: + sort_tut_02.diff

messages: + msg219144
2014-05-26 01:45:28rhettingersetfiles: + sort_tut.diff
keywords: + patch
2014-05-26 01:41:28rhettingersetnosy: + rhettinger
messages: + msg219120
2014-05-25 19:08:06eric.araujosetmessages: + msg219100
2014-05-25 12:36:25jgehrckecreate