classification
Title: Tutorial, list.sort() and items comparability
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: andymaier, docs@python, eric.araujo, ezio.melotti, martin.panter, r.david.murray, rhettinger, sandro.tosi, terry.reedy, tshepang
Priority: normal Keywords: patch

Created on 2012-02-18 16:58 by sandro.tosi, last changed 2019-08-22 16:40 by rhettinger. This issue is now closed.

Files
File name Uploaded Description Edit
list_sort-py27.diff sandro.tosi, 2012-02-18 16:58
list_sort-py32.diff sandro.tosi, 2012-02-18 16:58
issue14050-list_sort-py34_v2.diff andymaier, 2014-07-04 12:16 Patch version v2 for Python 3.4 and for merging into default review
issue14050-list_sort-py27_v2.diff andymaier, 2014-07-04 12:38 Patch version v2 for Python 2.7 review
Pull Requests
URL Status Linked Edit
PR 15381 merged rhettinger, 2019-08-22 07:06
PR 15395 merged miss-islington, 2019-08-22 16:11
Messages (16)
msg153648 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2012-02-18 16:58
I'm providing patches for what reported at http://mail.python.org/pipermail/docs/2012-February/007481.html . I'm not sure on wording or even if we want them in the tutorial section, but I think it would be nice to have it documented nonetheless.
msg153673 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-02-19 08:34
We could just mention that a TypeError is raised if some of the elements can't be compared. (Note that sorting a list that contains some types that cannot be compared might still succeed in some corner cases, but there's no reason to mention this).
msg153674 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-02-19 08:36
If I had read your patched version when I was a beginner, I don’t think it would have helped me much.  (Sorry for not coming up with an alternative right now, it’s late/early here and I’m tired :)
msg153769 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-02-20 08:24
An an aside, shouldn't that be "in-place" instead of "in place (http://en.wikipedia.org/wiki/In-place)?
msg153820 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-02-21 00:00
Nope, the expression would be hyphenated only when used as an adjective:

- “This sorts the sequence in place”
vs.
‑ “Performs an in-place rearrangement by birthdate”
msg222195 - (view) Author: Andy Maier (andymaier) * Date: 2014-07-03 15:23
Just out of curiosity: Why do the patches attached to this issue not have a "review" link?

Also, both (2.7 and 3.2) patches do not line up with the current 2.7 and 3.x tip, both hunks get rejected.

Comments on both patches:

1. It would be helpful if the text "Each item needs to define an ordering relationship." was followed by a statement about what happens when that is not the case (that is what Ezio also suggested), and where to look for details on how to define an ordering relationship. The problem with that is that there is no good place that is devoted to exactly that. The relatively best place for defining comparison I found so far is: https://docs.python.org/2.7/tutorial/datastructures.html#comparing-sequences-and-other-types and its 3.x equivalent.

2. The example that raises the TypeError is not needed, IMHO. This puts too much focus on the case that does not work. If we mention in the description that a TypeError is raised, that should be sufficient.

Andy
msg222197 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2014-07-03 16:07
> Why do the patches attached to this issue not have a "review" link?

because

> both (2.7 and 3.2) patches do not line up with the current
> 2.7 and 3.x tip, both hunks get rejected.

The "review" link only appears if the patch applies cleanly on the "default" branch.  Preparing a new patch against "default" should make the link appear.
msg222207 - (view) Author: Andy Maier (andymaier) * Date: 2014-07-03 18:57
Ah! I was somehow suspecting that. Thanks for clarifying!

I'll prepare a patch.

To correct my earlier message, the best place to link for comparisons is probably the Conparisons subchapter of the Expressions chapter in the reference. See also issue12067.
msg222208 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-07-03 19:04
The review link will also appear if the patch is generated via hg diff with diff.git turned *off*.  You will note that both existing patches use --git, which omits parent changeset information, so our system can't figure out what to apply them against in order to generate the review link.
msg222280 - (view) Author: Andy Maier (andymaier) * Date: 2014-07-04 12:16
Uploaded patch version py34_v2, which contains the following changes relative to 3.4:

1. The changes in the description of list.sort() from "default" in list.sort(), by adding this text:
  (the arguments can be used for sort customization, see :func:`sorted` for their explanation)

2. The proposed extension of the description of list.sort() from patch version py32.

3. A statement that TypeError is raised if the ordering relationship is not established.

4. A reference where to look in order to establish ordering relationship for user-defined classes. (referencing the Basic customization section of the Language Reference).

5. A reference where the ordering relationships for built-in types are described (referencing the Comparison chapter of the Language Reference).

-> Please review.

