dictutils
- Mapping types (OMD)¶
Python has a very powerful mapping type at its core: the dict
type. While versatile and featureful, the dict
prioritizes
simplicity and performance. As a result, it does not retain the order
of item insertion [1], nor does it store multiple values per key. It
is a fast, unordered 1:1 mapping.
The OrderedMultiDict
contrasts to the built-in dict
,
as a relatively maximalist, ordered 1:n subtype of
dict
. Virtually every feature of dict
has been
retooled to be intuitive in the face of this added
complexity. Additional methods have been added, such as
collections.Counter
-like functionality.
A prime advantage of the OrderedMultiDict
(OMD) is its
non-destructive nature. Data can be added to an OMD
without being
rearranged or overwritten. The property can allow the developer to
work more freely with the data, as well as make more assumptions about
where input data will end up in the output, all without any extra
work.
One great example of this is the OMD.inverted()
method, which
returns a new OMD with the values as keys and the keys as values. All
the data and the respective order is still represented in the inverted
form, all from an operation which would be outright wrong and reckless
with a built-in dict
or collections.OrderedDict
.
The OMD has been performance tuned to be suitable for a wide range of usages, including as a basic unordered MultiDict. Special thanks to Mark Williams for all his help.
[1] | As of 2015, basic dicts on PyPy are ordered, and as of December 2017, basic dicts in CPython 3 are now ordered, as well. |
-
boltons.dictutils.
MultiDict
¶ alias of
boltons.dictutils.OrderedMultiDict
-
boltons.dictutils.
OMD
¶ alias of
boltons.dictutils.OrderedMultiDict
-
class
boltons.dictutils.
OrderedMultiDict
(*args, **kwargs)[source]¶ A MultiDict is a dictionary that can have multiple values per key and the OrderedMultiDict (OMD) is a MultiDict that retains original insertion order. Common use cases include:
- handling query strings parsed from URLs
- inverting a dictionary to create a reverse index (values to keys)
- stacking data from multiple dictionaries in a non-destructive way
The OrderedMultiDict constructor is identical to the built-in
dict
, and overall the API constitutes an intuitive superset of the built-in type:>>> omd = OrderedMultiDict() >>> omd['a'] = 1 >>> omd['b'] = 2 >>> omd.add('a', 3) >>> omd.get('a') 3 >>> omd.getlist('a') [1, 3]
Some non-
dict
-like behaviors also make an appearance, such as support forreversed()
:>>> list(reversed(omd)) ['b', 'a']
Note that unlike some other MultiDicts, this OMD gives precedence to the most recent value added.
omd['a']
refers to3
, not1
.>>> omd OrderedMultiDict([('a', 1), ('b', 2), ('a', 3)]) >>> omd.poplast('a') 3 >>> omd OrderedMultiDict([('a', 1), ('b', 2)]) >>> omd.pop('a') 1 >>> omd OrderedMultiDict([('b', 2)])
Note that calling
dict()
on an OMD results in a dict of keys to lists of values:>>> from pprint import pprint as pp # ensuring proper key ordering >>> omd = OrderedMultiDict([('a', 1), ('b', 2), ('a', 3)]) >>> pp(dict(omd)) {'a': [1, 3], 'b': [2]}
Note that modifying those lists will modify the OMD. If you want a safe-to-modify or flat dictionary, use
OrderedMultiDict.todict()
.>>> pp(omd.todict()) {'a': 3, 'b': 2} >>> pp(omd.todict(multi=True)) {'a': [1, 3], 'b': [2]}
With
multi=False
, items appear with the keys in to original insertion order, alongside the most-recently inserted value for that key.>>> OrderedMultiDict([('a', 1), ('b', 2), ('a', 3)]).items(multi=False) [('a', 3), ('b', 2)]
-
addlist
(k, v)[source]¶ Add an iterable of values underneath a specific key, preserving any values already under that key.
>>> omd = OrderedMultiDict([('a', -1)]) >>> omd.addlist('a', range(3)) >>> omd OrderedMultiDict([('a', -1), ('a', 0), ('a', 1), ('a', 2)])
Called
addlist
for consistency withgetlist()
, but tuples and other sequences and iterables work.
-
counts
()[source]¶ Returns a mapping from key to number of values inserted under that key. Like
collections.Counter
, but returns a newOrderedMultiDict
.
-
classmethod
fromkeys
(keys, default=None)[source]¶ Create a dictionary from a list of keys, with all the values set to default, or
None
if default is not set.
-
get
(k, default=None)[source]¶ Return the value for key k if present in the dictionary, else default. If default is not given,
None
is returned. This method never raises aKeyError
.To get all values under a key, use
OrderedMultiDict.getlist()
.
-
getlist
(k, default=_MISSING)[source]¶ Get all values for key k as a list, if k is in the dictionary, else default. The list returned is a copy and can be safely mutated. If default is not given, an empty
list
is returned.
-
inverted
()[source]¶ Returns a new
OrderedMultiDict
with values and keys swapped, like creating dictionary transposition or reverse index. Insertion order is retained and all keys and values are represented in the output.>>> omd = OMD([(0, 2), (1, 2)]) >>> omd.inverted().getlist(2) [0, 1]
Inverting twice yields a copy of the original:
>>> omd.inverted().inverted() OrderedMultiDict([(0, 2), (1, 2)])
-
items
(multi=False)[source]¶ Returns a list containing the output of
iteritems()
. See that method’s docs for more details.
-
iteritems
(multi=False)[source]¶ Iterate over the OMD’s items in insertion order. By default, yields only the most-recently inserted value for each key. Set multi to
True
to get all inserted items.
-
iterkeys
(multi=False)[source]¶ Iterate over the OMD’s keys in insertion order. By default, yields each key once, according to the most recent insertion. Set multi to
True
to get all keys, including duplicates, in insertion order.
-
itervalues
(multi=False)[source]¶ Iterate over the OMD’s values in insertion order. By default, yields the most-recently inserted value per unique key. Set multi to
True
to get all values according to insertion order.
-
keys
(multi=False)[source]¶ Returns a list containing the output of
iterkeys()
. See that method’s docs for more details.
-
pop
(k, default=_MISSING)[source]¶ Remove all values under key k, returning the most-recently inserted value. Raises
KeyError
if the key is not present and no default is provided.
-
popall
(k, default=_MISSING)[source]¶ Remove all values under key k, returning them in the form of a list. Raises
KeyError
if the key is not present and no default is provided.
-
poplast
(k=_MISSING, default=_MISSING)[source]¶ Remove and return the most-recently inserted value under the key k, or the most-recently inserted key if k is not provided. If no values remain under k, it will be removed from the OMD. Raises
KeyError
if k is not present in the dictionary, or the dictionary is empty.
-
setdefault
(k, default=_MISSING)[source]¶ If key k is in the dictionary, return its value. If not, insert k with a value of default and return default. default defaults to
None
. Seedict.setdefault()
for more information.
-
sorted
(key=None, reverse=False)[source]¶ Similar to the built-in
sorted()
, except this method returns a newOrderedMultiDict
sorted by the provided key function, optionally reversed.Parameters: - key (callable) – A callable to determine the sort key of each element. The callable should expect an item (key-value pair tuple).
- reverse (bool) – Set to
True
to reverse the ordering.
>>> omd = OrderedMultiDict(zip(range(3), range(3))) >>> omd.sorted(reverse=True) OrderedMultiDict([(2, 2), (1, 1), (0, 0)])
Note that the key function receives an item (key-value tuple), so the recommended signature looks like:
>>> omd = OrderedMultiDict(zip('hello', 'world')) >>> omd.sorted(key=lambda i: i[1]) # i[0] is the key, i[1] is the val OrderedMultiDict([('o', 'd'), ('l', 'l'), ('e', 'o'), ('h', 'w')])
-
sortedvalues
(key=None, reverse=False)[source]¶ Returns a copy of the
OrderedMultiDict
with the same keys in the same order as the original OMD, but the values within each keyspace have been sorted according to key and reverse.Parameters: - key (callable) – A single-argument callable to determine the sort key of each element. The callable should expect an item (key-value pair tuple).
- reverse (bool) – Set to
True
to reverse the ordering.
>>> omd = OrderedMultiDict() >>> omd.addlist('even', [6, 2]) >>> omd.addlist('odd', [1, 5]) >>> omd.add('even', 4) >>> omd.add('odd', 3) >>> somd = omd.sortedvalues() >>> somd.getlist('even') [2, 4, 6] >>> somd.keys(multi=True) == omd.keys(multi=True) True >>> omd == somd False >>> somd OrderedMultiDict([('even', 2), ('even', 4), ('odd', 1), ('odd', 3), ('even', 6), ('odd', 5)])
As demonstrated above, contents and key order are retained. Only value order changes.
-
todict
(multi=False)[source]¶ Gets a basic
dict
of the items in this dictionary. Keys are the same as the OMD, values are the most recently inserted values for each key.Setting the multi arg to
True
is yields the same result as callingdict
on the OMD, except that all the value lists are copies that can be safely mutated.
-
update
(E, **F)[source]¶ Add items from a dictionary or iterable (and/or keyword arguments), overwriting values under an existing key. See
dict.update()
for more details.
-
update_extend
(E, **F)[source]¶ Add items from a dictionary, iterable, and/or keyword arguments without overwriting existing items present in the dictionary. Like
update()
, but adds to existing keys instead of overwriting them.
-
values
(multi=False)[source]¶ Returns a list containing the output of
itervalues()
. See that method’s docs for more details.
-
class
boltons.dictutils.
OneToOne
(*a, **kw)[source]¶ Implements a one-to-one mapping dictionary. In addition to inheriting from and behaving exactly like the builtin
dict
, all values are automatically added as keys on a reverse mapping, available as the inv attribute. This arrangement keeps key and value namespaces distinct.Basic operations are intuitive:
>>> oto = OneToOne({'a': 1, 'b': 2}) >>> print(oto['a']) 1 >>> print(oto.inv[1]) a >>> len(oto) 2
Overwrites happens in both directions:
>>> oto.inv[1] = 'c' >>> print(oto.get('a')) None >>> len(oto) 2
For a very similar project, with even more one-to-one functionality, check out bidict.
-
inv
¶
-
pop
(k[, d]) → v, remove specified key and return the corresponding value.[source]¶ If key is not found, d is returned if given, otherwise KeyError is raised
-