[Python-checkins] r59780 - in python/trunk/Doc: ACKS.txt library/functions.rst reference/datamodel.rst

[georg.brandl]

Author: georg.brandl
Date: Sun Jan  6 17:17:56 2008
New Revision: 59780

Modified:
   python/trunk/Doc/ACKS.txt
   python/trunk/Doc/library/functions.rst
   python/trunk/Doc/reference/datamodel.rst
Log:
#1582: document __reversed__, patch by Mark Russell.


Modified: python/trunk/Doc/ACKS.txt
==============================================================================
--- python/trunk/Doc/ACKS.txt	(original)
+++ python/trunk/Doc/ACKS.txt	Sun Jan  6 17:17:56 2008
@@ -158,6 +158,7 @@
    * Jim Roskind
    * Guido van Rossum
    * Donald Wallace Rouse II
+   * Mark Russell
    * Nick Russo
    * Chris Ryland
    * Constantina S.

Modified: python/trunk/Doc/library/functions.rst
==============================================================================
--- python/trunk/Doc/library/functions.rst	(original)
+++ python/trunk/Doc/library/functions.rst	Sun Jan  6 17:17:56 2008
@@ -977,12 +977,16 @@
 
 .. function:: reversed(seq)
 
-   Return a reverse :term:`iterator`.  *seq* must be an object which supports
-   the sequence protocol (the :meth:`__len__` method and the :meth:`__getitem__`
-   method with integer arguments starting at ``0``).
+   Return a reverse :term:`iterator`.  *seq* must be an object which has
+   a :meth:`__reversed__` method or supports the sequence protocol (the
+   :meth:`__len__` method and the :meth:`__getitem__` method with integer
+   arguments starting at ``0``).
 
    .. versionadded:: 2.4
 
+   .. versionchanged:: 2.6
+      Added the possibility to write a custom :meth:`__reversed__` method.
+
 
 .. function:: round(x[, n])
 

Modified: python/trunk/Doc/reference/datamodel.rst
==============================================================================
--- python/trunk/Doc/reference/datamodel.rst	(original)
+++ python/trunk/Doc/reference/datamodel.rst	Sun Jan  6 17:17:56 2008
@@ -1796,6 +1796,22 @@
    Iterator objects also need to implement this method; they are required to return
    themselves.  For more information on iterator objects, see :ref:`typeiter`.
 
+
+.. method:: object.__reversed__(self)
+
+   Called (if present) by the :func:`reversed` builtin to implement
+   reverse iteration.  It should return a new iterator object that iterates
+   over all the objects in the container in reverse order.
+
+   If the :meth:`__reversed__` method is not provided, the
+   :func:`reversed` builtin will fall back to using the sequence protocol
+   (:meth:`__len__` and :meth:`__getitem__`).  Objects should normally
+   only provide :meth:`__reversed__` if they do not support the sequence
+   protocol and an efficient implementation of reverse iteration is possible.
+
+   .. versionadded:: 2.6
+
+
 The membership test operators (:keyword:`in` and :keyword:`not in`) are normally
 implemented as an iteration through a sequence.  However, container objects can
 supply the following special method with a more efficient implementation, which