bpo-45680: Clarify documentation on `GenericAlias` objects #29335

AlexWaygood · 2021-10-30T20:44:40Z

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

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 · 2021-10-30T21:12:05Z

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


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.

Doc/library/stdtypes.rst

AlexWaygood · 2021-10-31T09:47:30Z

Doc/library/stdtypes.rst

 * :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`


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

Fully alphabetise the list

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__.

Something else?

erlend-aasland

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 ;)

Doc/library/stdtypes.rst

Fidget-Spinner

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

Doc/library/stdtypes.rst

AlexWaygood · 2021-11-01T12:15:08Z

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!

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@innova.no>

Doc/library/stdtypes.rst

AlexWaygood · 2021-11-01T19:27:29Z

Doc/library/stdtypes.rst


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


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".

AlexWaygood · 2021-11-02T11:25:55Z

Doc/library/stdtypes.rst

-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).


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

…terised

…python into generic-alias-docs

gvanrossum · 2021-11-03T03:23:22Z

I hope it's okay if I leave this PR in the capable hands of @Fidget-Spinner .

Fidget-Spinner

LGTM. Paging @ambv for a review too please.

…`` 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 · 2021-12-20T06:34:14Z

Friendly ping, @ambv 🙂

Doc/library/stdtypes.rst

AlexWaygood · 2022-01-15T10:05:03Z

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

Fidget-Spinner

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

Doc/library/stdtypes.rst

miss-islington · 2022-01-19T14:53:44Z

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

…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 <erlend.aasland@innova.no> Co-authored-by: Ken Jin <28750310+Fidget-Spinner@users.noreply.github.com> (cherry picked from commit 0eae9a2) Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

miss-islington · 2022-01-19T14:53:51Z

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

bedevere-bot · 2022-01-19T14:53:55Z

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

AlexWaygood · 2022-01-19T14:55:59Z

Hooray! Thanks, @Fidget-Spinner 😀

Fidget-Spinner

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

Doc/library/stdtypes.rst

…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 <erlend.aasland@innova.no> Co-Authored-By: Ken Jin <28750310+Fidget-Spinner@users.noreply.github.com> Co-Authored-By: Alex Waygood <Alex.Waygood@Gmail.com>

bedevere-bot · 2022-01-19T15:10:15Z

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

…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 <erlend.aasland@innova.no> Co-authored-by: Ken Jin <28750310+Fidget-Spinner@users.noreply.github.com> (cherry picked from commit 0eae9a2) Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com> Automerge-Triggered-By: GH:Fidget-Spinner

…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 <erlend.aasland@innova.no> Co-Authored-By: Ken Jin <28750310+Fidget-Spinner@users.noreply.github.com> Co-Authored-By: Alex Waygood <Alex.Waygood@Gmail.com>

…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 <erlend.aasland@innova.no> Co-authored-by: Ken Jin <28750310+Fidget-Spinner@users.noreply.github.com>

bedevere-bot added the docs label Oct 30, 2021

the-knights-who-say-ni added the CLA signed label Oct 30, 2021

bedevere-bot added the awaiting review label Oct 30, 2021

Correct typo

cef0930

AlexWaygood reviewed Oct 30, 2021

View changes

AlexWaygood reviewed Oct 31, 2021

View changes

Add more shelve classes

614fce5

erlend-aasland requested a review from Fidget-Spinner Oct 31, 2021

erlend-aasland reviewed Nov 1, 2021

View changes

Doc/library/stdtypes.rst Outdated Show resolved Hide resolved

Doc/library/stdtypes.rst Outdated Show resolved Hide resolved

Fidget-Spinner reviewed Nov 1, 2021

View changes

Doc/library/stdtypes.rst Outdated Show resolved Hide resolved

Doc/library/stdtypes.rst Outdated Show resolved Hide resolved

Doc/library/stdtypes.rst Outdated Show resolved Hide resolved

AlexWaygood and others added 2 commits Nov 1, 2021

Remove brackets

74269b8

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@innova.no>

Add link to container classes, remove use of the word 'they'

671579b

AlexWaygood reviewed Nov 1, 2021

View changes

Doc/library/stdtypes.rst Outdated Show resolved Hide resolved

AlexWaygood reviewed Nov 1, 2021

View changes

AlexWaygood added 2 commits Nov 2, 2021

Improve cross-references to data model docs

d367338

Move example to __class_getitem__ docs in the data model

d945e06

AlexWaygood reviewed Nov 2, 2021

View changes

revert line 4813

629a29d

AlexWaygood requested a review from Fidget-Spinner Nov 2, 2021

AlexWaygood added 2 commits Nov 2, 2021

More instances where it is implied that only containers can be parame…

5dd309c

…terised

Improve references in glossary and typing docs

5dbccad

AlexWaygood requested a review from gvanrossum as a code owner Nov 2, 2021

Fix typing docs link to __class_getitem__ method

bc457dd

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 Nov 2, 2021

Add note about typing.Generic

d398971

Merge branch 'generic-alias-docs' of https://github.com/AlexWaygood/c…

a195216

…python into generic-alias-docs

gvanrossum removed their request for review Nov 3, 2021

Fidget-Spinner approved these changes Dec 5, 2021

View changes

bedevere-bot added awaiting merge and removed awaiting review labels Dec 5, 2021

Fidget-Spinner requested a review from ambv Dec 5, 2021

This comment has been minimized.

Sign in to view

AlexWaygood added needs backport to 3.9 needs backport to 3.10 labels Dec 6, 2021

kumaraditya303 reviewed Dec 20, 2021

View changes

Doc/library/stdtypes.rst Show resolved Hide resolved

Fidget-Spinner reviewed Jan 19, 2022

View changes

Doc/library/stdtypes.rst Outdated Show resolved Hide resolved

Doc/library/stdtypes.rst Outdated Show resolved Hide resolved

Doc/library/stdtypes.rst Outdated Show resolved Hide resolved

Doc/library/stdtypes.rst Outdated Show resolved Hide resolved

Apply formatting suggestions from code review

3944e8c

Fidget-Spinner merged commit 0eae9a2 into python:main Jan 19, 2022
12 checks passed

bedevere-bot removed the awaiting merge label Jan 19, 2022

miss-islington assigned Fidget-Spinner Jan 19, 2022

bedevere-bot removed the needs backport to 3.10 label Jan 19, 2022

AlexWaygood deleted the generic-alias-docs branch Jan 19, 2022

Fidget-Spinner reviewed Jan 19, 2022

View changes

Doc/library/stdtypes.rst Show resolved Hide resolved

bedevere-bot removed the needs backport to 3.9 label Jan 19, 2022

python / cpython Public

bpo-45680: Clarify documentation on `GenericAlias` objects #29335

bpo-45680: Clarify documentation on `GenericAlias` objects #29335

AlexWaygood commented Oct 30, 2021 •

edited

AlexWaygood Oct 30, 2021

AlexWaygood Oct 31, 2021

erlend-aasland left a comment

Fidget-Spinner left a comment

AlexWaygood commented Nov 1, 2021

AlexWaygood Nov 1, 2021 •

edited

AlexWaygood Nov 2, 2021 •

edited

gvanrossum commented Nov 3, 2021

Fidget-Spinner left a comment

This comment has been minimized.

AlexWaygood commented Dec 20, 2021

AlexWaygood commented Jan 15, 2022

Fidget-Spinner left a comment

miss-islington commented Jan 19, 2022

miss-islington commented Jan 19, 2022

bedevere-bot commented Jan 19, 2022

AlexWaygood commented Jan 19, 2022

Fidget-Spinner left a comment

bedevere-bot commented Jan 19, 2022


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

python / cpython Public

bpo-45680: Clarify documentation on GenericAlias objects #29335

bpo-45680: Clarify documentation on GenericAlias objects #29335

Conversation

AlexWaygood commented Oct 30, 2021 • edited

AlexWaygood Oct 30, 2021

Choose a reason for hiding this comment

AlexWaygood Oct 31, 2021

Choose a reason for hiding this comment

erlend-aasland left a comment

Fidget-Spinner left a comment

AlexWaygood commented Nov 1, 2021

AlexWaygood Nov 1, 2021 • edited

Choose a reason for hiding this comment

AlexWaygood Nov 2, 2021 • edited

Choose a reason for hiding this comment

gvanrossum commented Nov 3, 2021

Fidget-Spinner left a comment

This comment has been minimized.

AlexWaygood commented Dec 20, 2021

AlexWaygood commented Jan 15, 2022

Fidget-Spinner left a comment

miss-islington commented Jan 19, 2022

miss-islington commented Jan 19, 2022

bedevere-bot commented Jan 19, 2022

AlexWaygood commented Jan 19, 2022

Fidget-Spinner left a comment

bedevere-bot commented Jan 19, 2022

bpo-45680: Clarify documentation on `GenericAlias` objects #29335

bpo-45680: Clarify documentation on `GenericAlias` objects #29335

AlexWaygood commented Oct 30, 2021 •

edited

AlexWaygood Nov 1, 2021 •

edited

AlexWaygood Nov 2, 2021 •

edited