classification
Title: Python 'datastructures.html' docs page needs improvement because of ambiguity
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, rhettinger, shoark7
Priority: normal Keywords: patch

Created on 2019-03-20 02:30 by shoark7, last changed 2019-04-02 04:53 by rhettinger. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 12468 merged eamanu, 2019-03-20 10:36
Repositories containing patches
https://docs.python.org/3/tutorial/datastructures.html#comparing-sequences-and-other-types
Messages (3)
msg338433 - (view) Author: parkito (shoark7) Date: 2019-03-20 02:30
Hi, I have lots of interests in python data structures and their inheritance relationships so I often look around in python collections and collections.abc module.

```
https://docs.python.org/3/tutorial/datastructures.html#comparing-sequences-and-other-types
```

Please see the last section of the page. I know all Python users are well aware of Sequence comparisons like in tuples and list. This page also mentions that 

'Sequence objects may be compared to other objects with the same sequence type' in the very first line of the page.

However, we have to know that 'range' is also a subclass of 'Sequence' but 'range' objects are not comparable to each other.

I tested 'range(1, 3) < 'range(3)' in my interpreter. If it compares correctly as both are same Sequence types, result would be 'False'. Instead, TypeError was raised. It's because comparision methods(__gt__, __lte__, etc) are not impleneted here. I thought range objects would compare the values with peeking. But they don't. 


So, I recommend you to implement 5.8 section in this page as follows:
  
   -> Please specify that 'not all' Sequence subclass are comparable to the same classes: typically, 'range'.

'range' is a good example because every Python user uses 'range' in for loop.
msg338434 - (view) Author: parkito (shoark7) Date: 2019-03-20 02:40
Hi, I have lots of interests in python data structures and their inheritance relationships so I often look around in python collections and collections.abc module.

```
https://docs.python.org/3/tutorial/datastructures.html#comparing-sequences-and-other-types
```

Please see the last section of the page. I know all Python users are well aware of Sequence comparisons like in tuples and list. This page also mentions that 

'Sequence objects may be compared to other objects with the same sequence type' in the very first line of the page.

However, we have to know that 'range' is also a subclass of 'Sequence' but 'range' objects are not comparable to each other.

I tested 'range(1, 3) < 'range(3)' in my interpreter. If it compares correctly as both are same Sequence types, result would be 'False'. Instead, TypeError was raised. It's because comparison methods(__gt__, __lte__, etc) are not impleneted here. I thought range objects would compare the values with peeking. But they don't. 


So, I recommend you to improve 5.8 section as follows:
  
   -> Please specify that 'not all' Sequence subclass are comparable to the same classes: typically, 'range'.

'range' is a good example because every Python user uses 'range' in for loop.
msg339315 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-04-02 04:52
New changeset b00479d42aaaed589d8b374bf5e5c6f443b0b499 by Raymond Hettinger (Emmanuel Arias) in branch 'master':
bpo-36377: Specify that range() can not be compared (GH-12468)
https://github.com/python/cpython/commit/b00479d42aaaed589d8b374bf5e5c6f443b0b499
History
Date User Action Args
2019-04-02 04:53:09rhettingersetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2019-04-02 04:52:44rhettingersetmessages: + msg339315
2019-03-20 10:36:27eamanusetkeywords: + patch
stage: patch review
pull_requests: + pull_request12420
2019-03-20 02:45:36xtreaksetnosy: + rhettinger
2019-03-20 02:40:42shoark7setmessages: + msg338434
2019-03-20 02:30:09shoark7create