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-45680: Clarify documentation on ``GenericAlias`` objects by AlexWaygood · Pull Request #29335 · python/cpython

Conversation

@AlexWaygood

@AlexWaygood AlexWaygood commented Oct 30, 2021 •
edited
Loading

Uh oh!

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

Copy link
Copy Markdown
Member

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.

The PR also proposes some changes to the list of standard library classes that
define __class_getitem__. This PR proposes adding several classes to the list,
to make it somewhat more complete. However, more importantly, it attempts
to clarify that the list is not intended to be an exhaustive enumeration of
every single standard-library class that defined __class_getitem__.

See also: initial discussion of issues with this piece of documentation in
#29308, and previous BPO issue 42280.

https://bugs.python.org/issue45680

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@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).
@bedevere-bot bedevere-bot added the docs Documentation in the Doc dir label Oct 30, 2021
@the-knights-who-say-ni the-knights-who-say-ni added the CLA signed label Oct 30, 2021
@bedevere-bot bedevere-bot added the awaiting review label Oct 30, 2021
@AlexWaygood
Correct typo
cef0930
AlexWaygood
AlexWaygood commented Oct 30, 2021
View reviewed changes
Comment thread Doc/library/stdtypes.rst
containers' classes may call the classmethod :meth:`__class_getitem__` of the
class instead. The classmethod :meth:`__class_getitem__` should return a
``GenericAlias`` object.
``GenericAlias`` objects are generally created by

@AlexWaygood AlexWaygood Oct 30, 2021

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I changed the wording from "are created by subscripting a class" to "are generally created by subscripting a class". This is because it is certainly possible to directly instantiate a GenericAlias object through types.GenericAlias, as this documentation states later on.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/library/stdtypes.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
AlexWaygood
AlexWaygood commented Oct 31, 2021
View reviewed changes
Comment thread Doc/library/stdtypes.rst
Comment on lines 4991 to +5013
* :class:`collections.abc.ValuesView`
* :class:`contextlib.AbstractContextManager`
* :class:`contextlib.AbstractAsyncContextManager`
* :class:`dataclasses.Field`
* :class:`functools.cached_property`
* :class:`functools.partialmethod`
* :class:`os.PathLike`
* :class:`pathlib.Path`
* :class:`pathlib.PurePath`
* :class:`pathlib.PurePosixPath`
* :class:`pathlib.PureWindowsPath`
* :class:`queue.LifoQueue`
* :class:`queue.Queue`
* :class:`queue.PriorityQueue`
* :class:`queue.SimpleQueue`
* :ref:`re.Pattern <re-objects>`
* :ref:`re.Match <match-objects>`
* :class:`shelve.Shelf`
* :class:`types.MappingProxyType`
* :class:`weakref.WeakKeyDictionary`
* :class:`weakref.WeakMethod`
* :class:`weakref.WeakSet`
* :class:`weakref.WeakValueDictionary`

@AlexWaygood AlexWaygood Oct 31, 2021

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Fidget-Spinner, is this list currently in any particular order at all? 🙂 I can think of a few possible orderings that might work:

  1. Fully alphabetise the list
  2. Go through the modules in alphabetical order, but list classes within each module according to the order they appear in in the module's __all__.
  3. Something else?

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@AlexWaygood
Add more shelve classes
614fce5
@erlend-aasland
erlend-aasland requested a review from Fidget-Spinner October 31, 2021 19:47
erlend-aasland
erlend-aasland reviewed Nov 1, 2021
View reviewed changes

@erlend-aasland erlend-aasland left a comment

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I left some remarks. Generally looks good, but I do not use the typing features of Python, so I'll wisely keep my mouth shut regarding most of these changes ;)

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
AlexWaygood reacted with laugh emoji
All reactions
  • 😄 1 reaction
Comment thread Doc/library/stdtypes.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/library/stdtypes.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Fidget-Spinner
Fidget-Spinner reviewed Nov 1, 2021
View reviewed changes

@Fidget-Spinner Fidget-Spinner left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I won't be able to respond so quickly due to IRL stuff. Sorry if I take a week or more!

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
AlexWaygood reacted with thumbs up emoji
All reactions
  • 👍 1 reaction
Comment thread Doc/library/stdtypes.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/library/stdtypes.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/library/stdtypes.rst Resolved

Uh oh!

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

