[doc] bpo-45680: Disambiguate `getitem` and `__class_getitem__` in the data model. #29389

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!

Doc/reference/datamodel.rst

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

Great job!

Thank you <3

ambv

This is pretty cool, thanks for being so thorough.

Doc/reference/datamodel.rst

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

Doc/reference/datamodel.rst

+
+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

Doc/reference/datamodel.rst

+   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 <[email protected]>

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 <[email protected]>

…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 <[email protected]> Co-authored-by: Łukasz Langa <[email protected]>

…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 <[email protected]> Co-authored-by: Łukasz Langa <[email protected]>

…`` 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

Doc/reference/datamodel.rst Outdated Show resolved Hide resolved

Doc/reference/datamodel.rst Outdated Show resolved Hide resolved

Doc/reference/datamodel.rst Outdated Show resolved Hide resolved

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:main Nov 18, 2021

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

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

bedevere-bot removed the needs backport to 3.9 only security fixes 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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[doc] bpo-45680: Disambiguate `getitem` and `__class_getitem__` in the data model. #29389

[doc] bpo-45680: Disambiguate `getitem` and `__class_getitem__` in the data model. #29389

AlexWaygood commented Nov 3, 2021 •

edited by bedevere-bot

Loading

Fidget-Spinner left a comment

AlexWaygood commented Nov 4, 2021

ambv left a comment

AlexWaygood commented Nov 7, 2021

AlexWaygood Nov 7, 2021

AlexWaygood Nov 7, 2021 •

edited

Loading

AlexWaygood commented Nov 9, 2021

miss-islington commented Nov 18, 2021

miss-islington commented Nov 18, 2021

bedevere-bot commented Nov 18, 2021

bedevere-bot commented Nov 18, 2021

[doc] bpo-45680: Disambiguate __getitem__ and __class_getitem__ in the data model. #29389

[doc] bpo-45680: Disambiguate __getitem__ and __class_getitem__ in the data model. #29389

Conversation

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

Fidget-Spinner left a comment

Choose a reason for hiding this comment

AlexWaygood commented Nov 4, 2021

ambv left a comment

Choose a reason for hiding this comment

AlexWaygood commented Nov 7, 2021

AlexWaygood Nov 7, 2021

Choose a reason for hiding this comment

AlexWaygood Nov 7, 2021 • edited Loading

Choose a reason for hiding this comment

AlexWaygood commented Nov 9, 2021

miss-islington commented Nov 18, 2021

miss-islington commented Nov 18, 2021

bedevere-bot commented Nov 18, 2021

bedevere-bot commented Nov 18, 2021

[doc] bpo-45680: Disambiguate `getitem` and `__class_getitem__` in the data model. #29389

[doc] bpo-45680: Disambiguate `getitem` and `__class_getitem__` in the data model. #29389

AlexWaygood commented Nov 3, 2021 •

edited by bedevere-bot

Loading

AlexWaygood Nov 7, 2021 •

edited

Loading