This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: collections.abc documentation incomplete
Type: enhancement Stage: resolved
Components: Documentation, Library (Lib) Versions: Python 3.11
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: docs@python Nosy List: abarnert, docs@python, gvanrossum, iritkatriel, rhettinger
Priority: normal Keywords: easy, patch

Created on 2016-01-06 02:05 by abarnert, last changed 2022-04-11 14:58 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
patch26019.diff abarnert, 2016-01-06 02:50 review
Messages (6)
msg257577 - (view) Author: Andrew Barnert (abarnert) * Date: 2016-01-06 02:05
Some of the modules in collections.abc have a subclass hook that implicitly registers any type that declares the right methods, like Iterator. Others do not, like Sequence. For those that do have the hook, it's not always obvious what methods are tested. And some of them test the methods for truthiness, others only for existence (although #25958 will fix that last bit).

The documentation doesn't even mention this, much less describe which ABCs are of which kind.

For someone who just wants to know how to write isinstance(arg, Iterable), that's fine. But anyone who wants to create new classes, or integrate third-party classes that weren't ABC-friendly, has to read the collections.abc module source to figure out what they want to do.
msg257581 - (view) Author: Andrew Barnert (abarnert) * Date: 2016-01-06 02:50
The attached patch is, I think, the smallest change that includes all the necessary information.

Of course it will need to be redone if #25958 goes through, with a version-changed note explaining that prior to 3.6 some of the implicit ABCs (maybe with a list) treated None as an abstract method implementation while others didn't. So, this patch is basically a throwaway. But any review comments would still be useful, of course.
msg257640 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2016-01-06 20:48
LGTM. Do you want me to commit it now or wait until you've redone it after #25958 has gone through?
msg257732 - (view) Author: Andrew Barnert (abarnert) * Date: 2016-01-08 00:46
Probably better to wait.
msg415564 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2022-03-19 19:44
The patch needs to be converted to a GitHub PR and reviewed.
msg415581 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2022-03-19 22:53
This was fixed in commit 62fa613f6a6e872723505ee9d56242c31a654a9d
History
Date User Action Args
2022-04-11 14:58:25adminsetgithub: 70207
2022-03-19 22:53:44rhettingersetstatus: open -> closed

nosy: + rhettinger
messages: + msg415581

resolution: out of date
stage: resolved
2022-03-19 19:44:09iritkatrielsetversions: + Python 3.11, - Python 3.6
nosy: + iritkatriel

messages: + msg415564

components: + Library (Lib)
keywords: + easy
2016-01-08 00:46:28abarnertsetmessages: + msg257732
2016-01-06 20:48:32gvanrossumsetnosy: + gvanrossum
messages: + msg257640
2016-01-06 02:50:21abarnertsetfiles: + patch26019.diff
keywords: + patch
messages: + msg257581
2016-01-06 02:05:12abarnertcreate