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.

alias of OrderedMultiDict


alias of 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')
>>> omd.getlist('a')
[1, 3]

Some non-dict-like behaviors also make an appearance, such as support for reversed():

>>> list(reversed(omd))
['b', 'a']

Note that unlike some other MultiDicts, this OMD gives precedence to the most recent value added. omd['a'] refers to 3, not 1.

>>> omd
OrderedMultiDict([('a', 1), ('b', 2), ('a', 3)])
>>> omd.poplast('a')
>>> omd
OrderedMultiDict([('a', 1), ('b', 2)])
>>> omd.pop('a')
>>> 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)]
add(k, v)[source]

Add a single value v under a key k. Existing values under k are preserved.

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 with getlist(), but tuples and other sequences and iterables work.


Empty the dictionary.


Return a shallow copy of the dictionary.


Returns a mapping from key to number of values inserted under that key. Like collections.Counter, but returns a new OrderedMultiDict.

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 a KeyError.

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.


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)])

Returns a list containing the output of iteritems(). See that method’s docs for more details.


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.


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.


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.


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. See dict.setdefault() for more information.

sorted(key=None, reverse=False)[source]

Similar to the built-in sorted(), except this method returns a new OrderedMultiDict sorted by the provided key function, optionally reversed.

  • 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.

  • 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)
>>> omd == somd
>>> 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.


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 calling dict 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.


Returns a list containing the output of itervalues(). See that method’s docs for more details.

viewitems() → a set-like object providing a view on OMD's items[source]
viewkeys() → a set-like object providing a view on OMD's keys[source]
viewvalues() → an object providing a view on OMD's values[source]
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'])
>>> print(oto.inv[1])
>>> len(oto)

Overwrites happens in both directions:

>>> oto.inv[1] = 'c'
>>> print(oto.get('a'))
>>> len(oto)
pop(key, default=_MISSING)[source]
setdefault(key, default=None)[source]
update(dict_or_iterable, **kw)[source]