Repository navigation
Inconsistent listing of inherited abstract methods in collections.abc documentation #161311
Description
Documentation
Thanks for maintaining such comprehensive Python documentation!
While studying collections.abc, I noticed a small inconsistency in how inherited abstract methods are listed in the documentation table.
Description
The "Abstract Methods" column does not consistently indicate whether it lists only methods declared directly in an ABC or all abstract methods that subclasses must implement.
For example:
Reversibleinherits fromIterable, so subclasses must implement both__iter__()and__reversed__(). However, the table lists only__reversed__().Collectioninherits fromSized,Iterable, andContainer. The table lists all three inherited abstract methods:__contains__(),__iter__(), and__len__().
This makes it difficult to determine the complete set of required methods from the table alone.
Suggested improvement
I suggest distinguishing between directly declared abstract methods and all required abstract methods, including inherited ones.
For example:
| ABC | Inherits from | Directly declared abstract methods | All required abstract methods | Mixin methods |
|---|---|---|---|---|
Reversible |
Iterable |
__reversed__() |
__iter__(), __reversed__() |
— |
Collection |
Sized, Iterable, Container |
— | __contains__(), __iter__(), __len__() |
— |
This structure clearly distinguishes abstract methods declared directly in each ABC from those inherited from parent classes, making the complete interface requirements easier to understand.
Alternatively, the existing table could simply list all required abstract methods consistently, without adding new columns.
Either approach would improve clarity and make the documentation easier to use when implementing custom classes.
This suggestion concerns documentation clarity only and does not require changes to Python's behavior.
I hope this suggestion is helpful. Thanks for your time and for considering it!
Linked PRs
- gh-161311: Document inherited abstract methods in collections.abc #161319
- [3.15] gh-161311: Document inherited abstract methods in
collections.abc(GH-161319) #161330 - [3.14] gh-161311: Document inherited abstract methods in
collections.abc(GH-161319) #161331 - gh-161311: fix prose in
collections.abcpost GH-161319 #161333
Metadata
Metadata
Assignees
Projects
- Status
Activity
picnixz commentedon Nov 4, 2026
I think the table would be less readable on small devices (wide tables on a laptop render poorly IMO). I'd assume that people traceback the tree for each methods they need to implement though. OTOH, showing ALL methods that need to be implemented also makes it even harder to read.
Now, since we are anyway inconsistent, I think we can lean towards enumerating all those that need to be implemented. The other possibility is to list the methods and the classes that need them. How many methods at most a collection type needs to implement (inherited ones included)? and how many different dunders are there?
Bayel1602 commentedon Nov 4, 2026
Thanks for your feedback!
I agree that adding more columns could make the table harder to read, especially on smaller screens.
I checked the abstract methods in Python 3.14:
MutableSequence,MutableMapping, andMutableSet).collections.abc, including 14 dunder methods.Regarding the alternative structure where methods are listed alongside the classes that require them, I think it might be less convenient for developers implementing a specific interface.
For example, someone implementing
MutableSequencewould have to search through multiple rows to identify all the required methods, rather than finding everything in one place.For this reason, I would prefer keeping the existing table structure and consistently listing all required abstract methods, including inherited ones.
Since the maximum is only five methods per ABC, I think this would be a reasonable compromise that improves clarity without adding more columns.
Bayel1602 commentedon Nov 4, 2026
For example, a small section of the updated table could look like this:
IteratorIterable__next__()__iter__()ReversibleIterable__iter__(),__reversed__()CollectionSized,Iterable,Container__contains__(),__iter__(),__len__()SequenceReversible,Collection__getitem__(),__len__()__contains__(),__iter__(),__reversed__(),index(),count()This approach makes all required abstract methods explicit while preserving the original four-column layout, with only a slight increase in row height and no significant impact on table width.
picnixz commentedon Nov 4, 2026
ok, with 5 abtract methods at most, I believe it's fine to put them all in the table.
picnixz commentedon Nov 4, 2026
@Bayel1602 do you want to create a PR for that?
Bayel1602 commentedon Nov 4, 2026
Yes, I'd be happy to! I'll prepare a PR for this
pythongh-161311: Document inherited abstract methods in collections.abc
pythongh-161311: Clarify abstract methods column header
pythongh-161311: Move abstract methods clarification to introductory …
gh-161311: Document inherited abstract methods in `collections.abc` (#…
pythongh-161311: Fix introductory text in collections.abc
gh-161311: Fix introductory text in `collections.abc` after GH-161319 (…