GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — bpo-42280: Clarify docs on standard generic collections by AlexWaygood · Pull Request #29308 · python/cpython

Conversation

@AlexWaygood

@AlexWaygood AlexWaygood commented Oct 29, 2021 •
edited by bedevere-bot
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@AlexWaygood
Clarify docs on standard generic collections
34af4e7 
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.
@the-knights-who-say-ni the-knights-who-say-ni added the CLA signed label Oct 29, 2021
@bedevere-bot bedevere-bot added docs Documentation in the Doc dir awaiting review labels Oct 29, 2021
@Fidget-Spinner

Fidget-Spinner commented Oct 29, 2021

Copy link
Copy Markdown
Member

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 reacted with thumbs up emoji
All reactions
  • 👍 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@AlexWaygood
Alter wording introducing the list
c0e1c28
@AlexWaygood

AlexWaygood commented Oct 29, 2021

Copy link
Copy Markdown
Member Author

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.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@AlexWaygood AlexWaygood changed the title Clarify docs on standard generic collections bpo-42280: Clarify docs on standard generic collections Oct 29, 2021
@Fidget-Spinner

Fidget-Spinner commented Oct 29, 2021

Copy link
Copy Markdown
Member

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 :).
AlexWaygood reacted with thumbs up emoji
All reactions
  • 👍 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@Fidget-Spinner Fidget-Spinner added needs backport to 3.9 skip news labels Oct 29, 2021
ambv
ambv reviewed Oct 29, 2021
View reviewed changes
Comment thread Doc/library/stdtypes.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@ambv
Avoid parentheses when they end the sentence
9b75743
@ambv

ambv commented Oct 29, 2021

Copy link
Copy Markdown
Contributor

@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
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@AlexWaygood

AlexWaygood commented Oct 29, 2021

Copy link
Copy Markdown
Member Author

@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 🤷
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@AlexWaygood

AlexWaygood commented Oct 30, 2021

Copy link
Copy Markdown
Member Author

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@AlexWaygood AlexWaygood closed this Oct 30, 2021
AlexWaygood added a commit to AlexWaygood/cpython that referenced this pull request Oct 30, 2021
@AlexWaygood
bpo-45680: Clarify documentation on GenericAlias objects
a6fe738 
The documentation on ``GenericAlias`` objects implies at multiple points that
only container classes can define ``__class_getitem__``. This is misleading.
This PR proposes a rewrite of the documentation to clarify that non-container
classes can define ``__class_getitem__``, and to clarify what it means when a
non-container class is parameterized.

See also: initial discussion of issues with this piece of documentation in
python#29308, and previous BPO issue [42280](https://bugs.python.org/issue42280).
@AlexWaygood AlexWaygood mentioned this pull request Oct 30, 2021
bpo-45680: Clarify documentation on GenericAlias objects #29335
Merged
@AlexWaygood
AlexWaygood deleted the patch-1 branch October 30, 2021 20:47
@miss-islington miss-islington mentioned this pull request Jan 19, 2022
[3.10] bpo-45680: Clarify documentation on GenericAlias objects (GH-29335) #30688
Merged
Fidget-Spinner added a commit that referenced this pull request Jan 19, 2022
@AlexWaygood Erlend Egeberg Aasland @Fidget-Spinner
bpo-45680: Clarify documentation on GenericAlias objects (GH-29335)
0eae9a2 
The documentation on ``GenericAlias`` objects implies at multiple points that
only container classes can define ``__class_getitem__``. This is misleading.
This PR proposes a rewrite of the documentation to clarify that non-container
classes can define ``__class_getitem__``, and to clarify what it means when a
non-container class is parameterized.

