Improvements to collections.deque():

* Add doctests for the examples in the library reference.
* Add two methods, left() and right(), modeled after deques in C++ STL.
* Apply the new method to asynchat.py.
* Add comparison operators to make deques more substitutable for lists.
* Replace the LookupErrors with IndexErrors to more closely match lists.

1 files changed, 22 insertions, 7 deletions

diff --git a/Doc/lib/libcollections.tex b/Doc/lib/libcollections.tex
index 0378ea5..2793095 100644
--- a/Doc/lib/libcollections.tex
+++ b/Doc/lib/libcollections.tex
@@ -54,14 +54,24 @@ Deque objects support the following methods:
    reversing the order of elements in the iterable argument.
 \end{methoddesc}
 
+\begin{methoddesc}{left}{}
+   Return leftmost element from the deque.
+   If no elements are present, raises a \exception{IndexError}.   
+\end{methoddesc}
+
 \begin{methoddesc}{pop}{}
    Remove and return an element from the right side of the deque.
-   If no elements are present, raises a \exception{LookupError}.
+   If no elements are present, raises a \exception{IndexError}.
 \end{methoddesc}
 
 \begin{methoddesc}{popleft}{}
    Remove and return an element from the left side of the deque.
-   If no elements are present, raises a \exception{LookupError}.   
+   If no elements are present, raises a \exception{IndexError}.   
+\end{methoddesc}
+
+\begin{methoddesc}{right}{}
+   Return the rightmost element from the deque.
+   If no elements are present, raises a \exception{IndexError}.   
 \end{methoddesc}
 
 \begin{methoddesc}{rotate}{n}
@@ -80,22 +90,27 @@ Example:
 >>> from collections import deque
 >>> d = deque('ghi')                 # make a new deque with three items
 >>> for elem in d:                   # iterate over the deque's elements
-	print elem.upper()
-
-	
+...     print elem.upper()	
 G
 H
 I
+
 >>> d.append('j')                    # add a new entry to the right side
 >>> d.appendleft('f')                # add a new entry to the left side
 >>> d                                # show the representation of the deque
 deque(['f', 'g', 'h', 'i', 'j'])
+
 >>> d.pop()                          # return and remove the rightmost item
 'j'
 >>> d.popleft()                      # return and remove the leftmost item
 'f'
 >>> list(d)                          # list the contents of the deque
 ['g', 'h', 'i']
+
+>>> d.left()                         # peek at leftmost item
+'g'
+>>> d.right()                        # peek at rightmost item
+'i'
 >>> list(reversed(d))                # list the contents of a deque in reverse
 ['i', 'h', 'g']
 >>> 'h' in d                         # search the deque
@@ -109,15 +124,15 @@ deque(['l', 'g', 'h', 'i', 'j', 'k'])
 >>> d.rotate(-1)                     # left rotation
 >>> d
 deque(['g', 'h', 'i', 'j', 'k', 'l'])
+
 >>> deque(reversed(d))               # make a new deque in reverse order
 deque(['l', 'k', 'j', 'i', 'h', 'g'])
 >>> d.clear()                        # empty the deque
 >>> d.pop()                          # cannot pop from an empty deque
-
 Traceback (most recent call last):
   File "<pyshell#6>", line 1, in -toplevel-
     d.pop()
-LookupError: pop from an empty deque
+IndexError: pop from an empty deque
 
 >>> d.extendleft('abc')              # extendleft() reverses the input order
 >>> d