Expand examples for ChainMap(). Improve markup.

Doc/library/collections.rst

@@ -93,42 +93,8 @@ The class can be used to simulate nested scopes and is useful in templating.
         The use-cases also parallel those for the builtin :func:`super` function.
         A reference to  ``d.parents`` is equivalent to: ``ChainMap(*d.maps[1:])``.
 
-    Example of simulating Python's internal lookup chain::
 
-        import builtins
-        pylookup = ChainMap(locals(), globals(), vars(builtins))
-
-    Example of letting user specified values take precedence over environment
-    variables which in turn take precedence over default values::
-
-        import os, argparse
-        defaults = {'color': 'red', 'user': guest}
-        parser = argparse.ArgumentParser()
-        parser.add_argument('-u', '--user')
-        parser.add_argument('-c', '--color')
-        user_specified = vars(parser.parse_args())
-        combined = ChainMap(user_specified, os.environ, defaults)
-
-    Example patterns for using the :class:`ChainMap` class to simulate nested
-    contexts::
-
-        c = ChainMap()        # Create root context
-        d = c.new_child()     # Create nested child context
-        e = c.new_child()     # Child of c, independent from d
-        e.maps[0]             # Current context dictionary -- like Python's locals()
-        e.maps[-1]            # Root context -- like Python's globals()
-        e.parents             # Enclosing context chain -- like Python's nonlocals
-
-        d['x']                # Get first key in the chain of contexts
-        d['x'] = 1            # Set value in current context
-        del['x']              # Delete from current context
-        list(d)               # All nested values
-        k in d                # Check all nested values
-        len(d)                # Number of nested values
-        d.items()             # All nested items
-        dict(d)               # Flatten into a regular dictionary
-
-    .. seealso::
+.. seealso::
 
     * The `MultiContext class
       <http://svn.enthought.com/svn/enthought/CodeTools/trunk/enthought/contexts/multi_context.py>`_
@@ -152,6 +118,76 @@ The class can be used to simulate nested scopes and is useful in templating.
       <http://code.activestate.com/recipes/305268/>`_.
 
 
+:class:`ChainMap` Examples and Recipes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This section shows various approaches to working with chained maps.
+
+
+Example of simulating Python's internal lookup chain::
+
+        import builtins
+        pylookup = ChainMap(locals(), globals(), vars(builtins))
+
+Example of letting user specified values take precedence over environment
+variables which in turn take precedence over default values::
+
+        import os, argparse
+        defaults = {'color': 'red', 'user': guest}
+        parser = argparse.ArgumentParser()
+        parser.add_argument('-u', '--user')
+        parser.add_argument('-c', '--color')
+        user_specified = vars(parser.parse_args())
+        combined = ChainMap(user_specified, os.environ, defaults)
+
+Example patterns for using the :class:`ChainMap` class to simulate nested
+contexts::
+
+        c = ChainMap()        # Create root context
+        d = c.new_child()     # Create nested child context
+        e = c.new_child()     # Child of c, independent from d
+        e.maps[0]             # Current context dictionary -- like Python's locals()
+        e.maps[-1]            # Root context -- like Python's globals()
+        e.parents             # Enclosing context chain -- like Python's nonlocals
+
+        d['x']                # Get first key in the chain of contexts
+        d['x'] = 1            # Set value in current context
+        del['x']              # Delete from current context
+        list(d)               # All nested values
+        k in d                # Check all nested values
+        len(d)                # Number of nested values
+        d.items()             # All nested items
+        dict(d)               # Flatten into a regular dictionary
+
+The :class:`ChainMap` class only makes updates (writes and deletions) to the
+first mapping in the chain while lookups will search the full chain.  However,
+if deep writes and deletions are desired, it is easy to make a subclass that
+updates keys found deeper in the chain::
+
+    class DeepChainMap(ChainMap):
+        'Variant of ChainMap that allows direct updates to inner scopes'
+
+        def __setitem__(self, key, value):
+            for mapping in self.maps:
+                if key in mapping:
+                    mapping[key] = value
+                    return
+            self.maps[0][key] = value
+
+        def __delitem__(self, key):
+            for mapping in self.maps:
+                if key in mapping:
+                    del mapping[key]
+                    return
+            raise KeyError(key)
+
+    >>> d = DeepChainMap({'zebra': 'black'}, {'elephant' : 'blue'}, {'lion' : 'yellow'})
+    >>> d['lion'] = 'orange'         # update an existing key two levels down
+    >>> d['snake'] = 'red'           # new keys get added to the topmost dict
+    >>> del d['elephant']            # remove an existing key one level down
+    DeepChainMap({'zebra': 'black', 'snake': 'red'}, {}, {'lion': 'orange'})
+
+
 :class:`Counter` objects
 ------------------------