See also: initial discussion of issues with this piece of documentation in
GH-29308, and previous BPO issue [42280](https://bugs.python.org/issue42280).

Also improved references in glossary and typing docs. Fixed some links.

Co-authored-by: Erlend Egeberg Aasland <[email protected]>
Co-authored-by: Ken Jin <[email protected]>
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jan 19, 2022
@AlexWaygood @miss-islington
bpo-45680: Clarify documentation on GenericAlias objects (pythonG…
f238ae6 
…H-29335)

The documentation on ``GenericAlias`` objects implies at multiple points that
only container classes can define ``__class_getitem__``. This is misleading.
This PR proposes a rewrite of the documentation to clarify that non-container
classes can define ``__class_getitem__``, and to clarify what it means when a
non-container class is parameterized.

See also: initial discussion of issues with this piece of documentation in
pythonGH-29308, and previous BPO issue [42280](https://bugs.python.org/issue42280).

Also improved references in glossary and typing docs. Fixed some links.

Co-authored-by: Erlend Egeberg Aasland <[email protected]>
Co-authored-by: Ken Jin <[email protected]>
(cherry picked from commit 0eae9a2)

Co-authored-by: Alex Waygood <[email protected]>
Fidget-Spinner added a commit to Fidget-Spinner/cpython that referenced this pull request Jan 19, 2022
@Fidget-Spinner Erlend Egeberg Aasland @AlexWaygood
bpo-45680: Clarify documentation on GenericAlias objects (pythonG…
8766418 
…H-29335)

The documentation on ``GenericAlias`` objects implies at multiple points that
only container classes can define ``__class_getitem__``. This is misleading.
This PR proposes a rewrite of the documentation to clarify that non-container
classes can define ``__class_getitem__``, and to clarify what it means when a
non-container class is parameterized.

See also: initial discussion of issues with this piece of documentation in
pythonGH-29308, and previous BPO issue [42280](https://bugs.python.org/issue42280).

Also improved references in glossary and typing docs. Fixed some links.

Co-Authored-By: Erlend Egeberg Aasland <[email protected]>
Co-Authored-By: Ken Jin <[email protected]>
Co-Authored-By: Alex Waygood <[email protected]>
@Fidget-Spinner Fidget-Spinner mentioned this pull request Jan 19, 2022
[3.9] bpo-45680: Clarify documentation on GenericAlias objects (GH-29335) #30689
Merged
miss-islington added a commit that referenced this pull request Jan 19, 2022
@miss-islington
[3.10] bpo-45680: Clarify documentation on GenericAlias objects (G…
24d0b33 
…H-29335) (GH-30688)

The documentation on ``GenericAlias`` objects implies at multiple points that
only container classes can define ``__class_getitem__``. This is misleading.
This PR proposes a rewrite of the documentation to clarify that non-container
classes can define ``__class_getitem__``, and to clarify what it means when a
non-container class is parameterized.

See also: initial discussion of issues with this piece of documentation in
GH-29308, and previous BPO issue [42280]().

Also improved references in glossary and typing docs. Fixed some links.

Co-authored-by: Erlend Egeberg Aasland <[email protected]>
Co-authored-by: Ken Jin <[email protected]>
(cherry picked from commit 0eae9a2)


Co-authored-by: Alex Waygood <[email protected]>

Automerge-Triggered-By: GH:Fidget-Spinner
Fidget-Spinner added a commit that referenced this pull request Jan 19, 2022
@Fidget-Spinner Erlend Egeberg Aasland @AlexWaygood
[3.9] bpo-45680: Clarify documentation on GenericAlias objects (G…
0064516 
…H-29335) (GH-30689)

The documentation on ``GenericAlias`` objects implies at multiple points that
only container classes can define ``__class_getitem__``. This is misleading.
This PR proposes a rewrite of the documentation to clarify that non-container
classes can define ``__class_getitem__``, and to clarify what it means when a
non-container class is parameterized.

See also: initial discussion of issues with this piece of documentation in
GH-29308, and previous BPO issue [42280](https://bugs.python.org/issue42280).

Also improved references in glossary and typing docs. Fixed some links.

(cherry picked from commit 0eae9a2)

Co-Authored-By: Erlend Egeberg Aasland <[email protected]>
Co-Authored-By: Ken Jin <[email protected]>
Co-Authored-By: Alex Waygood <[email protected]>
hello-adam pushed a commit to hello-adam/cpython that referenced this pull request Jun 2, 2022
@Fidget-Spinner Erlend Egeberg Aasland
@AlexWaygood @hello-adam
[3.9] bpo-45680: Clarify documentation on GenericAlias objects (p…
82a1542 
…ythonGH-29335) (pythonGH-30689)

The documentation on ``GenericAlias`` objects implies at multiple points that
only container classes can define ``__class_getitem__``. This is misleading.
This PR proposes a rewrite of the documentation to clarify that non-container
classes can define ``__class_getitem__``, and to clarify what it means when a
non-container class is parameterized.

See also: initial discussion of issues with this piece of documentation in
pythonGH-29308, and previous BPO issue [42280](https://bugs.python.org/issue42280).

Also improved references in glossary and typing docs. Fixed some links.

(cherry picked from commit 0eae9a2)

Co-Authored-By: Erlend Egeberg Aasland <[email protected]>
Co-Authored-By: Ken Jin <[email protected]>
Co-Authored-By: Alex Waygood <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ambv ambv ambv left review comments

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

awaiting review docs Documentation in the Doc dir skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

5 participants

@AlexWaygood @Fidget-Spinner @ambv @the-knights-who-say-ni @bedevere-bot
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.