classification
Title: Problem of consistency in collection.abc documentation
Type: enhancement Stage: resolved
Components: Documentation, Library (Lib) Versions: Python 3.7, Python 3.6
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: docs@python, rhettinger, yahya-abou-imran
Priority: normal Keywords:

Created on 2018-01-22 14:28 by yahya-abou-imran, last changed 2019-08-23 06:24 by rhettinger. This issue is now closed.

Messages (3)
msg310422 - (view) Author: Yahya Abou Imran (yahya-abou-imran) * Date: 2018-01-22 14:28
Opened after https://github.com/python/cpython/pull/5270 was closed.

Here:

https://docs.python.org/3/library/collections.abc.html

Some abstract methods are inherited from a superclass.
Most of the time the name of the method is mentioned in the subclass.

For example:

Collection inherit from Sized, Iterable and Contains.
But __len__, __iter__ and __contains__ are mentioned, even if they are inherited.

Mapping inherits from Collection, but __len__ and __iter__ appears in the table

There is one exception: Coroutine.
It inherits from Awaitable but we don't see __await__.

What would we do? Let all appear or not?
msg310683 - (view) Author: Yahya Abou Imran (yahya-abou-imran) * Date: 2018-01-25 16:10
There is another one:

Reversible list __reversed__ in the abstract method but inherits __iter__ from Iterable.

So there is definitely an inconsistency...
msg350251 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-08-23 06:24
The table is correct.  See the interactive session below for confirmation.  I think the source of your confusion is that some of the more complex ABCs are able to generate some of the required methods from the ones that are listed (for example, Mapping is able to automatically create __contains__ from __getitem__, so the former is not listed as a required abstract method).


>>> Container.__abstractmethods__
frozenset({'__contains__'})
>>> Hashable.__abstractmethods__
frozenset({'__hash__'})
>>> Iterable.__abstractmethods__
frozenset({'__iter__'})
>>> Reversible.__abstractmethods__
frozenset({'__reversed__', '__iter__'})
>>> Generator.__abstractmethods__
frozenset({'send', 'throw'})
>>> Sized.__abstractmethods__
frozenset({'__len__'})
>>> Callable.__abstractmethods__
frozenset({'__call__'})
>>> Collection.__abstractmethods__
frozenset({'__iter__', '__len__', '__contains__'})
>>> Sequence.__abstractmethods__
frozenset({'__getitem__', '__len__'})
>>> MutableSequence.__abstractmethods__
frozenset({'insert', '__getitem__', '__len__', '__delitem__', '__setitem__'})
>>> ByteString.__abstractmethods__
frozenset({'__getitem__', '__len__'})
>>> Set.__abstractmethods__
frozenset({'__iter__', '__len__', '__contains__'})
>>> MutableSet.__abstractmethods__
frozenset({'add', '__len__', '__iter__', 'discard', '__contains__'})
>>> Mapping.__abstractmethods__
frozenset({'__getitem__', '__iter__', '__len__'})
>>> MutableMapping.__abstractmethods__
frozenset({'__getitem__', '__len__', '__iter__', '__delitem__', '__setitem__'})
>>> MappingView.__abstractmethods__
frozenset()
>>> ItemsView.__abstractmethods__
frozenset()
>>> KeysView.__abstractmethods__
frozenset()
>>> ValuesView.__abstractmethods__
frozenset()
>>> Awaitable.__abstractmethods__
frozenset({'__await__'})
>>> Coroutine.__abstractmethods__
frozenset({'send', 'throw', '__await__'})
>>> AsyncIterable.__abstractmethods__
frozenset({'__aiter__'})
>>> AsyncIterator.__abstractmethods__
frozenset({'__anext__'})
>>> AsyncGenerator.__abstractmethods__
frozenset({'athrow', 'asend'})
History
Date User Action Args
2019-08-23 06:24:40rhettingersetstatus: open -> closed
resolution: not a bug
messages: + msg350251

stage: needs patch -> resolved
2018-01-28 18:22:17rhettingersetassignee: docs@python -> rhettinger
2018-01-27 15:09:52ppperrysettitle: Problem of consistence in collection.abc documentation -> Problem of consistency in collection.abc documentation
2018-01-26 23:53:42terry.reedysetassignee: docs@python

nosy: + docs@python
components: + Documentation, Library (Lib)
stage: needs patch
2018-01-26 23:53:08terry.reedysetnosy: + rhettinger
2018-01-25 16:10:29yahya-abou-imransetmessages: + msg310683
2018-01-22 14:28:36yahya-abou-imrancreate