GeezerVison is showing github.com — Inconsistent listing of inherited abstract methods in collections.abc documentation · Issue #161311 · python/cpython
Inconsistent listing of inherited abstract methods in collections.abc documentation #161311DescriptionDocumentation
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:
Reversible inherits from Iterable, so subclasses must implement both __iter__() and __reversed__(). However, the table lists only __reversed__().Collection inherits from Sized, Iterable, and Container. 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
Activitypicnixz commented on 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 commented on Nov 4, 2026 ContributorAuthor More actions 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:
- The maximum number of required abstract methods for a single ABC is 5 (
MutableSequence, MutableMapping, and MutableSet).
- There are 21 distinct abstract method names in
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 MutableSequence would 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 commented on Nov 4, 2026 ContributorAuthor More actions For example, a small section of the updated table could look like this:
| ABC |
Inherits from |
Required abstract methods (including inherited) |
Mixin methods |
Iterator |
Iterable |
__next__() |
__iter__() |
Reversible |
Iterable |
__iter__(), __reversed__() |
— |
Collection |
Sized, Iterable, Container |
__contains__(), __iter__(), __len__() |
— |
Sequence |
Reversible, 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 commented on Nov 4, 2026 ok, with 5 abtract methods at most, I believe it's fine to put them all in the table. picnixz commented on Nov 4, 2026 Bayel1602 commented on Nov 4, 2026 ContributorAuthor More actions Yes, I'd be happy to! I'll prepare a PR for this added a commit that references this issue on Nov 4, 2026gh-161311: Document inherited abstract methods in `collections.abc` (#…
MetadataMetadataStatusShow more project fields
DevelopmentNo branches or pull requestsIssue actions
|