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.
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 @@
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 @@
>>> 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 @@
>>> 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