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 (Union[dict[TypeVar(_KT), TypeVar(_VT)], Iterable[tuple[TypeVar(_KT), TypeVar(_VT)]], None]) – 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).

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, default=None)

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

Return type:

Union[TypeVar(_VT), TypeVar(_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 (TypeVar(_KT)) – The key to be looked up.

Return type:

list[TypeVar(_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.

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 (TypeVar(_KT)) – The key to be looked up.

• default_list (Optional[Iterable[TypeVar(_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[TypeVar(_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[TypeVar(_KT), TypeVar(_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[TypeVar(_KT), list[TypeVar(_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[TypeVar(_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.

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.

Return type:

dict[TypeVar(_KT), TypeVar(_VT)] | dict[TypeVar(_KT), list[TypeVar(_VT)]]

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 (Union[Mapping[TypeVar(_KT), TypeVar(_VT)], Iterable[tuple[TypeVar(_KT), TypeVar(_VT)]]]) – The extending value for the MultiDict. Either a regular dict, an iterable of (key, value) tuples, or None.

Return type:

None

pop(key, default=no value)

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 (TypeVar(_KT)) – The key to pop.

• default (Union[TypeVar(_VT), TypeVar(_T)]) – If provided the value to return if the key was not in the dictionary.

Return type:

Union[TypeVar(_VT), TypeVar(_T)]

popitem()

Pop an item from the dict.

Return type:

tuple[TypeVar(_KT), TypeVar(_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 (TypeVar(_KT)) – The key to pop.

Return type:

list[TypeVar(_VT)]

popitemlist()

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

Return type:

tuple[TypeVar(_KT), list[TypeVar(_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 (Union[dict[TypeVar(_KT), TypeVar(_VT)], Iterable[tuple[TypeVar(_KT), TypeVar(_VT)]], None]) – 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.

Type Variables

pcapkit.corekit.multidict._T: Any

pcapkit.corekit.multidict._KT: Any

pcapkit.corekit.multidict._VT: Any