[Python-checkins] r70473 - in python/trunk: Doc/library/collections.rst Lib/collections.py Lib/test/test_collections.py

[raymond.hettinger]

Author: raymond.hettinger
Date: Thu Mar 19 20:59:58 2009
New Revision: 70473

Log:
* Add clearer comment to initialization code.
* Add optional argument to popitem() -- modeled
  after Anthon van der Neut's C version.
* Fix method markup in docs.



Modified:
   python/trunk/Doc/library/collections.rst
   python/trunk/Lib/collections.py
   python/trunk/Lib/test/test_collections.py

Modified: python/trunk/Doc/library/collections.rst
==============================================================================
--- python/trunk/Doc/library/collections.rst	(original)
+++ python/trunk/Doc/library/collections.rst	Thu Mar 19 20:59:58 2009
@@ -858,8 +858,11 @@
 
    .. versionadded:: 2.7
 
-The :meth:`popitem` method for ordered dictionaries returns and removes the
-last added entry.  The key/value pairs are returned in LIFO order.
+.. method:: OrderedDict.popitem(last=True)
+
+   The :meth:`popitem` method for ordered dictionaries returns and removes
+   a (key, value) pair.  The pairs are returned in LIFO order if *last* is
+   true or FIFO order if false.
 
 Equality tests between :class:`OrderedDict` objects are order-sensitive
 and are implemented as ``list(od1.items())==list(od2.items())``.
@@ -867,3 +870,8 @@
 :class:`Mapping` objects are order-insensitive like regular dictionaries.
 This allows :class:`OrderedDict` objects to be substituted anywhere a
 regular dictionary is used.
+
+.. seealso::
+
+   `Equivalent OrderedDict recipe <http://code.activestate.com/recipes/576693/>`_
+   that runs on Python 2.4 or later.

Modified: python/trunk/Lib/collections.py
==============================================================================
--- python/trunk/Lib/collections.py	(original)
+++ python/trunk/Lib/collections.py	Thu Mar 19 20:59:58 2009
@@ -30,7 +30,7 @@
 
     def clear(self):
         self.__end = end = []
-        end += [None, end, end]         # null entry
+        end += [None, end, end]         # sentinel node for doubly linked list
         self.__map = {}                 # key --> [key, prev, next]
         dict.clear(self)
 
@@ -61,10 +61,10 @@
             yield curr[0]
             curr = curr[1]
 
-    def popitem(self):
+    def popitem(self, last=True):
         if not self:
             raise KeyError('dictionary is empty')
-        key = next(reversed(self))
+        key = next(reversed(self)) if last else next(iter(self))
         value = self.pop(key)
         return key, value
 

Modified: python/trunk/Lib/test/test_collections.py
==============================================================================
--- python/trunk/Lib/test/test_collections.py	(original)
+++ python/trunk/Lib/test/test_collections.py	Thu Mar 19 20:59:58 2009
@@ -768,12 +768,19 @@
 class GeneralMappingTests(mapping_tests.BasicTestMappingProtocol):
     type2test = OrderedDict
 
+    def test_popitem(self):
+        d = self._empty_mapping()
+        self.assertRaises(KeyError, d.popitem)
+
 class MyOrderedDict(OrderedDict):
     pass
 
 class SubclassMappingTests(mapping_tests.BasicTestMappingProtocol):
     type2test = MyOrderedDict
 
+    def test_popitem(self):
+        d = self._empty_mapping()
+        self.assertRaises(KeyError, d.popitem)
 
 import doctest, collections