AlexWaygood commented Nov 1, 2021

Copy link
Copy Markdown
Member Author

I won't be able to respond so quickly due to IRL stuff. Sorry if I take a week or more!

Of course, no worries! Apologies it ended up being such a large PR!
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
AlexWaygood and others added 2 commits November 1, 2021 13:23
@AlexWaygood Erlend Egeberg Aasland
Remove brackets
74269b8 
Co-authored-by: Erlend Egeberg Aasland <[email protected]>
@AlexWaygood
Add link to container classes, remove use of the word 'they'
671579b
AlexWaygood
AlexWaygood commented Nov 1, 2021
View reviewed changes
Comment thread Doc/library/stdtypes.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
AlexWaygood
AlexWaygood commented Nov 1, 2021
View reviewed changes
Comment thread Doc/library/stdtypes.rst
^^^^^^^^^^^^^^^^^^^^^^^^

These standard library collections support parameterized generics.
The following standard library classes support parameterized generics. This

@AlexWaygood AlexWaygood Nov 1, 2021 •
edited
Loading

Uh oh!

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

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There was discussion on the previous PR that I opened on how to introduce this list. @ambv suggested "The following standard library data structures [...]" — I've gone for "The following standard library classes [...]" as I think the definition of "class" is probably easier to grok than the definition of "data structure".

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
AlexWaygood added 2 commits November 2, 2021 09:51
@AlexWaygood
Improve cross-references to data model docs
d367338
@AlexWaygood
Move example to __class_getitem__ docs in the data model
d945e06
AlexWaygood
AlexWaygood commented Nov 2, 2021
View reviewed changes
Comment thread Doc/library/stdtypes.rst
Comment on lines -4829 to -4838
Usually, the :ref:`subscription <subscriptions>` of container objects calls the
method :meth:`__getitem__` of the object. However, the subscription of some
containers' classes may call the classmethod :meth:`__class_getitem__` of the
class instead. The classmethod :meth:`__class_getitem__` should return a
``GenericAlias`` object.

.. note::
If the :meth:`__getitem__` of the class' metaclass is present, it will take
precedence over the :meth:`__class_getitem__` defined in the class (see
:pep:`560` for more details).

@AlexWaygood AlexWaygood Nov 2, 2021 •
edited
Loading

Uh oh!

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

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This material has been moved to the docs for __class_getitem__ in the data model, per @Fidget-Spinner's suggestion (see #29389)

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@AlexWaygood
revert line 4813
629a29d
@AlexWaygood
AlexWaygood requested a review from Fidget-Spinner November 2, 2021 11:33
AlexWaygood added 2 commits November 2, 2021 13:04
@AlexWaygood
More instances where it is implied that only containers can be parame…
5dd309c 
…terised
@AlexWaygood
Improve references in glossary and typing docs
5dbccad
@AlexWaygood
AlexWaygood requested a review from gvanrossum as a code owner November 2, 2021 13:38
@AlexWaygood
Fix typing docs link to __class_getitem__ method
bc457dd
@AlexWaygood AlexWaygood changed the title bpo-45680: Clarify documentation on GenericAlias objects bpo-45680: Clarify documentation on GenericAlias objects and __class_getitem__ Nov 2, 2021
AlexWaygood added 2 commits November 2, 2021 17:45
@AlexWaygood
Add note about typing.Generic
d398971
@AlexWaygood
Merge branch 'generic-alias-docs' of https://github.com/AlexWaygood/c…
a195216 
…python into generic-alias-docs
@gvanrossum

gvanrossum commented Nov 3, 2021

Copy link
Copy Markdown
Member

I hope it's okay if I leave this PR in the capable hands of @Fidget-Spinner .
Fidget-Spinner and AlexWaygood reacted with thumbs up emoji
All reactions
  • 👍 2 reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@gvanrossum
gvanrossum removed their request for review November 3, 2021 03:23
@bedevere-bot bedevere-bot added awaiting merge and removed awaiting review labels Dec 5, 2021
@Fidget-Spinner
Fidget-Spinner requested a review from ambv December 5, 2021 23:44
@AlexWaygood

This comment has been minimized.

Sign in to view
@AlexWaygood AlexWaygood added needs backport to 3.9 labels Dec 6, 2021
remykarem pushed a commit to remykarem/cpython that referenced this pull request Dec 7, 2021
@AlexWaygood remykarem
[doc] bpo-45680: Disambiguate __getitem__ and ``__class_getitem__…
0fd630b 
…`` in the data model (pythonGH-29389)

