classification
Title: Make ChainMap() public in the collections module.
Type: enhancement Stage:
Components: Versions: Python 3.3
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: alex, daniel.urban, eric.araujo, pitrou, r.david.murray, rhettinger
Priority: low Keywords: patch

Created on 2011-02-23 10:22 by rhettinger, last changed 2011-02-26 01:20 by eric.araujo. This issue is now closed.

Files
File name Uploaded Description Edit
chainmap.diff rhettinger, 2011-02-23 10:22 Documentation patch
Messages (11)
msg129161 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-02-23 10:22
Attaching a documentation patch.
msg129162 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-02-23 10:35
This is nice, but IMO there is some information lacking, e.g.:
- when an underlying mapping is mutated, does the ChainMap get updated too?
- does it work with arbitrary mappings or only with dicts or dicts subclasses?

I think new_child() isn't very useful. It seems two specialized for a one-liner. Ditto for parents().
msg129163 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-02-23 10:35
("too specialized", sorry)
msg129216 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-02-23 16:55
I don't think that new_child and parents are too specialized at all, indeed they are essential to one of the primary use cases for the construct.  I find Django's push and pop much more intuitive than new_child and parents, however, and would prefer those methods.
msg129217 - (view) Author: Alex Gaynor (alex) * (Python committer) Date: 2011-02-23 18:19
An important distinction with Django's push/pop is that they mutate the Context (ChainMap) rather than return a fresh instance.
msg129218 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-02-23 18:39
Yes, that's part of what I find more intuitive about it.  I think of the chainmap as a stack.  Perhaps if I had a different application (I would use it for either configuration or namespace management) I'd want a different API, but for those two the stack approach seems most natural to me.

In particular, since only the top dict can be updated, it seems most natural to pop it off the top of the stack in order to modify the next one down (and then push it back, if desired).  If instead the way to modify the next one down is to do parents, then I'm mutating the chainmap I just did the parents call on, but I'm not referencing that object, I'm referencing the one I got back from the parents call.  It just seems more natural that the mutation operations should be carried out via a single chainmap object by using pop and push rather than effectively modifying (potentially multiple) chainmap objects by manipulating other chainmap objects.  (Yes, I realize that it is really the underlying dicts that are being modified, but conceptually I'm thinking of the chainmap as a single data structure).
msg129220 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-02-23 19:41
FWIW, the new_child() and parents() part of the API was modeled after contexts in ANLTR where they are needed to overcome the limitations of Django's push/pop style which precludes a context from having multiple, independent children at the same time.  The module docstring in the http://code.activestate.com/recipes/577434/ recipe shows how new_child() can be used to easily model both dynamic scoping and nested scoping.

The other advantage of the new_child/parents API over the push/pop API is that it overcomes the occasional templating need to keep two copies of the context (before a push and after a push).

In some ways, it is more difficult to keep track of a mutating chain that is being continuously pushed and popped.  It is simpler to assign a chain to a variable and always know that it is associated with a given template and not have to worry about whether some utility function pushed a new context and failed to pop it when it was done.  A push/pop style introduces the same problems as matching matching malloc() with free() in C.
msg129439 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-02-25 21:56
Minor doc issue: s/__builtin__/builtins/
msg129482 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-02-26 01:08
Antoine.  Thanks.  I put in a paragraph re-emphasizing that ChainMap is a view and that changes in the underlying mappings get reflected in the ChainMap.  Also, the first sentence says that ChainMap groups multiple dicts or other mappings.  So, any mapping-like object will work.

Éric, I changed built-in to builtin.  It is used as an adjetive, not as a module reference (that's the usual practice when referring the builtin functions).

See r88628.
msg129483 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-02-26 01:13
I was thinking of adding a recipes section to show how to extend or override the class:

class DjangoContext(ChainMap):
   def push(self):
       self.maps.insert(0, {})
   def pop(self):
       self.maps.pop(0)

class NestedScope(ChainMap):
   'Mutating methods that write to first matching dict'

    def __setitem__(self, key, value):
        '''Find the first matching *key* in chain and set its value.
        If not found, sets in maps[0].

        '''
        for m in self.maps:
            if key in m:
                break
        else:
            m = self.maps[0]
        try:
            cs = m.chain_set
        except AttributeError:
            m[key] = value
        else:
            cs(key, value)

    def __delitem__(self, key):
        '''Find and delete the first matching *key* in the chain.
        Raise KeyError if not found.

        '''
        for m in self.maps:
            if key in m:
                break
        try:
            cd = m.chain_del
        except AttributeError:
            del m[key]
        else:
            cd(key)

    def popitem(self):
        for m in self.maps:
            if m:
                break
        return m.popitem()

    def clear(self):
        for m in self.maps:
            m.clear()
msg129484 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-02-26 01:20
Raymond: Sorry I was imprecise.  I was referring specifically to “import __builtin__” in collections.rst.
History
Date User Action Args
2011-02-26 01:20:32eric.araujosetnosy: rhettinger, pitrou, eric.araujo, alex, r.david.murray, daniel.urban
messages: + msg129484
2011-02-26 01:13:03rhettingersetnosy: rhettinger, pitrou, eric.araujo, alex, r.david.murray, daniel.urban
messages: + msg129483
2011-02-26 01:08:11rhettingersetstatus: open -> closed

messages: + msg129482
resolution: fixed
nosy: rhettinger, pitrou, eric.araujo, alex, r.david.murray, daniel.urban
2011-02-25 21:56:05eric.araujosetnosy: + eric.araujo
messages: + msg129439
2011-02-23 19:41:04rhettingersetnosy: rhettinger, pitrou, alex, r.david.murray, daniel.urban
messages: + msg129220
2011-02-23 18:39:15r.david.murraysetnosy: rhettinger, pitrou, alex, r.david.murray, daniel.urban
messages: + msg129218
2011-02-23 18:19:58alexsetnosy: + alex
messages: + msg129217
2011-02-23 16:55:53r.david.murraysetnosy: + r.david.murray
messages: + msg129216
2011-02-23 16:26:06daniel.urbansetnosy: + daniel.urban
2011-02-23 10:35:22pitrousetmessages: + msg129163
2011-02-23 10:35:07pitrousetnosy: + pitrou
messages: + msg129162
2011-02-23 10:22:35rhettingercreate