[doc] bpo-45680: Disambiguate ``__getitem__`` and ``__class_getitem__`` in the data model. by AlexWaygood · Pull Request #29389 · python/cpython

AlexWaygood · 2021-11-03T14:56:03Z

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 #29335.

https://bugs.python.org/issue45680

…`` in the data model. 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 python#29335.

Fidget-Spinner

Great job!

AlexWaygood · 2021-11-04T11:47:51Z

Great job!

Thank you <3

ambv

This is pretty cool, thanks for being so thorough.

AlexWaygood · 2021-11-07T22:21:06Z

This is pretty cool, thanks for being so thorough.

Massive thanks for the detailed review! I've rewritten large chunks in response 😅

(Wow, writing documentation is hard!)

AlexWaygood · 2021-11-07T22:37:35Z

+
+Usually, the :ref:`subscription<subscriptions>` of an object using square
+brackets will call the :meth:`~object.__getitem__` instance method defined on
+the object's class. However, if the object being subscribed is itself a class,


Should it be "object being subscribed", or "object being subscripted"?

AlexWaygood · 2021-11-07T22:38:12Z

+ def subscribe(obj, x):
+ class_of_obj = type(obj)
+
+ # If the class of `obj` defines `__getitem__()`,
+ # call `type(obj).__getitem__()`
+ if hasattr(class_of_obj, '__getitem__'):
+ return class_of_obj.__getitem__(obj, x)
+
+ # Else, if `obj` defines `__class_getitem__()`,
+ # call `obj.__class_getitem__()`
+ elif hasattr(obj, '__class_getitem__'):
+ return obj.__class_getitem__(x)
+
+ # Else, raise an exception
+ else:
+ raise TypeError(
+ f"'{class_of_obj.__name__}' object is not subscriptable"
+ )


Please correct me if this isn't quite right -- I'm in a little over my head here!

AlexWaygood · 2021-11-09T16:05:49Z

Okay, the CI failures are because rstlint.py reckons I've applied bad markup in lines 2292, 2297, 2315, 2323, 2337 and 2340. All of these are because rstlint sees things like "`obj`" and raises an error, because it reckons that it should either be something like "``obj``" or ":class:`obj`" -- it doesn't realise that I'm not actually trying to apply reStructuredText markup at all, as these are all inside comments inside code blocks.

miss-islington · 2021-11-18T15:54:42Z

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

miss-islington · 2021-11-18T15:54:43Z

Thanks @AlexWaygood for the PR, and @ambv for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

bedevere-bot · 2021-11-18T15:54:57Z

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

…`` 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. (cherry picked from commit 31b3a70) Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

bedevere-bot · 2021-11-18T15:55:03Z

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

…`` 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. (cherry picked from commit 31b3a70) Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

…titem__`` in the data model (GH-29389) (GH-29620) 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 GH-29335. (cherry picked from commit 31b3a70) Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com> Co-authored-by: Łukasz Langa <lukasz@langa.pl>

…item__`` in the data model (GH-29389) (GH-29619) 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 GH-29335. (cherry picked from commit 31b3a70) Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com> Co-authored-by: Łukasz Langa <lukasz@langa.pl>

…`` 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 added 2 commits November 3, 2021 14:37

Update 2021-11-03-14-30-55.bpo-45680.UBpWzY.rst
fe66943

the-knights-who-say-ni added the CLA signed label Nov 3, 2021

bedevere-bot added docs Documentation in the Doc dir awaiting review labels Nov 3, 2021

AlexWaygood mentioned this pull request Nov 3, 2021
bpo-45680: Clarify documentation on GenericAlias objects #29335
Merged

Delete news entry
32d7751

Fidget-Spinner added the skip news label Nov 4, 2021

Fidget-Spinner reviewed Nov 4, 2021
View reviewed changes

Comment threadDoc/reference/datamodel.rst Outdated
Comment threadDoc/reference/datamodel.rst Outdated
Comment threadDoc/reference/datamodel.rst Outdated

Fidget-Spinner requested a review from ambv November 4, 2021 06:30

AlexWaygood changed the title ~~[doc] bpo-45680: Disambiguate __getitem__ and __class_getitem__ in the data model.~~[doc] bpo-45680: Disambiguate __getitem__ and __class_getitem__ in the data model.Nov 4, 2021

Address review
efa0731

AlexWaygood requested a review from Fidget-Spinner November 4, 2021 11:46

Improve links to typing docs
7ae4fac

AlexWaygood requested a review from gvanrossum as a code owner November 4, 2021 12:27

Add link to glossary definition
8bc6b7c

gvanrossum removed their request for review November 4, 2021 13:54

ambv reviewed Nov 6, 2021
View reviewed changes

Address second review
b01b0c9

Revise changes to __getitem__
ca568d5

AlexWaygood commented Nov 7, 2021
View reviewed changes

AlexWaygood requested a review from ambv November 7, 2021 22:40

Improve code snippet
c1955d7

AlexWaygood mentioned this pull request Nov 8, 2021
bpo-45680: Improve docs on subscriptions w.r.t. GenericAlias objects #29479
Merged

Remove trailing whitespace
ace22fd

Fix CI failures
f8ea20a

ambv merged commit 31b3a70 into python:mainNov 18, 2021

bedevere-bot removed the awaiting review label Nov 18, 2021

ambv added needs backport to 3.9 needs backport to 3.10 only security fixes labels Nov 18, 2021

bedevere-bot removed the needs backport to 3.9 label Nov 18, 2021

bedevere-bot removed the needs backport to 3.10 only security fixes label Nov 18, 2021

AlexWaygood deleted the class_getitem-docs branch November 18, 2021 17:52

JulienPalard mentioned this pull request Nov 19, 2021
bpo-42238: [doc]: Hide false positive in make suspicious. #29636
Merged

JulienPalard mentioned this pull request Apr 8, 2022
Check for false positives sphinx-contrib/sphinx-lint#21
Closed

Uh oh!

Uh oh!

Conversation

AlexWaygood commented Nov 3, 2021• edited by bedevere-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Fidget-Spinner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AlexWaygood commented Nov 4, 2021

Uh oh!

ambv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AlexWaygood commented Nov 7, 2021

Uh oh!

AlexWaygoodNov 7, 2021

Choose a reason for hiding this comment

Uh oh!

AlexWaygoodNov 7, 2021• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlexWaygood commented Nov 9, 2021

Uh oh!

miss-islington commented Nov 18, 2021

Uh oh!

miss-islington commented Nov 18, 2021

Uh oh!

bedevere-bot commented Nov 18, 2021

Uh oh!

bedevere-bot commented Nov 18, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

AlexWaygood commented Nov 3, 2021•
edited by bedevere-bot
Loading

AlexWaygoodNov 7, 2021•
edited
Loading