The documentation explaining Python's data model does not adequately explain
the differences between ``__getitem__`` and ``__class_getitem__``, nor does it
explain when each is called. There is an attempt at explaining
``__class_getitem__`` in the documentation for ``GenericAlias`` objects, but
this does not give sufficient clarity into how the method works. Moreover, it
is the wrong place for that information to be found; the explanation of
``__class_getitem__`` should be in the documentation explaining the data model.

This PR has been split off from pythonGH-29335.
@AlexWaygood

AlexWaygood commented Dec 20, 2021

Copy link
Copy Markdown
Member Author

Friendly ping, @ambv 🙂
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
kumaraditya303
kumaraditya303 reviewed Dec 20, 2021
View reviewed changes
Comment thread Doc/library/stdtypes.rst Resolved

Uh oh!

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

AlexWaygood commented Jan 15, 2022

Copy link
Copy Markdown
Member Author

Ping, @ambv, @Fidget-Spinner 🙂 any chance of getting this merged soon?
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
Fidget-Spinner
Fidget-Spinner reviewed Jan 19, 2022
View reviewed changes

@Fidget-Spinner Fidget-Spinner left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor formatting suggestions, I will apply them myself then merge.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
AlexWaygood reacted with heart emoji
All reactions
  • ❤️ 1 reaction
Comment thread Doc/library/stdtypes.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/library/stdtypes.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/library/stdtypes.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/library/stdtypes.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@Fidget-Spinner
Apply formatting suggestions from code review
3944e8c
@Fidget-Spinner
Fidget-Spinner merged commit 0eae9a2 into python:main Jan 19, 2022
@miss-islington

miss-islington commented Jan 19, 2022

Copy link
Copy Markdown
Contributor

Thanks @AlexWaygood for the PR, and @Fidget-Spinner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.9, 3.10.
🐍🍒⛏🤖
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-bot bedevere-bot removed the awaiting merge label Jan 19, 2022
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]>
@miss-islington

miss-islington commented Jan 19, 2022

Copy link
Copy Markdown
Contributor

Sorry, @AlexWaygood and @Fidget-Spinner, I could not cleanly backport this to 3.9 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 0eae9a2a2db6cc5a72535f61bb988cc417011640 3.9
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@miss-islington miss-islington assigned Fidget-Spinner Jan 19, 2022
@bedevere-bot

bedevere-bot commented Jan 19, 2022

Copy link
Copy Markdown

GH-30688 is a backport of this pull request to the 3.10 branch.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-bot bedevere-bot removed the needs backport to 3.10 label Jan 19, 2022
@AlexWaygood
AlexWaygood deleted the generic-alias-docs branch January 19, 2022 14:54
@AlexWaygood

AlexWaygood commented Jan 19, 2022

Copy link
Copy Markdown
Member Author

Hooray! Thanks, @Fidget-Spinner 😀
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
Fidget-Spinner
Fidget-Spinner reviewed Jan 19, 2022
View reviewed changes

@Fidget-Spinner Fidget-Spinner left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@AlexWaygood no problem. Thanks for your patience and seeing this through.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/library/stdtypes.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
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]>
@bedevere-bot bedevere-bot removed the needs backport to 3.9 label Jan 19, 2022
@bedevere-bot

bedevere-bot commented Jan 19, 2022

Copy link
Copy Markdown

GH-30689 is a backport of this pull request to the 3.9 branch.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
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

@erlend-aasland erlend-aasland erlend-aasland left review comments
@Fidget-Spinner Fidget-Spinner Fidget-Spinner approved these changes
@kumaraditya303 kumaraditya303 kumaraditya303 left review comments
@ambv ambv Awaiting requested review from ambv
+1 more reviewer
@TeamSpen210 TeamSpen210 TeamSpen210 left review comments
Reviewers whose approvals may not affect merge requirements

Uh oh!

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

Assignees

@Fidget-Spinner Fidget-Spinner

Labels

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.

9 participants

@AlexWaygood @gvanrossum @Fidget-Spinner @miss-islington @bedevere-bot @TeamSpen210 @erlend-aasland @kumaraditya303 @the-knights-who-say-ni
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.