Skip to content

[3.9] bpo-45680: Improve docs on subscriptions w.r.t. GenericAlias objects (GH-29479) #31744

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 1 commit into from
Mar 8, 2022
Merged

[3.9] bpo-45680: Improve docs on subscriptions w.r.t. GenericAlias objects (GH-29479) #31744

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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 @@ -802,30 +802,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>`
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 @@ -836,14 +850,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