From cb8ecb142be4ea3335fd7f8c1722e95ef5563fc7 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 4 Sep 2007 06:35:14 +0000 Subject: [PATCH] Doc update for __xslice__ removal. --- Doc/library/constants.rst | 5 +- Doc/library/stdtypes.rst | 13 ++- Doc/reference/datamodel.rst | 173 +++++++++------------------------- Doc/reference/expressions.rst | 13 ++- 4 files changed, 57 insertions(+), 147 deletions(-) diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst index 8f7be508759..c36b2fae64c 100644 --- 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 index 77a8411347e..3e049b2b434 100644 --- 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 index 1e8f3bee5aa..7c2ed4db739 100644 --- 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 index b1b80ca3843..6f7e13f35b0 100644 --- 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