bpo-45680: Improve docs on subscriptions w.r.t. GenericAlias objects

[AlexWaygood]

This PR is part of the project to improve documentation on GenericAlias objects and __class_getitem__, started in #29335.

https://bugs.python.org/issue45680

[AlexWaygood]

@JelleZijlstra, reckon this can be merged soon? :)

[JelleZijlstra]

Looking at this again I'm not so sure, sorry. This adds more text than was there before, but the new text is a little repetitive. I do like the additional links though.

I feel like a broader problem with the language reference is that it veers too much into describing how concrete built-in types handle an operation, and not enough into how exactly the operation works. Here, for example, there is no precise description of when __class_getitem__ is called instead of __getitem__. That description exists only in the docs for __class_getitem__, but logically it should be part of the description of the subscript operator. The fact that the key is a tuple unless there is exactly one element shows up in a parenthetical in the text around mappings. (It's also wrong: obj[1,] is a tuple key, not an integer. The next section on slicing gets this right.) Also, type[int] works through deep magic in the interpreter, since type has neither a __getitem__ nor a __class_getitem__ magic, but nothing in the reference mentions this.

[JelleZijlstra]

See also bpo-46754.

[AlexWaygood]

Looking at this again I'm not so sure, sorry.

Thanks for taking a look! I'll have a think tomorrow about whether I want to try revising this PR, or just close it.

[AlexWaygood]

Here, for example, there is no precise description of when __class_getitem__ is called instead of __getitem__. That description exists only in the docs for __class_getitem__, but logically it should be part of the description of the subscript operator.

Perhaps you're right that that information might be better found in this document, but tbqh I don't have the energy to move that section from the data model to here after spending so long adding that section to the data model in GH-29389 :(

[AlexWaygood]

@JelleZijlstra I've had another bash at it. I've tried to make the section less repetitive and increase the accuracy of the section regarding the "expression list".

The core aims of this PR are to:

1. Make more prominent mention of the fact that subscriptions can also result in __class_getitem__ being called, as well as __getitem__.
2. Add more links to to docs elsewhere on __class_getitem__.

[JelleZijlstra]

Thanks! Just one comment.

[JelleZijlstra]

Seems weird to link this to sequence types. Maybe just drop the link? The later explanation is clearer about sequences and mappings.

Suggested change

	The subscription of an instance of a :ref:`container class <sequence-types>`
	The subscription of an instance of a container class

[AlexWaygood]

I think the section in the docs linked to with sequence-types perhaps originally only discussed sequence types. Now, however, it discusses all kinds of container types -- the link takes us to here: https://docs.python.org/3/reference/datamodel.html#emulating-container-types

[JelleZijlstra]

Thanks! I'm happy to merge this now (cc @gvanrossum).

[gvanrossum]

(Because the other meaning of "subscription" (e.g. a magazine) is so much more common I have a slight problem with using it to refer to the a[i] syntax, but it seems commonly used in our docs so it's fine. And the unambiguous alternative, "subscripting", is used much less frequently in our docs.)

[miss-islington]

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

[bedevere-bot]

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

[bedevere-bot]

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

[AlexWaygood]

Thanks so much for helping get this over the line @JelleZijlstra!