Reference

MultiDict

class multidict.MultiDict(**kwargs)
class multidict.MultiDict(mapping, **kwargs)
class multidict.MultiDict(iterable, **kwargs)

Creates a mutable multidict instance.

Accepted parameters are the same as for dict. If the same key appears several times it will be added, e.g.:

>>> d = MultiDict([('a', 1), ('b', 2), ('a', 3)])
>>> d
<MultiDict ('a': 1, 'b': 2, 'a': 3)>
len(d)

Return the number of items in multidict d.

d[key]

Return the first item of d with key key.

Raises a KeyError if key is not in the multidict.

d[key] = value

Set d[key] to value.

Replace all items where key is equal to key with single item (key, value).

del d[key]

Remove all items where key is equal to key from d. Raises a KeyError if key is not in the map.

key in d

Return True if d has a key key, else False.

key not in d

Equivalent to not (key in d)

iter(d)

Return an iterator over the keys of the dictionary. This is a shortcut for iter(d.keys()).

add(key, value)

Append (key, value) pair to the dictionary.

clear()

Remove all items from the dictionary.

copy()

Return a shallow copy of the dictionary.

extend([other])

Extend the dictionary with the key/value pairs from other, overwriting existing keys. Return None.

extend() accepts either another dictionary object or an iterable of key/value pairs (as tuples or other iterables of length two). If keyword arguments are specified, the dictionary is then extended with those key/value pairs: d.extend(red=1, blue=2).

getone(key[, default])

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

Raises KeyError if default is not given and key is not found.

d[key] is equivalent to d.getone(key).

getall(key[, default])

Return a list of all values for key if key is in the dictionary, else default.

Raises KeyError if default is not given and key is not found.

get(key[, default])

Return the first 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.

d.get(key) is equivalent to d.getone(key, None).

keys()

Return a new view of the dictionary’s keys.

View contains all keys, possibly with duplicates.

items()

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

View contains all items, multiple items can have the same key.

values()

Return a new view of the dictionary’s values.

View contains all values.

popone(key[, default])

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

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

New in version 3.0.

pop(key[, default])

An alias to pop()

Changed in version 3.0: Now only first occurrence is removed (was all).

popall(key[, default])

If key is in the dictionary, remove all occurrences and return a list of all values in corresponding order (as getall() does).

If key is not found and default is provided return default.

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

New in version 3.0.

popitem()

Remove and return an arbitrary (key, value) pair from the dictionary.

popitem() is useful to destructively iterate over a dictionary, as often used in set algorithms.

If the dictionary is empty, calling popitem() raises a KeyError.

setdefault(key[, default])

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

update([other])

Update the dictionary with the key/value pairs from other, overwriting existing keys.

Return None.

update() accepts either another dictionary object or an iterable of key/value pairs (as tuples or other iterables of length two). If keyword arguments are specified, the dictionary is then updated with those key/value pairs: d.update(red=1, blue=2).

See also

MultiDictProxy can be used to create a read-only view of a MultiDict.

CIMultiDict

class multidict.CIMultiDict(**kwargs)
class multidict.CIMultiDict(mapping, **kwargs)
class multidict.CIMultiDict(iterable, **kwargs)

Create a case insensitive multidict instance.

The behavior is the same as of MultiDict but key comparisons are case insensitive, e.g.:

>>> dct = CIMultiDict(a='val')
>>> 'A' in dct
True
>>> dct['A']
'val'
>>> dct['a']
'val'
>>> dct['b'] = 'new val'
>>> dct['B']
'new val'

The class is inherited from MultiDict.

See also

CIMultiDictProxy can be used to create a read-only view of a CIMultiDict.

MultiDictProxy

class multidict.MultiDictProxy(multidict)

Create an immutable multidict proxy.

It provides a dynamic view on the multidict’s entries, which means that when the multidict changes, the view reflects these changes.

Raises TypeError is multidict is not MultiDict instance.

len(d)

Return number of items in multidict d.

d[key]

Return the first item of d with key key.

Raises a KeyError if key is not in the multidict.

key in d

Return True if d has a key key, else False.

key not in d

Equivalent to not (key in d)

iter(d)

Return an iterator over the keys of the dictionary. This is a shortcut for iter(d.keys()).

copy()

Return a shallow copy of the underlying multidict.

getone(key[, default])

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

Raises KeyError if default is not given and key is not found.

d[key] is equivalent to d.getone(key).

getall(key[, default])

Return a list of all values for key if key is in the dictionary, else default.

Raises KeyError if default is not given and key is not found.

get(key[, default])

Return the first 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.

d.get(key) is equivalent to d.getone(key, None).

keys()

Return a new view of the dictionary’s keys.

View contains all keys, possibly with duplicates.

items()

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

View contains all items, multiple items can have the same key.

values()

Return a new view of the dictionary’s values.

View contains all values.

CIMultiDictProxy

class multidict.CIMultiDictProxy(multidict)

Case insensitive version of MultiDictProxy.

Raises TypeError is multidict is not CIMultiDict instance.

The class is inherited from MultiDict.

Version

All multidicts have an internal version flag. It’s changed on every dict update, thus the flag could be used for checks like cache expiring etc.

multidict.getversion(mdict)

Return a version of given mdict object (works for proxies also).

The type of returned value is opaque and should be used for equality tests only (== and !=), ordering is not allowed while not prohibited explicitly.

New in version 3.0.

See also

PEP 509

istr

CIMultiDict accepts str as key argument for dict lookups but converts it to title case internally.

Title case means every word in key will be capitalized, e.g. istr('content-length') internally will be converted to 'Content-Length'.

For more effective processing it should know if the key is already title cased.

To skip the title() call you may want to create title cased strings by hand, e.g:

>>> key = istr('Key')
>>> key
'Key'
>>> mdict = CIMultiDict(key='value')
>>> key in mdict
True
>>> mdict[key]
'value'

For performance you should create istr strings once and store them globally, like aiohttp.hdrs does.

class multidict.istr(object='')
class multidict.istr(bytes_or_buffer[, encoding[, errors]])

Create a new title cased string object from the given object. If encoding or errors are specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler.

Otherwise, returns the result of object.__str__() (if defined) or repr(object).

encoding defaults to sys.getdefaultencoding().

errors defaults to 'strict'.

The class is inherited from str and has all regular string methods.

Changed in version 2.0: upstr has renamed to istr with keeping upstr alias.

The behavior remains the same with the only exception: repr('Content-Length') and str('Content-Length') now returns 'Content-Length' instead of 'CONTENT-LENGTH'.

Abstract Base Classes

The module provides two ABCs: MultiMapping and MutableMultiMapping. They are similar to collections.abc.Mapping and collections.abc.MutableMapping and inherited from them.

New in version 3.3.