Multidicts

HTTP Headers and URL query string require specific data structure: multidict. It behaves mostly like a dict but may have several values for the same key.

aiohttp.multidict has four multidict classes: MultiDict, MultiDictProxy, CIMultiDict and CIMultiDictProxy.

Immutable proxies (MultiDictProxy and CIMultiDictProxy) provide a dynamic view on the proxied multidict, the view reflects the multidict changes. They are implement Mapping interface.

Regular mutable (MultiDict and CIMultiDict) classes implement MutableMapping and allow to change own content.

Case insensitive (CIMultiDict and CIMultiDictProxy) ones assumes the keys are case insensitive, e.g.:

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

Keys should be a str.

MultiDict

class aiohttp.multidict.MultiDict(**kwargs)

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

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

Create a mutable multidict instance.

Accepted parameters are the same as for dict.

If the same key produced 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 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(getall=True)

Return a new view of the dictionary’s keys.

View contains all keys if getall is True (default) or distinct set of ones otherwise.

keys(getall=True)

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

View contains all items if getall is True (default) or only first key occurrences otherwise.

values(getall=True)

Return a new view of the dictionary’s values.

View contains all values if getall is True (default) or only first key occurrences otherwise.

pop(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.

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 aiohttp.multidict.CIMultiDict(**kwargs)

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

class aiohttp.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 aiohttp.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(getall=True)

Return a new view of the dictionary’s keys.

View contains all keys if getall is True (default) or distinct set of ones otherwise.

keys(getall=True)

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

View contains all items if getall is True (default) or only first key occurrences otherwise.

values(getall=True)

Return a new view of the dictionary’s values.

View contains all values if getall is True (default) or only first key occurrences otherwise.

CIMultiDictProxy

class aiohttp.multidict.CIMultiDictProxy(multidict)

Case insensitive version of MultiDictProxy.

Raises TypeError is multidict is not CIMultiDict instance.

The class is inherited from MultiDict.

upstr

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

For more effective processing it should to know if key is already upper cased.

To skip upper() call you may create upper cased string by hands, e.g:

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

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

class aiohttp.multidict.upstr(object='')

class aiohttp.multidict.upstr(bytes_or_buffer[, encoding[, errors]])

Create a new upper cased string object from the given object. If encoding or errors is 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.