[Python-3000-checkins] r57948 - in python/branches/py3k/Doc: library/constants.rst library/stdtypes.rst reference/datamodel.rst reference/expressions.rst
georg.brandl
python-3000-checkins at python.org
Tue Sep 4 08:35:14 CEST 2007
Author: georg.brandl
Date: Tue Sep 4 08:35:14 2007
New Revision: 57948
Modified:
python/branches/py3k/Doc/library/constants.rst
python/branches/py3k/Doc/library/stdtypes.rst
python/branches/py3k/Doc/reference/datamodel.rst
python/branches/py3k/Doc/reference/expressions.rst
Log:
Doc update for __xslice__ removal.
Modified: python/branches/py3k/Doc/library/constants.rst
==============================================================================
--- python/branches/py3k/Doc/library/constants.rst (original)
+++ python/branches/py3k/Doc/library/constants.rst Tue Sep 4 08:35:14 2007
@@ -34,7 +34,6 @@
.. 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, ...]
Modified: python/branches/py3k/Doc/library/stdtypes.rst
==============================================================================
--- python/branches/py3k/Doc/library/stdtypes.rst (original)
+++ python/branches/py3k/Doc/library/stdtypes.rst Tue Sep 4 08:35:14 2007
@@ -587,7 +587,6 @@
pair: repetition; operation
pair: subscript; operation
pair: slice; operation
- pair: extended slice; operation
operator: in
operator: not in
@@ -948,9 +947,10 @@
.. 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 @@
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 @@
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 ``...``.
Modified: python/branches/py3k/Doc/reference/datamodel.rst
==============================================================================
--- python/branches/py3k/Doc/reference/datamodel.rst (original)
+++ python/branches/py3k/Doc/reference/datamodel.rst Tue Sep 4 08:35:14 2007
@@ -265,8 +265,6 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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
Modified: python/branches/py3k/Doc/reference/expressions.rst
==============================================================================
--- python/branches/py3k/Doc/reference/expressions.rst (original)
+++ python/branches/py3k/Doc/reference/expressions.rst Tue Sep 4 08:35:14 2007
@@ -517,25 +517,24 @@
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
More information about the Python-3000-checkins
mailing list