Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Mar 8, 2022
Merged

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

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
5ae81b5
Improve docs on 'subscriptions'
AlexWaygood Nov 8, 2021
0dfaee5
Merge remote-tracking branch 'origin/main' into subscription-docs
AlexWaygood Nov 19, 2021
f3d66fc
Make this mergeable
AlexWaygood Nov 19, 2021
46f96c0
Reduce diff
AlexWaygood Dec 4, 2021
dc77393
Improve markup readability
AlexWaygood Dec 6, 2021
4ce0cb7
Merge remote-tracking branch 'origin/main' into subscription-docs
AlexWaygood Mar 5, 2022
5393008
Make more concise, improve technical accuracy
AlexWaygood Mar 5, 2022
19edeef
tweaks
AlexWaygood Mar 5, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 30 additions & 20 deletions Doc/reference/expressions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -815,30 +815,44 @@ Subscriptions
object: dictionary
pair: sequence; item

Subscription of a sequence (string, tuple or list) or mapping (dictionary)
object usually selects an item from the collection:
The subscription of an instance of a :ref:`container class <sequence-types>`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

@AlexWaygood AlexWaygood Mar 6, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

will generally select an element from the container. The subscription of a
:term:`generic class <generic type>` will generally return a
:ref:`GenericAlias <types-genericalias>` object.

.. productionlist:: python-grammar
subscription: `primary` "[" `expression_list` "]"

The primary must evaluate to an object that supports subscription (lists or
dictionaries for example). User-defined objects can support subscription by
defining a :meth:`__getitem__` method.
When an object is subscripted, the interpreter will evaluate the primary and
the expression list.

For built-in objects, there are two types of objects that support subscription:
The primary must evaluate to an object that supports subscription. An object
may support subscription through defining one or both of
:meth:`~object.__getitem__` and :meth:`~object.__class_getitem__`. When the
primary is subscripted, the evaluated result of the expression list will be
passed to one of these methods. For more details on when ``__class_getitem__``
is called instead of ``__getitem__``, see :ref:`classgetitem-versus-getitem`.

If the primary is a mapping, the expression list must evaluate to an object
whose value is one of the keys of the mapping, and the subscription selects the
value in the mapping that corresponds to that key. (The expression list is a
tuple except if it has exactly one item.)
If the expression list contains at least one comma, it will evaluate to a
:class:`tuple` containing the items of the expression list. Otherwise, the
expression list will evaluate to the value of the list's sole member.

If the primary is a sequence, the expression list must evaluate to an integer
or a slice (as discussed in the following section).
For built-in objects, there are two types of objects that support subscription
via :meth:`~object.__getitem__`:

1. Mappings. If the primary is a :term:`mapping`, the expression list must
evaluate to an object whose value is one of the keys of the mapping, and the
subscription selects the value in the mapping that corresponds to that key.
An example of a builtin mapping class is the :class:`dict` class.
2. Sequences. If the primary is a :term:`sequence`, the expression list must
evaluate to an :class:`int` or a :class:`slice` (as discussed in the
following section). Examples of builtin sequence classes include the
:class:`str`, :class:`list` and :class:`tuple` classes.

The formal syntax makes no special provision for negative indices in
sequences; however, built-in sequences all provide a :meth:`__getitem__`
:term:`sequences <sequence>`. However, built-in sequences all provide a :meth:`~object.__getitem__`
method that interprets negative indices by adding the length of the sequence
to the index (so that ``x[-1]`` selects the last item of ``x``). The
to the index so that, for example, ``x[-1]`` selects the last item of ``x``. The
resulting value must be a nonnegative integer less than the number of items in
the sequence, and the subscription selects the item whose index is that value
(counting from zero). Since the support for negative indices and slicing
Expand All @@ -849,14 +863,10 @@ this method will need to explicitly add that support.
single: character
pair: string; item

A string's items are characters. A character is not a separate data type but a
A :class:`string <str>` is a special kind of sequence whose items are
*characters*. A character is not a separate data type but a
string of exactly one character.

Subscription of certain :term:`classes <class>` or :term:`types <type>`
creates a :ref:`generic alias <types-genericalias>`.
In this case, user-defined classes can support subscription by providing a
:meth:`__class_getitem__` classmethod.


.. _slicings:

Expand Down