Andy
msg222281 - (view) Author: Andy Maier (andymaier) * Date: 2014-07-04 12:38
uploaded patch version py27_v2, which contains the same changes as py34_v2, relative to 2.7, except for this differences:

1. The change from "default" was already in 2.7.

2. The reference to defining ordering methods for user-defined classes includes a reference to object.__cmp__(), in addition.

-> Please review

Andy
msg222447 - (view) Author: Andy Maier (andymaier) * Date: 2014-07-07 10:59
Comments on v2 of both patches:

1. The paragraph "Each item needs to ..." describes the requirement in terms of "ordering relationships between items". It would be both simpler and less ambiguous to describe the requirement in terms of "type must be orderable". See the text added to sorted() as part of the patch for issue10289, for details.
msg222864 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-07-12 18:34
Unless I'm misremembering, it is exactly __lt__ (or __gt__, if __lt__ returns NotImplemented) that sorting depends on.  Since I'm sure there is code out there that depends on this fact, I wonder if it should be part of the language definition.

Also, the comparison documentation (https://docs.python.org/3/reference/expressions.html#comparisons) speaks about "total ordering" as being the requirement, which has a specific mathematical meaning (which sets, for example, do not satisfy, even though they have a __lt__ method).  Whether or not the distinction is worth explaining in the tutorial is a open question.
msg240513 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-04-12 00:00
The first paragraph in the patch already seems to have been applied, for Issue 21575.

The Sorting How-to <https://docs.python.org/dev/howto/sorting.html#odd-and-ends> already guarantees that defining only __lt__() is sufficient for sorted() and list.sort(). And the list.sort() specification <https://docs.python.org/dev/library/stdtypes.html#list.sort> says “only < comparisons” are used, which implies that only __gt__() may also be sufficient.

It might be good to change “ordering relationship” to “total ordering relationship”, but I think further explanation and other details are probably not worth adding to the tutorial. They could be clarified in the main documentation, but that is probably a separate issue.
msg350208 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-08-22 16:11
New changeset 4109263a7edce11194e301138cf66fa2d07f7ce4 by Raymond Hettinger in branch 'master':
bpo-14050: Note that not all data can be sorted (GH-15381)
https://github.com/python/cpython/commit/4109263a7edce11194e301138cf66fa2d07f7ce4
msg350213 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-08-22 16:39
New changeset cb8de91dadf15925fb95069cb190398e1d485f56 by Raymond Hettinger (Miss Islington (bot)) in branch '3.8':
bpo-14050: Note that not all data can be sorted (GH-15381) (GH-15395)
https://github.com/python/cpython/commit/cb8de91dadf15925fb95069cb190398e1d485f56
History
Date User Action Args
2019-08-22 16:40:18rhettingersetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2019-08-22 16:39:59rhettingersetmessages: + msg350213
2019-08-22 16:11:45miss-islingtonsetpull_requests: + pull_request15103
2019-08-22 16:11:38rhettingersetmessages: + msg350208
2019-08-22 07:06:58rhettingersetpull_requests: + pull_request15091
2015-04-12 00:00:14martin.pantersetnosy: + martin.panter
messages: + msg240513
2014-07-12 18:34:43r.david.murraysetmessages: + msg222864
2014-07-07 10:59:06andymaiersetmessages: + msg222447
2014-07-04 12:38:26andymaiersetfiles: + issue14050-list_sort-py27_v2.diff

messages: + msg222281
2014-07-04 12:16:18andymaiersetfiles: + issue14050-list_sort-py34_v2.diff

messages: + msg222280
2014-07-03 21:11:09rhettingersetassignee: docs@python -> rhettinger

nosy: + rhettinger
2014-07-03 19:04:44r.david.murraysetnosy: + r.david.murray
messages: + msg222208
2014-07-03 18:57:47andymaiersetmessages: + msg222207
2014-07-03 16:07:44ezio.melottisettype: enhancement
messages: + msg222197
versions: + Python 3.4, Python 3.5, - Python 3.2, Python 3.3
2014-07-03 15:23:10andymaiersetnosy: + andymaier
messages: + msg222195
2012-02-21 00:00:39eric.araujosetmessages: + msg153820
2012-02-20 08:24:45tshepangsetnosy: + tshepang
messages: + msg153769
2012-02-19 08:36:25eric.araujosetnosy: + eric.araujo, terry.reedy
messages: + msg153674
2012-02-19 08:34:34ezio.melottisetnosy: + ezio.melotti
messages: + msg153673
2012-02-18 16:58:56sandro.tosisetfiles: + list_sort-py32.diff
2012-02-18 16:58:48sandro.tosicreate