API docs: fresco.multidict

An order preserving multidict implementation

class fresco.multidict.MultiDict(*args, **kwargs)

Dictionary-like object that supports multiple values per key. Insertion order is preserved.

Synopsis:

>>> from fresco.multidict import MultiDict
>>> d = MultiDict([('a', 1), ('a', 2), ('b', 3)])
>>> d['a']
1
>>> d['b']
3
>>> d.getlist('a')
[1, 2]
>>> d.getlist('b')
[3]
>>> list(d.allitems())
[('a', 1), ('a', 2), ('b', 3)]
allitems()

Return (key, value) pairs for each item in the MultiDict. Items with multiple keys will have multiple key-value pairs returned:

>>> from fresco.multidict import MultiDict
>>> d = MultiDict([('a', 1), ('a', 2), ('b', 3)])
>>> list(d.allitems())
[('a', 1), ('a', 2), ('b', 3)]
copy()

Return a shallow copy of the dictionary:

>>> d = MultiDict([('a', 1), ('a', 2), ('b', 3)])
>>> copy = d.copy()
>>> copy
MultiDict([('a', 1), ('a', 2), ('b', 3)])
>>> copy is d
False
extend(*args, **kwargs)

Extend the MultiDict with another MultiDict, regular dictionary or a iterable of (key, value) pairs. This is similar to update() except that new keys are added to old keys.

classmethod fromkeys(seq, value=None)

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

Example:

>>> MultiDict.fromkeys(['a', 'b'])
MultiDict([('a', None), ('b', None)])

Keys can be repeated:

>>> d = MultiDict.fromkeys(['a', 'b', 'a'])
>>> d.getlist('a')
[None, None]
>>> d.getlist('b')
[None]
get(key, default=None)

Return the first available value for key key, or default if no such value exists:

>>> d = MultiDict([('a', 1), ('a', 2)])
>>> print(d.get('a'))
1
>>> print(d.get('b'))
None
getlist(key)

Return a list of all values for key key.

items()

Return a list of (key, value) tuples. Only the first (key, value) is returned where keys have multiple values:

>>> d = MultiDict([('a', 1), ('a', 2), ('b', 3)])
>>> list(d.items())
[('a', 1), ('b', 3)]
keys()

Return dictionary keys. Each key is returned only once, even if multiple values are present.

>>> from fresco.multidict import MultiDict
>>> d = MultiDict([('a', 1), ('a', 2), ('b', 3)])
>>> list(d.keys())
['a', 'b']
listitems()

Like items, but returns lists of values:

>>> d = MultiDict([('a', 1), ('a', 2), ('b', 3)])
>>> list(d.listitems())
[('a', [1, 2]), ('b', [3])]
listvalues()

Return an iterator over lists of values. Each item will be the list of values associated with a single key.

Example usage:

>>> from fresco.multidict import MultiDict
>>> d = MultiDict([('a', 1), ('a', 2), ('b', 3)])
>>> list(d.listvalues())
[[1, 2], [3]]
pop(key, *args)

Dictionary pop method. Return and remove the value associated with key. If more than one value is associated with key, only the first is returned.

Example usage:

>>> d = MultiDict([('a', 1), ('a', 2), ('b', 3)])
>>> d.pop('a')
1
>>> d
MultiDict([('a', 2), ('b', 3)])
>>> d.pop('a')
2
>>> d
MultiDict([('b', 3)])
>>> d.pop('a')
Traceback (most recent call last):
    ...
KeyError: 'a'
popitem()

Return and remove a (key, value) pair from the dictionary.

The item popped is always the most recently added key and the first value associated with it:

>>> d = MultiDict([('a', 1), ('a', 2), ('b', 3)])
>>> d.popitem()
('b', 3)
>>> d.popitem()
('a', 1)
>>> d.popitem()
('a', 2)
>>> d.popitem() 
Traceback (most recent call last):
    ...
KeyError: 'popitem(): dictionary is empty'
setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
update(*args, **kwargs)

Update the MultiDict from another MultiDict, regular dictionary or a iterable of (key, value) pairs. New keys overwrite old keys - use extend() if you want new keys to be added to old keys.

Updating from another MultiDict:

>>> d = MultiDict([('name', 'eric'), ('occupation', 'lumberjack')])
>>> d.update(MultiDict([('mood', 'okay')]))
>>> d
MultiDict([('name', 'eric'), ('occupation', 'lumberjack'), ('mood', 'okay')])

from a dictionary:

>>> d = MultiDict([('name', 'eric'), ('hobby', 'shopping')])
>>> d.update({'hobby': 'pressing wild flowers'})
>>> d
MultiDict([('name', 'eric'), ('hobby', 'pressing wild flowers')])

an iterable of (key, value) pairs:

>>> d = MultiDict([('name', 'eric'), ('occupation', 'lumberjack')])
>>> d.update([('hobby', 'shopping'),
...           ('hobby', 'pressing wild flowers')])
>>> d
MultiDict([('name', 'eric'), ('occupation', 'lumberjack'), ('hobby', 'shopping'), ('hobby', 'pressing wild flowers')])

or keyword arguments:

>>> d = MultiDict([('name', 'eric'),\
...                ('occupation', 'lumberjack')])
>>> d.update(mood='okay')
values()

Return values from the dictionary. Where keys have multiple values, only the first is returned:

>>> from fresco.multidict import MultiDict
>>> d = MultiDict([('a', 1), ('a', 2), ('b', 3)])
>>> list(d.values())
[1, 3]