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 — [doc] bpo-45680: Disambiguate ``__getitem__`` and ``__class_getitem__`` in the data model. by AlexWaygood · Pull Request #29389 · python/cpython

Conversation

@AlexWaygood

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

Uh oh!

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

Copy link
Copy Markdown
Member

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

Sorry, something went wrong.

Uh oh!

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

All reactions
AlexWaygood added 2 commits November 3, 2021 14:37
@AlexWaygood
[doc] bpo-45680: Disambiguate __getitem__ and ``__class_getitem__…
020d168
…`` 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.
@AlexWaygood
Update 2021-11-03-14-30-55.bpo-45680.UBpWzY.rst
fe66943
@the-knights-who-say-ni the-knights-who-say-ni added the CLA signed label Nov 3, 2021
@bedevere-bot bedevere-bot added docs Documentation in the Doc dir awaiting review labels Nov 3, 2021
@AlexWaygood AlexWaygood mentioned this pull request Nov 3, 2021
bpo-45680: Clarify documentation on GenericAlias objects #29335
Merged
@AlexWaygood
Delete news entry
32d7751
@Fidget-Spinner Fidget-Spinner added the skip news label Nov 4, 2021
Fidget-Spinner
Fidget-Spinner reviewed Nov 4, 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.

Great job!

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/reference/datamodel.rst Resolved

Uh oh!

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

Comment thread Doc/reference/datamodel.rst Resolved

Uh oh!

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

Comment thread Doc/reference/datamodel.rst Resolved

Uh oh!

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

@Fidget-Spinner
Fidget-Spinner requested a review from ambv November 4, 2021 06:30
@AlexWaygood 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
@AlexWaygood
Address review
efa0731
@AlexWaygood
AlexWaygood requested a review from Fidget-Spinner November 4, 2021 11:46
@AlexWaygood

AlexWaygood commented Nov 4, 2021

Copy link
Copy Markdown
Member Author

Great job!

Thank you <3

All reactions

Sorry, something went wrong.

Uh oh!

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

@AlexWaygood
Improve links to typing docs
7ae4fac
@AlexWaygood
AlexWaygood requested a review from gvanrossum as a code owner November 4, 2021 12:27
@AlexWaygood
Add link to glossary definition
8bc6b7c
@gvanrossum
gvanrossum removed their request for review November 4, 2021 13:54
ambv
ambv reviewed Nov 6, 2021
View reviewed changes

@ambv ambv 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.

This is pretty cool, thanks for being so thorough.

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/reference/datamodel.rst Resolved

Uh oh!

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

Comment thread Doc/reference/datamodel.rst Resolved

Uh oh!

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

Comment thread Doc/reference/datamodel.rst Resolved

Uh oh!

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

Comment thread Doc/reference/datamodel.rst Resolved

Uh oh!

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

Comment thread Doc/reference/datamodel.rst Resolved

Uh oh!

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

Comment thread Doc/reference/datamodel.rst Resolved

Uh oh!

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

@AlexWaygood
Address second review
b01b0c9
@AlexWaygood

AlexWaygood commented Nov 7, 2021

Copy link
Copy Markdown
Member Author

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

All reactions

Sorry, something went wrong.

Uh oh!

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

@AlexWaygood
Revise changes to __getitem__
ca568d5
AlexWaygood
AlexWaygood commented Nov 7, 2021
View reviewed changes
Comment thread 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,

@AlexWaygood AlexWaygood Nov 7, 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.

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

Sorry, something went wrong.

Uh oh!

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

All reactions
Comment thread Doc/reference/datamodel.rst
Comment on lines +2285 to +2302
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"
)

@AlexWaygood AlexWaygood Nov 7, 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.

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

Sorry, something went wrong.

Uh oh!

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

All reactions
@AlexWaygood
AlexWaygood requested a review from ambv November 7, 2021 22:40
@AlexWaygood
Improve code snippet
c1955d7
@AlexWaygood AlexWaygood mentioned this pull request Nov 8, 2021
bpo-45680: Improve docs on subscriptions w.r.t. GenericAlias objects #29479
Merged
@AlexWaygood
Remove trailing whitespace
ace22fd
@AlexWaygood

AlexWaygood commented Nov 9, 2021

Copy link
Copy Markdown
Member Author

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.

All reactions

Sorry, something went wrong.

Uh oh!

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

@AlexWaygood
Fix CI failures
f8ea20a
@ambv
ambv merged commit 31b3a70 into python:main Nov 18, 2021
@bedevere-bot bedevere-bot removed the awaiting review label Nov 18, 2021
@ambv ambv added needs backport to 3.9 labels Nov 18, 2021
@miss-islington

miss-islington commented Nov 18, 2021

Copy link
Copy Markdown
Contributor

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

All reactions

Sorry, something went wrong.

Uh oh!

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

@miss-islington

miss-islington commented Nov 18, 2021

Copy link
Copy Markdown
Contributor

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!

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.9 label Nov 18, 2021
@bedevere-bot

bedevere-bot commented Nov 18, 2021

Copy link
Copy Markdown

GH-29619 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 pushed a commit to miss-islington/cpython that referenced this pull request Nov 18, 2021
@AlexWaygood @miss-islington
[doc] bpo-45680: Disambiguate __getitem__ and ``__class_getitem__…
e7f1f22
…`` 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

bedevere-bot commented Nov 18, 2021

Copy link
Copy Markdown

GH-29620 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 Nov 18, 2021
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Nov 18, 2021
@AlexWaygood @miss-islington
[doc] bpo-45680: Disambiguate __getitem__ and ``__class_getitem__…
2822e03
…`` 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]>
ambv added a commit that referenced this pull request Nov 18, 2021
@miss-islington @AlexWaygood @ambv
[3.10] [doc] bpo-45680: Disambiguate __getitem__ and ``__class_ge…
fde9f61
…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]>
ambv added a commit that referenced this pull request Nov 18, 2021
@miss-islington @AlexWaygood @ambv
[3.9] [doc] bpo-45680: Disambiguate __getitem__ and ``__class_get…
591bf41
…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]>
@AlexWaygood
AlexWaygood deleted the class_getitem-docs branch November 18, 2021 17:52
@JulienPalard JulienPalard mentioned this pull request Nov 19, 2021
bpo-42238: [doc]: Hide false positive in make suspicious. #29636
Merged
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.
@JulienPalard JulienPalard mentioned this pull request Apr 8, 2022
Check for false positives sphinx-contrib/sphinx-lint#21
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Fidget-Spinner Fidget-Spinner Awaiting requested review from Fidget-Spinner
@ambv ambv Awaiting requested review from ambv

Uh oh!

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

Assignees

No one assigned

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.

6 participants

@AlexWaygood @miss-islington @bedevere-bot @ambv @Fidget-Spinner @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.