Kaydet (Commit) bfcb4293 authored tarafından Raymond Hettinger's avatar Raymond Hettinger

Expand examples for ChainMap(). Improve markup.

üst 9253862f
......@@ -93,13 +93,44 @@ 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::
.. seealso::
* The `MultiContext class
<http://svn.enthought.com/svn/enthought/CodeTools/trunk/enthought/contexts/multi_context.py>`_
in the Enthought `CodeTools package
<https://github.com/enthought/codetools>`_ has options to support
writing to any mapping in the chain.
* Django's `Context class
<http://code.djangoproject.com/browser/django/trunk/django/template/context.py>`_
for templating is a read-only chain of mappings. It also features
pushing and popping of contexts similar to the
:meth:`~collections.ChainMap.new_child` method and the
:meth:`~collections.ChainMap.parents` property.
* The `Nested Contexts recipe
<http://code.activestate.com/recipes/577434/>`_ has options to control
whether writes and other mutations apply only to the first mapping or to
any mapping in the chain.
* A `greatly simplified read-only version of Chainmap
<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::
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}
......@@ -109,8 +140,8 @@ The class can be used to simulate nested scopes and is useful in templating.
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::
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
......@@ -128,28 +159,33 @@ The class can be used to simulate nested scopes and is useful in templating.
d.items() # All nested items
dict(d) # Flatten into a regular dictionary
.. seealso::
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::
* The `MultiContext class
<http://svn.enthought.com/svn/enthought/CodeTools/trunk/enthought/contexts/multi_context.py>`_
in the Enthought `CodeTools package
<https://github.com/enthought/codetools>`_ has options to support
writing to any mapping in the chain.
class DeepChainMap(ChainMap):
'Variant of ChainMap that allows direct updates to inner scopes'
* Django's `Context class
<http://code.djangoproject.com/browser/django/trunk/django/template/context.py>`_
for templating is a read-only chain of mappings. It also features
pushing and popping of contexts similar to the
:meth:`~collections.ChainMap.new_child` method and the
:meth:`~collections.ChainMap.parents` property.
* The `Nested Contexts recipe
<http://code.activestate.com/recipes/577434/>`_ has options to control
whether writes and other mutations apply only to the first mapping or to
any mapping in the chain.
* A `greatly simplified read-only version of Chainmap
<http://code.activestate.com/recipes/305268/>`_.
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
......@@ -326,23 +362,23 @@ or subtracting from an empty counter.
.. seealso::
* `Counter class <http://code.activestate.com/recipes/576611/>`_
adapted for Python 2.5 and an early `Bag recipe
<http://code.activestate.com/recipes/259174/>`_ for Python 2.4.
adapted for Python 2.5 and an early `Bag recipe
<http://code.activestate.com/recipes/259174/>`_ for Python 2.4.
* `Bag class <http://www.gnu.org/software/smalltalk/manual-base/html_node/Bag.html>`_
in Smalltalk.
in Smalltalk.
* Wikipedia entry for `Multisets <http://en.wikipedia.org/wiki/Multiset>`_.
* `C++ multisets <http://www.demo2s.com/Tutorial/Cpp/0380__set-multiset/Catalog0380__set-multiset.htm>`_
tutorial with examples.
tutorial with examples.
* For mathematical operations on multisets and their use cases, see
*Knuth, Donald. The Art of Computer Programming Volume II,
Section 4.6.3, Exercise 19*.
*Knuth, Donald. The Art of Computer Programming Volume II,
Section 4.6.3, Exercise 19*.
* To enumerate all distinct multisets of a given size over a given set of
elements, see :func:`itertools.combinations_with_replacement`.
elements, see :func:`itertools.combinations_with_replacement`.
map(Counter, combinations_with_replacement('ABC', 2)) --> AA AB AC BB BC CC
......@@ -876,14 +912,14 @@ and more efficient to use a simple class declaration:
.. seealso::
* `Named tuple recipe <http://code.activestate.com/recipes/500261/>`_
adapted for Python 2.4.
adapted for Python 2.4.
* `Recipe for named tuple abstract base class with a metaclass mix-in
<http://code.activestate.com/recipes/577629-namedtupleabc-abstract-base-class-mix-in-for-named/>`_
by Jan Kaliszewski. Besides providing an :term:`abstract base class` for
named tuples, it also supports an alternate :term:`metaclass`-based
constructor that is convenient for use cases where named tuples are being
subclassed.
<http://code.activestate.com/recipes/577629-namedtupleabc-abstract-base-class-mix-in-for-named/>`_
by Jan Kaliszewski. Besides providing an :term:`abstract base class` for
named tuples, it also supports an alternate :term:`metaclass`-based
constructor that is convenient for use cases where named tuples are being
subclassed.
:class:`OrderedDict` objects
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment