8000 bpo-45680: Improve docs on subscriptions w.r.t. `GenericAlias` objects by AlexWaygood · Pull Request #29479 · python/cpython · GitHub
[go: up one dir, main page]
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 5 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 f 10000 ile
Failed to load files.
Loading
Diff view
Diff view
59 changes: 39 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,46 @@ 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 object in Python can have one of two effects. If the
object is a :term:`sequence` (such as a :class:`string <str>`,
:class:`tuple` or :class:`list`) or a :term:`mapping` (such as a
:class:`dictionary <dict>`), subscripting the object will select an object from
the collection. Subscripting certain *classes or types*, meanwhile, will
return a :ref:`generic alias <types-genericalias>` object representing a
*parameterized generic class*. The latter form of subscription is primarily
useful for :term:`type hinting <type hint>`.

.. 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.
The primary must evaluate to an object that supports subscription, such as a
:class:`list` or a :class:`dictionary <dict>`. User-defined objects can support
subscription by defining one or both of :meth:`~object.__getitem__` and
:meth:`~object.__class_getitem__`.

For built-in objects, there are two types of objects that support subscription:
.. seealso::
:ref:`classgetitem-versus-getitem`
Documentation explaining when a subscription will lead to
:meth:`~object.__class_getitem__` being called over
:meth:`~object.__getitem__`

Subscriptions calling *__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.)
For built-in objects, there are two types of objects that support subscription
via :meth:`~object.__getitem__`:

If the primary is a sequence, the expression list must evaluate to an integer
or a slice (as discussed in the following section).
* 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. (The
expression list is a :class:`tuple` except if it has exactly one item.)
* 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).

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,13 +865,16 @@ 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
string of exactly one character.
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.

Subscriptions calling *__class_getitem__*
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.
A large number of types in the standard library support subscription via
:meth:`~object.__class_getitem__`. See :ref:`types-genericalias` for more
information on the objects returned by such subscriptions.


.. _slicings:
Expand Down
0