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, appending the pairs to this dictionary. For existing keys, values are added. Returns 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).

Effectively the same as calling add() for every (key, value) pair. Also see update(), for a version that replaces existing keys.

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.

Added in version 3.0.

pop(key[, default])¶: An alias to popone()

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.

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

Returns 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).

Also see extend() for a method that adds to existing keys rather than update them.

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.

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 if multidict is not a 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 if 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.

Added in version 3.0.

See also

PEP 509

istr¶

CIMultiDict accepts str as key argument for dict lookups but uses case-folded (lower-cased) strings for the comparison internally.

For more effective processing it should know if the key is already case-folded to skip the lower() call.

The performant code may create case-folded string keys explicitly hand, e.g:

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

For performance istr strings should be created once and stored somewhere for the later usage, see aiohttp.hdrs for example.

class multidict.istr(object='')¶

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

Create a new case-folded 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() is a deprecated alias for istr.

Changed in version 3.7: istr doesn’t title-case its argument anymore but uses internal lower-cased data for fast case-insensitive comparison.

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.

Added in version 3.3.

Typing¶

The library is shipped with embedded type annotations, mypy just picks the annotations by default.

MultiDict, CIMultiDict, MultiDictProxy, and CIMultiDictProxy are generic types; please use the corresponding notation for multidict value types, e.g. md: MultiDict[str] = MultiDict().

The type of multidict keys is always str or a class derived from a string.

Added in version 3.7.

Environment variables¶

MULTIDICT_NO_EXTENSIONS¶: An environment variable that instructs the packaging scripts to skip compiling the C-extension based variant of multidict. When used in runtime, it instructs the pure-Python variant to be imported from the top-level multidict entry-point package, even when the C-extension implementation is available.

Caution

The pure-Python (uncompiled) version is roughly 20-50 times slower than its C counterpart, depending on the way it’s used.