Improve documentation of list.sort and sorted()

[olau]

BPO	7257
Nosy	@birkenfeld, @rhettinger

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/rhettinger'
closed_at = <Date 2010-11-21.23:29:28.215>
created_at = <Date 2009-11-03.18:03:20.597>
labels = ['docs']
title = 'Improve documentation of list.sort and sorted()'
updated_at = <Date 2010-11-22.11:29:55.144>
user = 'https://bugs.python.org/olau'

bugs.python.org fields:

activity = <Date 2010-11-22.11:29:55.144>
actor = 'olau'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2010-11-21.23:29:28.215>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2009-11-03.18:03:20.597>
creator = 'olau'
dependencies = []
files = []
hgrepos = []
issue_num = 7257
keywords = []
message_count = 8.0
messages = ['94863', '94864', '94865', '94868', '94869', '94885', '122020', '122112']
nosy_count = 3.0
nosy_names = ['georg.brandl', 'rhettinger', 'olau']
pr_nums = []
priority = 'low'
resolution = 'wont fix'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue7257'
versions = []

[olau]

On my Python 3.1, help() for sorted returns

sort(...)
    L.sort(key=None, reverse=False) -- stable sort *IN PLACE*

sorted(...)
    sorted(iterable, key=None, reverse=False) --> new sorted list

Kindly suggest this be expanded. Here's some text:

sort(...)

Sorts the sequence with a fast stable sort. The sequence is modified in
place. To remind you of this, the function always returns None. Example:

a = [1, 3, 2]
a.sort()
# a is now [1, 2, 3]

Use the "sorted()" built-in function if you need to preserve the
original list.

Set "reverse" to True to sort the elements in reverse order. A function
for extracting a key for comparison from each object can be passed in as
"key", e.g.

a = [{'k': 'foo'}, {'k': 'bar'}]
a.sort(key=lambda x: x['k'])
# a is now [{'k': 'bar'}, {'k': 'foo'}]

Note that "key" can be used to solve many sorting problems, e.g.
key=str.lower can be used for case-insensitive sorting and key=lambda x:
(x['a'], x['b']) can be used to sort by first 'a' then 'b'.

The sort is stable which means that the relative order of elements that
compare equal is not changed.

sorted(...)

Sorts the sequence with a fast stable sort and returns a new list with
the result. Example:

[same text as before]

I'm not sure how this interacts with what's in the online help
(http://docs.python.org/3.1/library/stdtypes.html search for "sort("),
maybe the text could just be copied over. I think it's important to give
copy-pasteable examples for something as important as this, and hint at
how you solve common sorting problems.

[birkenfeld]

Raymond, do you have an opinion on this?

[rhettinger]

I'm inclined to leave the on-line help docstring as-is (pretty much
everywhere, we adopt a style of terse reminders instead of lengthy prose
with examples).

Instead, was thinking of updating the sorting how-to and providing a
link to it from the main docs.

[olau]

If you think it's too long, here's a shorter version:

Sorts sequence in place with a fast stable sort, returning None. key is
a function for extracting a comparison key from each element, e.g.
key=lambda x: x['name'] or key=str.lower. reverse=True reverses the
result order.

a = [1, 3, 2]
a.sort() # a is now [1, 2, 3]

Use the "sorted()" built-in function if you need to preserve the
original list.

Is this better? You could whack the last comment about sorted and/or the
example, then it's about the same length as the other built-in
docstrings (e.g. zip, reduce, getattr).

[rhettinger]

Will look at it and make an update, but not right away.

[olau]

OK, thanks! :) Sorry about the unintended nosy list removal, my browser
got me there.

[rhettinger]

After more thought, am leaving the doc strings as-is. They are succinct and accurate. I have updated the sorting how-to to more thoroughly cover the basics of sorting.

[olau]

Okay. I can only say that while the current docstrings are likely good reminders for you, knowing Python in and out, they were pretty useless to me as documentation, which I believe docstrings should be, they're called docstrings, after all, not reminderstrings. :) I fail to see how including more info can hurt in any way, you're not forced to read it if you don't need it, so I hope you (or somebody else) will reconsider at some point.