bpo-42280: Clarify docs on standard generic collections

[AlexWaygood]

This PR proposes adding two classes to the list of standard generic collections in the docs. These classes can be parametrised at runtime, but are currently omitted from the list.

The PR also tweaks the wording introducing the list, to make clear that the docs are not promising that this is an exhaustive list.

The PR does not add any of the classes from the queue module (queue.Queue, queue.LifoQueue, queue.PriorityQueue, queue.SimpleQueue), even though these can be parametrised. I have excluded these from the PR, as the documentation states that this is a list of "standard-library collections", and the queue classes are not collections (they are neither sized, nor iterable). However, re.Pattern is included in this list, and re.Pattern objects are also not collections -- so, perhaps the queue classes should also be added to this list.

https://bugs.python.org/issue42280

[Fidget-Spinner]

I would prefer we explicitly say "This list is non-exhaustive.". We won't be able to keep up with all the classes supporting __class_getitem__ as time goes by. There are way too many to list.

Related issue https://bugs.python.org/issue42280.

[AlexWaygood]

I would prefer we explicitly say "This list is non-exhaustive.". We won't be able to keep up with all the classes supporting __class_getitem__ as time goes by. There are way too many to list.

Related issue https://bugs.python.org/issue42280.

Ah, apologies, I didn't realise there was already an issue on this. I just stumbled across the list while doing the PR for the typing documentation. I agree with the thoughts on the BPO thread -- I think it's much wiser to clarify that the list is non-exhaustive rather than to attempt to put together an exhaustive list. Have edited the PR.

[Fidget-Spinner]

Ah, apologies, I didn't realise there was already an issue on this. I just stumbled across the list while doing the PR for the typing documentation. I agree with the thoughts on the BPO thread -- I think it's much wiser to clarify that the list is non-exhaustive rather than to attempt to put together an exhaustive list. Have edited the PR.

Yeah no issues (pun intended) there. I just linked the issue to provide some context behind our current stance. You don't have to link this PR to that (though I don't mind you linking it either :).

[ambv]

@AlexWaygood, now that I think about it, I think you're making a good point about "collections" not being "collections" in the list. How about we fix it by:

• adding queue classes (and others if any come to your mind)
• using the word data structures instead of collections in the wording of the list in question

[AlexWaygood]

@AlexWaygood, now that I think about it, I think you're making a good point about "collections" not being "collections" in the list. How about we fix it by:

• adding queue classes (and others if any come to your mind)
• using the word data structures instead of collections in the wording of the list in question

...how are we defining "data structures"? 🤔 If re.Pattern belongs in this list, does os.PathLike?

I think I'd be tempted to split it into two lists: a list of standard library collections that can be parameterised, and a list of standard library ABCs that can be parameterised. We have widely agreed-upon definitions for what constitutes a "collection" and what constitutes an "ABC", so it would make this problem easier to tackle.

But I'm not sure the classes from the re module would belong in either list 🤷

[AlexWaygood]

I'm going to close this PR and open a new one.