Multi-Mapping Dictionary

pcapkit.corekit.multidict contains dictionaries that store multiple values per key, based on the Werkzeug project.

class pcapkit.corekit.multidict.MultiDict[_KT, _VT](mapping=None)

Bases: dict, Generic[_KT, _VT]

A MultiDict is a dictionary subclass customized to deal with multiple values for the same key which is for example used by the parsing functions in the wrappers. This is necessary because some HTML form elements pass multiple values for the same key.

MultiDict implements all standard dictionary methods. Internally, it saves all values for a key as a list, but the standard dict access methods will only return the first value for a key. If you want to gain access to the other values, too, you have to use the list methods as explained below.

Basic Usage:

>>> d = MultiDict([('a', 'b'), ('a', 'c')])
>>> d
MultiDict([('a', 'b'), ('a', 'c')])
>>> d['a']
'b'
>>> d.getlist('a')
['b', 'c']
>>> 'a' in d
True

It behaves like a normal dict thus all dict functions will only return the first value when multiple values for one key are found.

A MultiDict can be constructed from an iterable of (key, value) tuples, a dict, a MultiDict or from Werkzeug 0.2 onwards some keyword parameters.

Parameters:

mapping (MultiDict[_KT, _VT] | Mapping[_KT, _VT | list[_VT] | tuple[_VT, ...] | set[_VT]] | Iterable[tuple[_KT, _VT]] | None) – the initial value for the MultiDict. Either a regular dict, an iterable of (key, value) tuples or None.

add(key, value)

Adds a new value for the key.

Parameters:

• key (_KT) – the key for the value.

• value (_VT) – the value to add.

get(key, default=None)

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

Overloads:

• key (_KT) → _VT | _T

• key (_KT), default (_VT | _T) = ... → _VT | _T

getlist(key)

Return the list of items for a given key. If that key is not in the MultiDict, the return value will be an empty list.

Parameters:

key (_KT) – The key to be looked up.

Return type:

list[_VT]

Returns:

a list of all the values for the key.

setlist(key, new_list)

Remove the old values for a key and add new ones. Note that the list you pass the values in will be shallow-copied before it is inserted in the dictionary.

>>> d = MultiDict()
>>> d.setlist('foo', ['1', '2'])
>>> d['foo']
'1'
>>> d.getlist('foo')
['1', '2']

Parameters:

• key (_KT) – The key for which the values are set.

• new_list (Iterable[_VT]) – An iterable with the new values for the key. Old values are removed first.

setdefault(key, default=None)

Returns the value for the key if it is in the dict, otherwise it returns default and sets that value for key.

Overloads:

• key (_KT) → None

• key (_KT), default (_VT) → _VT

Parameters:

• key (_KT) – The key to be looked up.

• default (_VT | None) – The default value to be returned if the key is not in the dict. If not further specified it’s None.

setlistdefault(key, default_list=None)

Like setdefault but sets multiple values. The list returned is not a copy, but the list that is actually used internally. This means that you can put new values into the dict by appending items to the list:

>>> d = MultiDict({"foo": 1})
>>> d.setlistdefault("foo").extend([2, 3])
>>> d.getlist("foo")
[1, 2, 3]

Parameters:

• key (_KT) – The key to be looked up.

• default_list (Iterable[_VT] | None) – An iterable of default values. It is either copied (in case it was a list) or converted into a list before returned.

Return type:

list[_VT]

Returns:

a list

items(multi=False)

Return an iterator of (key, value) pairs.

Parameters:

multi (bool) – If set to True the iterator returned will have a pair for each value of each key. Otherwise it will only contain pairs for the first value of each key.

Return type:

Iterable[tuple[_KT, _VT]]

lists()

Return a iterator of (key, values) pairs, where values is the list of all values associated with the key.

Return type:

Iterable[tuple[_KT, list[_VT]]]

values()

Returns an iterator of the first value on every key’s value list.

Return type:

Iterable[_VT]

listvalues()

Return an iterator of all values associated with a key. Zipping keys() and this is the same as calling lists():

>>> d = MultiDict({"foo": [1, 2, 3]})
>>> zip(d.keys(), d.listvalues()) == d.lists()
True

Return type:

Iterable[list[_VT]]

to_dict(flat=True)

Return the contents as regular dict. If flat is True the returned dict will only have the first item present, if flat is False all values will be returned as lists.

Overloads:

• flat (Literal[True]) = ... → dict[_KT, _VT]

• flat (Literal[False]) → dict[_KT, list[_VT]]

Parameters:

flat (bool) – If set to False the dict returned will have lists with all the values in it. Otherwise it will only contain the first value for each key.

Returns:

a dict

update(mapping)

update() extends rather than replaces existing key lists:

>>> a = MultiDict({'x': 1})
>>> b = MultiDict({'x': 2, 'y': 3})
>>> a.update(b)
>>> a
MultiDict([('y', 3), ('x', 1), ('x', 2)])

If the value list for a key in other_dict is empty, no new values will be added to the dict and the key will not be created:

>>> x = {'empty_list': []}
>>> y = MultiDict()
>>> y.update(x)
>>> y
MultiDict([])

pop(key, default=_missing)

Pop the first item for a list on the dict. Afterwards the key is removed from the dict, so additional values are discarded:

Overloads:

• key (_KT) → _VT

• key (_KT), default (_VT) → _VT

• key (_KT), default (_T) → _VT | _T

>>> d = MultiDict({"foo": [1, 2, 3]})
>>> d.pop("foo")
1
>>> "foo" in d
False

Parameters:

• key (_KT) – the key to pop.

• default (_VT | _T) – if provided the value to return if the key was not in the dictionary.

popitem()

Pop an item from the dict.

Return type:

tuple[_KT, _VT]

poplist(key)

Pop the list for a key from the dict. If the key is not in the dict an empty list is returned.

Return type:

list[_VT]

popitemlist()

Pop a (key, list) tuple from the dict.

Return type:

tuple[_KT, list[_VT]]

deepcopy(memo=None)

Return a deep copy of this object.

Return type:

Self

class pcapkit.corekit.multidict.OrderedMultiDict[_KT, _VT](mapping=None)

Bases: ReduceToItems, MultiDict[_KT, _VT]

Works like a regular MultiDict but preserves the order of the fields. To convert the ordered multi dict into a list you can use the items() method and pass it multi=True.

In general an OrderedMultiDict is an order of magnitude slower than a MultiDict.

note

Due to a limitation in Python you cannot convert an ordered multi dict into a regular dict by using dict(multidict). Instead you have to use the to_dict() method, otherwise the internal bucket objects are exposed.

deepcopy(memo=None)

Return a deep copy of this object.

Notes

MultiDict.deepcopy() rebuilds from to_dict() with flat=False, which groups the values by key. This rebuilds from items(multi=True) instead, so the copy keeps the insertion order of interleaved keys. __deepcopy__() reaches it too.

Changed in version 1.5.0: Keeps the insertion order of interleaved keys, where the copy grouped the values by key (#1295).

Return type:

OrderedMultiDict[_KT, _VT]

items(multi=False)

Return an iterator of (key, value) pairs.

Parameters:

multi (bool) – If set to True the iterator returned will have a pair for each value of each key. Otherwise it will only contain pairs for the first value of each key.

Return type:

Iterable[tuple[_KT, _VT]]

Type Variables

pcapkit.corekit.multidict._T: Any

pcapkit.corekit.multidict._KT: Any

pcapkit.corekit.multidict._VT: Any