Multi-Mapping Dictionary

pcapkit.corekit.multidict contains multi-mapping dictionary classes, which are used to store multiple mappings of the same key. The implementation is inspired and based on the Werkzeug project.

class pcapkit.corekit.multidict.MultiDict(mapping=None)

Bases: dict, Generic[_KT, _VT]

A MultiDict is a dictionary subclass customized to deal with 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 getlist() and similar methods.

Parameters

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

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

See also

The class is inspired from and based on the Werkzeug project (c.f. werkzeug.datastructures.MultiDict).

__setitem__(key, value)

Like add() but removes an existing key first.

Parameters

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

• value (TypeVar(_VT)) – The value to set.

Return type

None

add(key, value)

Adds a new value for the key.

Parameters

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

• value (TypeVar(_VT)) – The value to add.

Return type

None

get(key: _KT) → _VT | _T

get(key: _KT, default: _VT | _T = None) → _VT | _T

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

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.

Returns

A list of all the values for the key.

Return type

list[_VT]

setlist(key, new_list)

Remove the old values for a key and add new ones.

Notes

The list you pass the values in will be shallow-copied before it is inserted in the dictionary.

Parameters

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

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

Return type

None

setdefault(key, default=None)

If key is in the dictionary, returns its value.

If not, set it to default and return default.

Parameters

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

• default (Optional[TypeVar(_VT)]) – The value to be set.

Return type

TypeVar(_VT)

Returns

The value of the key.

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.

Parameters

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

• default_list (Optional[Iterable[_VT]]) – 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]

items(multi=False)

Return an interator of (key, value) paris.

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 an iterator of (key, values) pairs, where values is the list of all values associated with the key.

Return type

Iterator[tuple[_KT, list[_VT]]]

values()

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

Return type

Iterator[TypeVar(_VT)]

listvalues()

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

Return type

Iterator[list[_VT]]

to_dict(flat: Literal[True] = True) → dict[_KT, _VT]

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

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.

Parameters

flat – 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.

update(mapping)

update() extends rather than replaces existing key lists.

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.

Parameters

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

Return type

None

pop(key: _KT) → _VT

pop(key: _KT, default: _VT | _T = no value) → _VT | _T

Pop the first item for a list on the dict.

Afterwards the key is removed from the dict, so additional values are discarded.

Parameters

• key – The key to pop.

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

Notes

If the key does no longer exist a list is returned instead of raising an error.

Parameters

key (_KT) – The key to pop.

Return type

list[_VT]

popitemlist()

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

Return type

tuple[_KT, list[_VT]]

class pcapkit.corekit.multidict.OrderedMultiDict(mapping=None)

Bases: MultiDict[_KT, _VT]

Works like a regular MultiDict but preserves the order of the fields.

Parameters

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

To convert the ordered multi dict into a list you can us the items() method and pass it multi=True.

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

Notes

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.