Doc update for __xslice__ removal.

birkenfeld · birkenfeld · commit cb8ecb142be4 · 2007-09-04T06:35:14.000Z
diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst
@@ -34,7 +34,6 @@ A small number of constants live in the built-in namespace.  They are:
 .. data:: Ellipsis
 
    The same as ``...``. Special value used mostly in conjunction with extended
-   slicing syntax for user-defined container data types.
-
-   .. % XXX Someone who understands extended slicing should fill in here.
+   slicing syntax for user-defined container data types, as in ::
 
+      val = container[1:5, 7:10, ...]
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
@@ -587,7 +587,6 @@ of the same type and have the same length. (For full details see
    pair: repetition; operation
    pair: subscript; operation
    pair: slice; operation
-   pair: extended slice; operation
    operator: in
    operator: not in
 
@@ -948,9 +947,10 @@ the :mod:`re` module for string functions based on regular expressions.
 .. method:: str.translate(map)
 
    Return a copy of the *s* where all characters have been mapped through the
-   *map* which must be a mapping of Unicode ordinals (integers) to Unicode
-   ordinals, strings or ``None``.  Unmapped characters are left
-   untouched. Characters mapped to ``None`` are deleted.
+   *map* which must be a dictionary of characters (strings of length 1) or
+   Unicode ordinals (integers) to Unicode ordinals, strings or ``None``.
+   Unmapped characters are left untouched. Characters mapped to ``None`` are
+   deleted.
 
    .. note::
 
@@ -1244,7 +1244,6 @@ Note that while lists allow their items to be of any type, bytes object
    triple: operations on; list; type
    pair: subscript; assignment
    pair: slice; assignment
-   pair: extended slice; assignment
    statement: del
    single: append() (sequence method)
    single: extend() (sequence method)
@@ -2389,8 +2388,8 @@ It is written as ``None``.
 The Ellipsis Object
 -------------------
 
-This object is mostly used by extended slice notation (see :ref:`slicings`).  It
-supports no special operations.  There is exactly one ellipsis object, named
+This object is commonly used by slicing (see :ref:`slicings`).  It supports no
+special operations.  There is exactly one ellipsis object, named
 :const:`Ellipsis` (a built-in name).
 
 It is written as ``Ellipsis`` or ``...``.
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
@@ -265,8 +265,6 @@ Sequences
    sequence of the same type.  This implies that the index set is renumbered so
    that it starts at 0.
 
-   .. index:: single: extended slicing
-
    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*
    ``>=`` ``0`` and *i* ``<=`` *x* ``<`` *j*.
@@ -997,10 +995,8 @@ Internal types
    Slice objects
       .. index:: builtin: slice
 
-      Slice objects are used to represent slices when *extended slice syntax* is used.
-      This is a slice using two colons, or multiple slices or ellipses separated by
-      commas, e.g., ``a[i:j:step]``, ``a[i:j, k:l]``, or ``a[..., i:j]``.  They are
-      also created by the built-in :func:`slice` function.
+      Slice objects are used to represent slices for :meth:`__getitem__`
+      methods.  They are also created by the built-in :func:`slice` function.
 
       .. index::
          single: start (slice object attribute)
@@ -1013,15 +1009,14 @@ Internal types
 
       Slice objects support one method:
 
-
       .. method:: slice.indices(self, length)
 
-         This method takes a single integer argument *length* and computes information
-         about the extended slice that the slice object would describe if applied to a
-         sequence of *length* items.  It returns a tuple of three integers; respectively
-         these are the *start* and *stop* indices and the *step* or stride length of the
-         slice. Missing or out-of-bounds indices are handled in a manner consistent with
-         regular slices.
+         This method takes a single integer argument *length* and computes
+         information about the slice that the slice object would describe if
+         applied to a sequence of *length* items.  It returns a tuple of three
+         integers; respectively these are the *start* and *stop* indices and the
+         *step* or stride length of the slice. Missing or out-of-bounds indices
+         are handled in a manner consistent with regular slices.
 
    Static method objects
       Static method objects provide a way of defeating the transformation of function
@@ -1592,31 +1587,28 @@ but can represent other containers as well.  The first set of methods is used
 either to emulate a sequence or to emulate a mapping; the difference is that for
 a sequence, the allowable keys should be the integers *k* for which ``0 <= k <
 N`` where *N* is the length of the sequence, or slice objects, which define a
-range of items. (For backwards compatibility, the method :meth:`__getslice__`
-(see below) can also be defined to handle simple, but not extended slices.) It
-is also recommended that mappings provide the methods :meth:`keys`,
-:meth:`values`, :meth:`items`, :meth:`has_key`, :meth:`get`, :meth:`clear`,
-:meth:`setdefault`, :meth:`iterkeys`, :meth:`itervalues`, :meth:`iteritems`,
-:meth:`pop`, :meth:`popitem`, :meth:`copy`, and :meth:`update` behaving similar
-to those for Python's standard dictionary objects.  The :mod:`UserDict` module
-provides a :class:`DictMixin` class to help create those methods from a base set
-of :meth:`__getitem__`, :meth:`__setitem__`, :meth:`__delitem__`, and
-:meth:`keys`. Mutable sequences should provide methods :meth:`append`,
-:meth:`count`, :meth:`index`, :meth:`extend`, :meth:`insert`, :meth:`pop`,
-:meth:`remove`, :meth:`reverse` and :meth:`sort`, like Python standard list
-objects.  Finally, sequence types should implement addition (meaning
-concatenation) and multiplication (meaning repetition) by defining the methods
-:meth:`__add__`, :meth:`__radd__`, :meth:`__iadd__`, :meth:`__mul__`,
-:meth:`__rmul__` and :meth:`__imul__` described below; they should not define
-other numerical operators.  It is recommended that both mappings and sequences
-implement the :meth:`__contains__` method to allow efficient use of the ``in``
-operator; for mappings, ``in`` should be equivalent of :meth:`has_key`; for
-sequences, it should search through the values.  It is further recommended that
-both mappings and sequences implement the :meth:`__iter__` method to allow
-efficient iteration through the container; for mappings, :meth:`__iter__` should
-be the same as :meth:`iterkeys`; for sequences, it should iterate through the
-values.
-
+range of items.  It is also recommended that mappings provide the methods
+:meth:`keys`, :meth:`values`, :meth:`items`, :meth:`has_key`, :meth:`get`,
+:meth:`clear`, :meth:`setdefault`, :meth:`iterkeys`, :meth:`itervalues`,
+:meth:`iteritems`, :meth:`pop`, :meth:`popitem`, :meth:`copy`, and
+:meth:`update` behaving similar to those for Python's standard dictionary
+objects.  The :mod:`UserDict` module provides a :class:`DictMixin` class to help
+create those methods from a base set of :meth:`__getitem__`,
+:meth:`__setitem__`, :meth:`__delitem__`, and :meth:`keys`. Mutable sequences
+should provide methods :meth:`append`, :meth:`count`, :meth:`index`,
+:meth:`extend`, :meth:`insert`, :meth:`pop`, :meth:`remove`, :meth:`reverse` and
+:meth:`sort`, like Python standard list objects.  Finally, sequence types should
+implement addition (meaning concatenation) and multiplication (meaning
+repetition) by defining the methods :meth:`__add__`, :meth:`__radd__`,
+:meth:`__iadd__`, :meth:`__mul__`, :meth:`__rmul__` and :meth:`__imul__`
+described below; they should not define other numerical operators.  It is
+recommended that both mappings and sequences implement the :meth:`__contains__`
+method to allow efficient use of the ``in`` operator; for mappings, ``in``
+should be equivalent of :meth:`has_key`; for sequences, it should search through
+the values.  It is further recommended that both mappings and sequences
+implement the :meth:`__iter__` method to allow efficient iteration through the
+container; for mappings, :meth:`__iter__` should be the same as
+:meth:`iterkeys`; for sequences, it should iterate through the values.
 
 .. method:: object.__len__(self)
 
@@ -1630,6 +1622,19 @@ values.
    considered to be false in a Boolean context.
 
 
+.. note::
+
+   Slicing is done exclusively with the following three methods.  A call like ::
+
+      a[1:2] = b
+
+   is translated to ::
+
+      a[slice(1, 2, None)] = b
+
+   and so forth.  Missing slice items are always filled in with ``None``.
+
+
 .. method:: object.__getitem__(self, key)
 
    .. index:: object: slice
@@ -1690,98 +1695,6 @@ also does not require the object be a sequence.
    of the mapping rather than the values or the key-item pairs.
 
 
-.. _sequence-methods:
-
-Additional methods for emulation of sequence types
---------------------------------------------------
-
-The following optional methods can be defined to further emulate sequence
-objects.  Immutable sequences methods should at most only define
-:meth:`__getslice__`; mutable sequences might define all three methods.
-
-
-.. method:: object.__getslice__(self, i, j)
-
-   .. deprecated:: 2.0
-      Support slice objects as parameters to the :meth:`__getitem__` method.
-      (However, built-in types in CPython currently still implement
-      :meth:`__getslice__`.  Therefore, you have to override it in derived
-      classes when implementing slicing.)
-
-   Called to implement evaluation of ``self[i:j]``. The returned object should be
-   of the same type as *self*.  Note that missing *i* or *j* in the slice
-   expression are replaced by zero or ``sys.maxint``, respectively.  If negative
-   indexes are used in the slice, the length of the sequence is added to that
-   index. If the instance does not implement the :meth:`__len__` method, an
-   :exc:`AttributeError` is raised. No guarantee is made that indexes adjusted this
-   way are not still negative.  Indexes which are greater than the length of the
-   sequence are not modified. If no :meth:`__getslice__` is found, a slice object
-   is created instead, and passed to :meth:`__getitem__` instead.
-
-
-.. method:: object.__setslice__(self, i, j, sequence)
-
-   Called to implement assignment to ``self[i:j]``. Same notes for *i* and *j* as
-   for :meth:`__getslice__`.
-
-   This method is deprecated. If no :meth:`__setslice__` is found, or for extended
-   slicing of the form ``self[i:j:k]``, a slice object is created, and passed to
-   :meth:`__setitem__`, instead of :meth:`__setslice__` being called.
-
-
-.. method:: object.__delslice__(self, i, j)
-
-   Called to implement deletion of ``self[i:j]``. Same notes for *i* and *j* as for
-   :meth:`__getslice__`. This method is deprecated. If no :meth:`__delslice__` is
-   found, or for extended slicing of the form ``self[i:j:k]``, a slice object is
-   created, and passed to :meth:`__delitem__`, instead of :meth:`__delslice__`
-   being called.
-
-Notice that these methods are only invoked when a single slice with a single
-colon is used, and the slice method is available.  For slice operations
-involving extended slice notation, or in absence of the slice methods,
-:meth:`__getitem__`, :meth:`__setitem__` or :meth:`__delitem__` is called with a
-slice object as argument.
-
-The following example demonstrate how to make your program or module compatible
-with earlier versions of Python (assuming that methods :meth:`__getitem__`,
-:meth:`__setitem__` and :meth:`__delitem__` support slice objects as
-arguments)::
-
-   class MyClass:
-       ...
-       def __getitem__(self, index):
-           ...
-       def __setitem__(self, index, value):
-           ...
-       def __delitem__(self, index):
-           ...
-
-       if sys.version_info < (2, 0):
-           # They won't be defined if version is at least 2.0 final
-
-           def __getslice__(self, i, j):
-               return self[max(0, i):max(0, j):]
-           def __setslice__(self, i, j, seq):
-               self[max(0, i):max(0, j):] = seq
-           def __delslice__(self, i, j):
-               del self[max(0, i):max(0, j):]
-       ...
-
-Note the calls to :func:`max`; these are necessary because of the handling of
-negative indices before the :meth:`__\*slice__` methods are called.  When
-negative indexes are used, the :meth:`__\*item__` methods receive them as
-provided, but the :meth:`__\*slice__` methods get a "cooked" form of the index
-values.  For each negative index value, the length of the sequence is added to
-the index before calling the method (which may still result in a negative
-index); this is the customary handling of negative indexes by the built-in
-sequence types, and the :meth:`__\*item__` methods are expected to do this as
-well.  However, since they should already be doing that, negative indexes cannot
-be passed in; they must be constrained to the bounds of the sequence before
-being passed to the :meth:`__\*item__` methods. Calling ``max(0, i)``
-conveniently returns the proper value.
-
-
 .. _numeric-types:
 
 Emulating numeric types
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
@@ -517,25 +517,24 @@ or list).  Slicings may be used as expressions or as targets in assignment or
    simple_slicing: `primary` "[" `short_slice` "]"
    extended_slicing: `primary` "[" `slice_list` "]" 
    slice_list: `slice_item` ("," `slice_item`)* [","]
