Continue rewording

Author: encukou

Doc/library/functions.rst

@@ -1822,8 +1822,8 @@ are always available.  They are listed here in alphabetical order.
    .. attribute:: slice.stop
    .. attribute:: slice.step
 
-   Slice objects are also generated when extended indexing syntax is used.  For
-   example: ``a[start:stop:step]`` or ``a[start:stop, i]``.  See
+   Slice objects are also generated when :ref:`slicing syntax <slicings>`
+   is used.  For example: ``a[start:stop:step]`` or ``a[start:stop, i]``.  See
    :func:`itertools.islice` for an alternate version that returns an
    :term:`iterator`.
 

Doc/reference/datamodel.rst

@@ -314,12 +314,22 @@ including built-in sequences, interpret negative subscripts by adding the
 sequence length. For example, ``a[-2]`` equals ``a[n-2]``, the second to last
 item of sequence a with length ``n``.
 
-.. index:: single: slicing
+.. index::
+   single: slicing
+   single: start (slice object attribute)
+   single: stop (slice object attribute)
+   single: step (slice object attribute)
 
-Sequences also support slicing: ``a[i:j]`` selects all items with index *k* such
-that *i* ``<=`` *k* ``<`` *j*.  When used as an expression, a slice is a
-sequence of the same type. The comment above about negative indexes also applies
+Sequences also support slicing: ``a[start:stop]`` selects all items with index *k* such
+that *start* ``<=`` *k* ``<`` *stop*.  When used as an expression, a slice is a
+sequence of the same type. The comment above about negative subscripts also applies
 to negative slice positions.
+Note that no error is raised if a slice positions is larger than the length
+of the sequence.
+
+If *start* is missing or ``None``, slicing behaves as if *start* was zero.
+If *stop* is missing or ``None``, slicing behaves as if *stop* was equal to
+the length of the sequence.
 
 Some sequences also support "extended slicing" with a third "step" parameter:
 ``a[i:j:k]`` selects all items of *a* with index *x* where ``x = i + n*k``, *n*
@@ -3203,21 +3213,28 @@ through the object's keys; for sequences, it should iterate through the values.
    and so forth.  Missing slice items are always filled in with ``None``.
 
 
-.. method:: object.__getitem__(self, key)
+.. method:: object.__getitem__(self, subscript)
 
-<<<<
+   Called to implement *subscription*, that is, ``self[subscript]``.
+   See :ref:`subscriptions` for details on the syntax.
 
-For built-in objects, there are two types of objects that support subscription
-via :meth:`~object.__getitem__`:
+   There are two types of built-in objects that support subscription
+   via :meth:`~object.__getitem__`:
+   - **sequences**, where *subscript* (also called
+     *index*) should be an integer or a :class:`slice` object.
+     See :ref:`sequence documentation <datamodel-sequences>` for the expected
+     behavior, including handling :class:`slice` objects and negative indices.
+   - **mappings**, where *subscript* is also called the *key*.
+     See :ref:`mapping documentation <datamodel-mappings>` for the expected
+     behavior.
 
-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.
+   If *subscript* is of an inappropriate type, :meth:`~object.__getitem__`
+   should raise :exc:`TypeError`.
+   If *subscript* has an inappropriate value, :meth:`~object.__getitem__`
+   should raise an :exc:`LookupError` or one of its subclasses
+   (:exc:`IndexError` for sequences; :exc:`KeyError` for mappings).
+
+<<<<
 
 The formal syntax makes no special provision for negative indices in
 :term:`sequences <sequence>`. However, built-in sequences all provide a :meth:`~object.__getitem__`
@@ -3263,17 +3280,6 @@ expressions given as lower bound, upper bound and stride, respectively,
 substituting ``None`` for missing expressions.
 
 
-====
-
-   Called to implement evaluation of ``self[key]``. For :term:`sequence` types,
-   the accepted keys should be integers. Optionally, they may support
-   :class:`slice` objects as well.  Negative index support is also optional.
-   If *key* is
-   of an inappropriate type, :exc:`TypeError` may be raised; if *key* is a value
-   outside the set of indexes for the sequence (after any special
-   interpretation of negative values), :exc:`IndexError` should be raised. For
-   :term:`mapping` types, if *key* is missing (not in the container),
-   :exc:`KeyError` should be raised.
 
 >>>>>>
 

Doc/reference/expressions.rst

@@ -931,7 +931,6 @@ If an :exc:`AttributeError` is raised and the object has a :meth:`!__getattr__`
 method, that method is called as a fallback.
 
 .. _subscriptions:
-.. _slicings:
 
 Subscriptions and slicing
 -------------------------
@@ -958,42 +957,31 @@ a :class:`dict`::
    2
 
 In the subscription syntax, the object being subscribed -- a
-:ref:`primary <primaries>` -- is followed by square brackets.
-In the simplest case, the brackets contain a single expression.
+:ref:`primary <primaries>` -- is followed by a :dfn:`subscript` in
+square brackets.
+In the simplest case, the subscript is single expression.
 
