wardrobe.stackeddict

StackedDict implementation.

exception wardrobe.stackeddict.NoRevisionException

Exception raised when reset() has been called more times than commit().

args

message

class wardrobe.stackeddict.StackedDict(initial=None, **kwargs)

Dictionary-like object made of stacked layers.

Instances act like dictionaries.

Calls to push() or pop() affect (respectively create or delete) one entire layer of the stack.

>>> from wardrobe import StackedDict
>>> clark = StackedDict(top='blue bodysuit', bottom='red underpants',
...                     sex_appeal=True)
>>> clark['bottom']
'red underpants'
>>> clark['friend'] = 'Lois'
>>> dict(clark) == {'top': 'blue bodysuit',
...                 'bottom': 'red underpants',
...                 'friend': 'Lois',
...                 'sex_appeal': True}
True
>>> clark.commit()  
<wardrobe.stackeddict.StackedDict object at 0x...>
>>> clark.update({'top': 'shirt', 'bottom': 'jeans', 'head': 'glasses'})
>>> del clark['sex_appeal']
>>> dict(clark) == {'top': 'shirt',
...                 'bottom': 'jeans',
...                 'head': 'glasses',
...                 'friend': 'Lois'}
True
>>> clark.reset()  
<wardrobe.stackeddict.StackedDict object at 0x...>
>>> dict(clark) == {'top': 'blue bodysuit',
...                 'bottom': 'red underpants',
...                 'friend': 'Lois',
...                 'sex_appeal': True}
True

clear()

Remove all items from the dictionary.

>>> s = StackedDict(a=1, b=2, c=3)
>>> s.clear()
>>> dict(s)
{}

Affects only current layer.

>>> s = StackedDict(a=1, b=2, c=3)
>>> s.commit().update(c='C', d=4, e=5)
>>> s.clear()
>>> dict(s)
{}
>>> silent = s.reset()
>>> dict(s) == dict(a=1, b=2, c=3)
True

commit()

Save current dictionary state, record next changes in some diff history.

Returns StackedDict instance, so that you can chain operations.

Use reset() to restore the saved state.

>>> s = StackedDict(a=1)
>>> s.commit().update(a='A')
>>> dict(s)
{'a': 'A'}
>>> silent = s.reset()
>>> dict(s)
{'a': 1}

copy()

Return a shallow copy of instance.

>>> s1 = StackedDict(a=1, b=2, c=3)
>>> s2 = s1.copy()
>>> s1 == s2
True
>>> s1 is s2
False

classmethod fromkeys(seq, value=None)

Create a new StackedDict with keys from seq and values set to value.

fromkeys() is a class method that returns a new StackedDict. value defaults to None.

>>> s = StackedDict.fromkeys(['a', 'b', 'c'])
>>> filter(lambda x: x is not None, s.values())
[]

>>> s = StackedDict.fromkeys(['a', 'b', 'c'], 42)
>>> filter(lambda x: x is not 42, s.values())
[]

>>> s = StackedDict.fromkeys(range(1, 5), 'Hello world!')
>>> filter(lambda x: x != 'Hello world!', s.values())
[]

get(key, default=None)

Return the value for key if key is in the dictionary, else default.

If default is not given, it defaults to None, so that this method never raises a KeyError.

>>> s = StackedDict(a=1)
>>> s.get('a')
1
>>> s.get('b') is None
True
>>> s.get('b', 2)
2

has_key(key)

Return True if key is in instance, False otherwise.

Affects global instance, not “only the current layer”.

>>> s = StackedDict(a=1, b=2, c=3)
>>> s.has_key('a')
True
>>> s.has_key('b')
True
>>> s.has_key(1)
False
>>> s.commit()  
<wardrobe.stackeddict.StackedDict object at 0x...>
>>> s.has_key('a')
True
>>> del s['a']
>>> s.has_key('a')
False
>>> s.commit()  
<wardrobe.stackeddict.StackedDict object at 0x...>
>>> s.has_key('a')
False

items()

Return a copy of the StackedDict’s list of (key, value) pairs.

>>> s = StackedDict(a=1, b=2)
>>> i = s.items()
>>> i.sort()
>>> i
[('a', 1), ('b', 2)]
>>> s.commit().update(c=3)
>>> i = s.items()
>>> i.sort()
>>> i
[('a', 1), ('b', 2), ('c', 3)]

iteritems()

Return an iterator over the StackedDict’s (key, value) pairs.

>>> s = StackedDict(a=1, b=2)
>>> i = s.iteritems()
>>> i  
<generator object iteritems at 0x...>
>>> i = list(i)
>>> i.sort()
>>> i
[('a', 1), ('b', 2)]
>>> s.commit().update(c=3)
>>> i = s.iteritems()
>>> i  
<generator object iteritems at 0x...>
>>> i = list(i)
>>> i.sort()
>>> i
[('a', 1), ('b', 2), ('c', 3)]

iterkeys()

Return an iterator over the StackedDict’s keys.

>>> s = StackedDict(a=1, b=2, c=3)
>>> i = s.iterkeys()
>>> i  
<generator object iterkeys at 0x...>
>>> l = list(i)
>>> l.sort()
>>> l
['a', 'b', 'c']

itervalues()

Return an iterator over the StackedDict’s values.

>>> s = StackedDict(a=1, b=2, c=3)
>>> i = s.itervalues()
>>> i  
<generator object itervalues at 0x...>
>>> l = list(i)
>>> l.sort()
>>> l
[1, 2, 3]

keys()

Return iterable on keys.

>>> s = StackedDict(a=1, b=2, c=3)
>>> keys = s.keys()
>>> len(keys) == 3
True
>>> 'a' in keys and 'b' in keys and 'c' in keys
True

