mirror of https://github.com/python/cpython
bpo-45680: Improve docs on subscriptions w.r.t. `GenericAlias` objects (GH-29479)
This commit is contained in:
parent
47cca0492b
commit
50731297a9
|
@ -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>`
|
||||
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
|
||||
|
@ -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:
|
||||
|
||||
|
|
Loading…
Reference in New Issue