-When getting a value from a :ref:`mapping <datamodel-mappings>`, like in the
-:class:`~dict` example above, the expression in brackets is called a *key*.
-When when getting an item from a :ref:`sequence <datamodel-sequences>`,
-the expression is called an *index*::
+Depending on the type of the object being subscribed, the subscript is
+sometimes called a *key* (for mappings), *index* (for sequences),
+or *type argument* (for :term:`generic types <generic type>`).
+Syntacticall, these are all equivalent::
 
    >>> number_names = ['zero', 'one', 'two', 'three', 'four', 'five']
    >>> number_names[2]  # Subscripting a list using the index 2
    'two'
-   >>> number_names[-2]
-   'four'
-
-Syntactically, there's no difference between a *key* and an *index*.
-
-The subscription syntax is also used to provide type arguments for
-:term:`generic types <generic type>`, even though types are not (necessarily)
-sequences::
 
    >>> list[str]  # Parameterizing `list` using the type argument `str`
    list[str]
 
-Syntactically, there's also no difference between a *type argument* and a
-key or index.
-
 At runtime, the interpreter will evaluate the primary and
-the expression in the square brackets, and call the primary's
-:meth:`~object.__getitem__` or :meth:`~object.__class_getitem__` method
-with the contents of the square brackets as argument.
+the subscript, and call the primary's :meth:`~object.__getitem__` or
+:meth:`~object.__class_getitem__` method with the subscript as argument.
 For more details on which of these methods is called, see
 :ref:`classgetitem-versus-getitem`.
 
 To show how subscription works, we can define a custom object that
-implements :meth:`~object.__getitem__` and prints out the key it
-was subscripted with::
+implements :meth:`~object.__getitem__` and prints out the value of
+the subscript::
 
    >>> class SubscriptionDemo:
    ...     def __getitem__(self, key):
@@ -1006,7 +994,7 @@ was subscripted with::
    subscripted with: 'aaa'
 
 See :meth:`~object.__getitem__` documentation for how built-in types handle
-subscription, including support for negative indices.
+subscription, including support for negative subscripts.
 
 
 .. index::
@@ -1028,7 +1016,7 @@ Slicing
 
 A more advanced form of subscription, :dfn:`slicing`, is commonly used
 to extract a portion of a :ref:`sequence <datamodel-sequences>`.
-In this form, the square brackets contain a :term:`slice`: up to three
+In this form, the subscript is a :term:`slice`: up to three
 expressions separated by colons.
 Any of the expressions may be omitted, but a slice must contain at least one
 colon::
@@ -1062,19 +1050,21 @@ or :meth:`~object.__class_getitem__` method, as above. ::
 Tuple subscription
 ^^^^^^^^^^^^^^^^^^
 
-The square brackets used for subscription can also contain two or more
-comma-separated expressions or slices::
+The subscript can also be given as two or more comma-separated expressions
+or slices::
 
    >>> demo[1, 2, 3]
    subscripted with (1, 2, 3)
+   >>> demo[1:2, 3]
+   subscripted with (slice(1, 2, None), 3)
 
 This form is commonly used with numerical libraries for slicing
 multi-dimensional data.
 In this case, the interpreter constructs a :class:`tuple` of the results of the
 expressions or slices, and passes this tuple to the :meth:`~object.__getitem__`
 or :meth:`~object.__class_getitem__` method, as above.
 
-The square brackets may also contain one expression or slice followed
+The subscript may also be given as a single expression or slice followed
 by a comma, to specify a one-element tuple::
 
    >>> demo['spam',]
@@ -1087,7 +1077,7 @@ by a comma, to specify a one-element tuple::
 .. versionadded:: 3.11
    Expressions in *tuple_slices* may be starred. See :pep:`646`.
 
-The square brackets can also contain a starred expression.
+The subscript can also contain a starred expression.
 In this case, the interpreter unpacks the result into a tuple, and passes
 this tuple to :meth:`~object.__getitem__` or :meth:`~object.__class_getitem__`::
 
@@ -1107,19 +1097,19 @@ Formal subscription grammar
 .. grammar-snippet::
    :group: python-grammar
 
-   subscription: `primary` '[' `slices` ']'
-   slices:       `slice` | `tuple_slices`
+   subscription: `primary` '[' `subscript` ']'
+   subscript:    `slice` | `tuple_slices`
    tuple_slices: ','.(`slice` | `starred_expression`)+ [',']
    slice:        `proper_slice` | `assignment_expression`
    proper_slice: [`lower_bound`] ":" [`upper_bound`] [ ":" [`stride`] ]
    lower_bound:  `expression`
    upper_bound:  `expression`
    stride:       `expression`
 
-If *slices* contains ony one unstarred *slice* without a trailing comma,
+If *subscript* contains ony one unstarred *slice* without a trailing comma,
 it will evaluate to the value of that *slice*.
-Otherwise, *slices* will evaluate to a :class:`tuple` containing
-the items of *slices*.
+Otherwise, *subscript* will evaluate to a :class:`tuple` containing
+the items of *subscript*.
 
 .. index::
    pair: object; callable