New submission from Mark Russell:
This patch adds documentation for the reversed() builtin and
__reversed__() special method.
----------
components: Documentation
files: reverse-2.6-docs.diff
messages: 58369
nosy: mark_t_russell
severity: normal
status: open
title: Documentation patch for reversed() and __reversed__()
versions: Python 2.6
Added file: http://bugs.python.org/file8912/reverse-2.6-docs.diff
__________________________________
Tracker <[EMAIL PROTECTED]>
<http://bugs.python.org/issue1582>
__________________________________
Index: Doc/reference/datamodel.rst
===================================================================
--- Doc/reference/datamodel.rst (revision 59453)
+++ Doc/reference/datamodel.rst (working copy)
@@ -1819,12 +1819,27 @@
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.
+
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
also does not require the object be a sequence.
+
+
+
.. method:: object.__contains__(self, item)
Called to implement membership test operators. Should return true if
*item* is
Index: Doc/library/functions.rst
===================================================================
--- Doc/library/functions.rst (revision 59453)
+++ Doc/library/functions.rst (working copy)
@@ -974,8 +974,9 @@
.. 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__`
+ 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
@@ -1342,6 +1343,8 @@
any I/O has been performed, and there's no reliable way to determine whether
this is the case.
+.. [#] See :ref:`sequence-types`
+
.. [#] In the current implementation, local variable bindings cannot normally
be
affected this way, but variables retrieved from other scopes (such as
modules)
can be. This may change.
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
