Backport PEP 372: OrderedDict()

1 files changed, 30 insertions, 2 deletions

diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index d6d7ebb..cf30aa5 100644
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -16,7 +16,7 @@
    __name__ = '<doctest>'
 
 This module implements high-performance container datatypes.  Currently,
-there are three datatypes, :class:`Counter`, :class:`deque` and
+there are three datatypes, :class:`Counter`, :class:`deque`, :class:`OrderedDict` and
 :class:`defaultdict`, and one datatype factory function, :func:`namedtuple`.
 
 The specialized containers provided in this module provide alternatives
@@ -33,7 +33,7 @@ to Python's general purpose built-in containers, :class:`dict`,
    Added :func:`namedtuple` and added abstract base classes.
 
 .. versionchanged:: 2.7
-   Added :class:`Counter`.
+   Added :class:`Counter` and :class:`OrderedDict`.
 
 In addition to containers, the collections module provides some ABCs
 (abstract base classes) that can be used to test whether a class
@@ -826,3 +826,31 @@ and more efficient to use a simple class declaration:
 
    `Named tuple recipe <http://code.activestate.com/recipes/500261/>`_
    adapted for Python 2.4.
+
+
+:class:`OrderedDict` objects
+----------------------------
+
+Ordered dictionaries are just like regular dictionaries but they remember the
+order that items were inserted.  When iterating over an ordered dictionary,
+the items are returned in the order their keys were first added.
+
+.. class:: OrderedDict([items])
+
+   Return an instance of a dict subclass, supporting the usual :class:`dict`
+   methods.  An *OrderedDict* is a dict that remembers the order that keys
+   were first inserted. If a new entry overwrites an existing entry, the
+   original insertion position is left unchanged.  Deleting an entry and
+   reinserting it will move it to the end.
+
+   .. 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.
+
+Equality tests between :class:`OrderedDict` objects are order-sensitive
+and are implemented as ``list(od1.items())==list(od2.items())``.
+Equality tests between :class:`OrderedDict` objects and other
+:class:`Mapping` objects are order-insensitive like regular dictionaries.
+This allows :class:`OrderedDict` objects to be substituted anywhere a
+regular dictionary is used.