classification
Title: Docstrings of Sequence and MutableSequence seems not right
Type: behavior Stage:
Components: Documentation Versions:
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Jelle Zijlstra, docs@python, rhettinger, xiang.zhang
Priority: normal Keywords: patch

Created on 2016-06-04 09:20 by xiang.zhang, last changed 2016-06-06 00:10 by rhettinger. This issue is now closed.

Files
File name Uploaded Description Edit
issue27215.patch Jelle Zijlstra, 2016-06-05 18:45 review
Messages (3)
msg267249 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2016-06-04 09:20
Docstrings of Sequence and MutableSequence in collections.abc says "Concrete subclasses must provide __new__ and __init__". This seems not the truth. Not providing __new__ and __init__ is also OK.
msg267456 - (view) Author: Jelle Zijlstra (Jelle Zijlstra) * (Python triager) Date: 2016-06-05 18:45
The docstrings (at least in 3.6) say subclasses must override __new__ *or* __init__. However, I think this is wrong too. The following is a correct (if not very useful) implementation of Sequence:

>>> import collections.abc
>>> class MySequence(collections.abc.Sequence):
...     def __getitem__(self, key):
...             raise IndexError(key)
...     def __len__(self):
...             return 0
... 

Other abc docstrings also don't claim that __init__ or __new__ must be implemented. The attached patch fixes the docstrings.
msg267489 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-06-06 00:10
I think you're reading too much into the docs.  Most useful classes provide a __new__ or __init__ to put data into instances.  The docs are simply saying that that responsibility lies with the implementer rather than with the ABC.

IMO, the docs are more useful as-is.  Were we to accept the patch, it wouldn't be long before another user reported a bug saying that the implemented the other methods but the class didn't do anything useful.
History
Date User Action Args
2016-06-06 00:10:02rhettingersetstatus: open -> closed
resolution: not a bug
messages: + msg267489
2016-06-05 18:45:09Jelle Zijlstrasetfiles: + issue27215.patch

nosy: + Jelle Zijlstra
messages: + msg267456

keywords: + patch
2016-06-04 13:00:45ppperrysettype: behavior
2016-06-04 12:59:39ppperrysetassignee: docs@python

components: + Documentation
nosy: + docs@python
2016-06-04 09:20:17xiang.zhangcreate