Deleted keys aren’t returned... until the layer where the key was deleted is dropped.

>>> s = StackedDict(a=1)
>>> s.keys()
['a']
>>> silent = s.commit()
>>> del s['a']
>>> s.keys()
[]
>>> silent = s.commit()
>>> s.keys()
[]
>>> silent = s.reset()
>>> s.keys()
[]
>>> silent = s.reset()
>>> s.keys()
['a']

pop(key, *args)

If key is in the dictionary, remove it and return its value, else return default.

>>> s = StackedDict(a=1, b=2, c=3)
>>> s.pop('a')
1
>>> 'a' in s
False
>>> s.pop('a', 'A')
'A'

If default is not given and key is not in the dictionary, a KeyError is raised.

>>> s = StackedDict()
>>> s.pop('a')
Traceback (most recent call last):
...
KeyError: 'a'

Affects only current layer.

>>> s = StackedDict(a=1, b=2, c=3)
>>> s.commit()  
<wardrobe.stackeddict.StackedDict object at 0x...>
>>> s.pop('b')
2
>>> silent = s.reset()
>>> s['b']
2

popitem()

Remove and return some (key, value) pair as a 2-tuple.

>>> s = StackedDict(a=1)
>>> s.popitem()
('a', 1)
>>> len(s)
0

Raises KeyError if D is empty.

>>> s = StackedDict()
>>> s.popitem()
Traceback (most recent call last):
...
KeyError: 'popitem(): dictionary is empty'

Affects only the current layer.

>>> s = StackedDict(a=1)
>>> silent = s.commit()
>>> s.popitem()
('a', 1)
>>> silent = s.reset()
>>> dict(s)
{'a': 1}

reset()

Restore dictionary to state before last commit().

>>> s = StackedDict(a=1, b=2)
>>> s.commit().update(c=3, d=4)
>>> s.reset()  
<wardrobe.stackeddict.StackedDict object at 0x...>
>>> dict(s)
{'a': 1, 'b': 2}
>>> s.commit().update(a='A', b='B')
>>> s.reset()  
<wardrobe.stackeddict.StackedDict object at 0x...>
>>> dict(s)
{'a': 1, 'b': 2}
>>> s.commit().update(a='A', c=3)
>>> s.reset()  
<wardrobe.stackeddict.StackedDict object at 0x...>
>>> dict(s)
{'a': 1, 'b': 2}

Raises NoRevisionException when invoked on a StackedDict instance that hasn’t been pushed yet.

>>> s = StackedDict()
>>> s.reset()
Traceback (most recent call last):
...
NoRevisionException

setdefault(key, default=None)

If key is in the dictionary, return its value. If not, insert key with a value of default and return default. default defaults to None.

>>> s = StackedDict()
>>> s.setdefault('a', 1)
1
>>> s.setdefault('a', 2)
1
>>> s.setdefault('b') is None
True

update(*args, **kwargs)

Update instance from dict (positional argument) and/or iterable (keyword arguments).

Affects only current layer.

Positional argument can be a dict...

>>> s = StackedDict(a=1, b=2)
>>> s.update({'a': 'A', 'c': 3})
>>> dict(s) == {'a': 'A', 'b': 2, 'c': 3}
True

... or any object that can be converted to a dict.

>>> s = StackedDict(a=1, b=2)
>>> s.update((('a', 'A'), ('c', 3)))
>>> dict(s) == {'a': 'A', 'b': 2, 'c': 3}
True

Also accepts input as keyword arguments.

>>> s = StackedDict(a=1, b=2)
>>> s.update(a='A', c=3)
>>> dict(s) == {'a': 'A', 'b': 2, 'c': 3}
True

A combination of positional and keyword arguments is accepted. The positional argument is handled as a dict.

>>> s = StackedDict(a=1, b=2)
>>> s.update({'a': 'A'}, c=3)
>>> dict(s) == {'a': 'A', 'b': 2, 'c': 3}
True

But only one positional argument is accepted. This mimics a limitation of the standard dict type.

>>> s = StackedDict(a=1, b=2)
>>> s.update({'a': 'A'}, {'c': 3})
Traceback (most recent call last):
...
TypeError: update expected at most 1 arguments, got 2

values()

Return a copy of the StackedDict’s list of values.

>>> s = StackedDict(a=1, b=2)
>>> values = s.values()
>>> values.sort()
>>> values
[1, 2]

viewitems()

Return a new view of the StackedDict’s items ((key, value) pairs).

See http://docs.python.org/library/stdtypes.html#dictionary-view-objects for documentation of view objects.

>>> s = StackedDict()
>>> view = s.viewitems()
>>> view
dict_items([])
>>> s.update(a=1)
>>> view
dict_items([('a', 1)])
>>> s.commit().update(a='A')
>>> view
dict_items([('a', 'A')])

viewkeys()

See http://docs.python.org/library/stdtypes.html#dictionary-view-objects for documentation of view objects.

>>> s = StackedDict()
>>> view = s.viewkeys()
>>> view
dict_keys([])
>>> s.update(a=1)
>>> view
dict_keys(['a'])
>>> s.commit()  
<wardrobe.stackeddict.StackedDict object at 0x...>
>>> del s['a']
>>> s['b'] = 2
>>> view
dict_keys(['b'])

viewvalues()

See http://docs.python.org/library/stdtypes.html#dictionary-view-objects for documentation of view objects.

>>> s = StackedDict()
>>> view = s.viewvalues()
>>> view
dict_values([])
>>> s.update(a=1)
>>> view
dict_values([1])
>>> s.commit()  
<wardrobe.stackeddict.StackedDict object at 0x...>
>>> del s['a']
>>> s['b'] = 2
>>> view
dict_values([2])