-   slice_item: `expression` | `proper_slice` | `ellipsis`
+   slice_item: `expression` | `proper_slice`
    proper_slice: `short_slice` | `long_slice`
    short_slice: [`lower_bound`] ":" [`upper_bound`]
    long_slice: `short_slice` ":" [`stride`]
    lower_bound: `expression`
    upper_bound: `expression`
    stride: `expression`
-   ellipsis: "..."
-
-.. index:: pair: extended; slicing
 
 There is ambiguity in the formal syntax here: anything that looks like an
 expression list also looks like a slice list, so any subscription can be
 interpreted as a slicing.  Rather than further complicating the syntax, this is
 disambiguated by defining that in this case the interpretation as a subscription
 takes priority over the interpretation as a slicing (this is the case if the
-slice list contains no proper slice nor ellipses).  Similarly, when the slice
-list has exactly one short slice and no trailing comma, the interpretation as a
-simple slicing takes priority over that as an extended slicing.
+slice list contains no proper slice).  Similarly, when the slice list has
+exactly one short slice and no trailing comma, the interpretation as a simple
+slicing takes priority over that as an extended slicing.
+
+.. XXX is the next paragraph stil correct?
 
 The semantics for a simple slicing are as follows.  The primary must evaluate to
 a sequence object.  The lower and upper bound expressions, if present, must
