A collection of Mapping types.¶

This module provides specialized mapping classes built on top of Python’s collections.abc.Mapping and collections.OrderedDict.

Module Contents¶

class OrderableDict(other: _SupportsKeysAndGetItem[_KT, _VT] | collections.abc.Iterable[tuple[_KT, _VT]] = (), /, **kwds: _VT)[source]¶

Extends: collections.OrderedDict[_KT, _VT]

A OrderedDict subclass with positional key manipulation.

Extends OrderedDict with after() and before() methods for inserting, moving, or querying entries relative to other keys and first / last properties for O(1) access to boundary keys.

Initialize self. See help(type(self)) for accurate signature.

property first : _KT¶

Return the first key.

property last : _KT¶

Return the last key.

after(key: _KT, other: _KT | None = None, value: _VT | None = None) → tuple[_KT, _VT] | None[source]¶

Insert, move, or return a (key, value) pair after another key.

If other is not provided, returns the (key, value) pair found after key in the ordering.

If value is None, move key after other in the dict (the entry must already exist).

If value is provided, insert the (key, value) pair after other. If the key already exists in the dict, the value is updated but no move occurs.

Parameters:¶

key: _KT¶

The key to look up, move, or insert.

other: _KT | None = None¶

Reference key. If None, the method returns the pair after key. Defaults to None.

value: _VT | None = None¶

If provided, insert this value for key; if None, move the existing entry. Defaults to None.

Returns:¶

tuple | None – A (key, value) pair if other is None, otherwise None.

Raises:¶

KeyError – If key or other does not exist in the dict.

before(key: _KT, other: _KT | None = None, value: _VT | None = None) → tuple[_KT, _VT] | None[source]¶

Insert, move, or return a (key, value) pair before another key.

If other is not provided, returns the (key, value) pair found before key in the ordering.

If value is None, move key before other in the dict (the entry must already exist).

If value is provided, insert the (key, value) pair before other. If the key already exists in the dict, the value is updated but no move occurs.

Parameters:¶

key: _KT¶

The key to look up, move, or insert.

other: _KT | None = None¶

Reference key. If None, the method returns the pair before key. Defaults to None.

value: _VT | None = None¶

If provided, insert this value for key; if None, move the existing entry. Defaults to None.

Returns:¶

tuple | None – A (key, value) pair if other is None, otherwise None.

Raises:¶

KeyError – If key or other does not exist in the dict.

class FrozenMap(other: collections.abc.Mapping[_KT, _VT] | None = None, /, **kwds: _VT)[source]¶

Extends: collections.abc.Mapping[_KT, _VT]

A read-only Mapping that cannot be modified.

Items are provided at instantiation and cannot be added, changed, or removed afterward. Note that FrozenMap does not enforce the immutability of the values themselves; use immutable containers as values if that is required.

Note

This class exists primarily because types.MappingProxyType, which offers similar behavior cannot be subclassed.

The following dunder methods are implemented to satisfy the Mapping protocol:

• __contains__(), __getitem__(), __len__(), __iter__()

• __eq__() / __ne__() compare by items.

• __repr__() produces a FrozenMap({...}) string.

Parameters:¶

other: collections.abc.Mapping[_KT, _VT] | None = None¶

The source mapping to freeze. If None, keyword arguments are used instead. Defaults to None.

**kwds: _VT¶

Additional key-value pairs merged into the mapping.

keys() → collections.abc.KeysView[_KT][source]¶

Return a view of the keys in the mapping.

Returns:¶

KeysView – A view of the keys in the mapping.

values() → collections.abc.ValuesView[_VT][source]¶

Return a view of the values in the mapping.

Returns:¶

ValuesView – A view of the values in the mapping.

items() → collections.abc.ItemsView[_KT, _VT][source]¶

Return a view of the (key, value) pairs in the mapping.

Returns:¶

ItemsView – A view of the (key, value) pairs in the mapping.

get(key: _KT, default: _VT | None = None) → _VT | None[source]¶

Return the value associated with the specified key.

If the key is not found in the mapping, the default value is returned.

Parameters:¶

key: _KT¶

The key to look up in the mapping.

default: _VT | None = None¶

The value to return if the key is not found. Defaults to None.

Returns:¶

Any | None – The value associated with the key if found, otherwise the default value.

view_filter¶

class FilteredView(source: collections.abc.Mapping[_KT, _VT], filter: view_filter | None = None)[source]¶

Extends: FrozenMap[_KT, _VT]

Dynamically filtered read-only view on a Mapping.

Provides a live, filtered view of a source mapping: when the source mapping is modified, this view reflects those changes automatically.

Dunder methods __contains__(), __getitem__(), __len__(), and __iter__() all respect the filter predicate, only entries for which the filter returns True are visible.

Examples:

>>> d = {'a': 1, 'b': 2, 'c': 3}
>>> FilteredView(d, lambda k, v: v > 1)
FilteredView({'b': 2, 'c': 3})

Parameters:¶

source: collections.abc.Mapping[_KT, _VT]¶

The source mapping for this view.

filter : callable, optional¶

A callable (key, value) -> bool that determines whether an entry is included. If None, an identity-like filter is used: entries whose value evaluates to False are excluded. Defaults to None.

inherited Members¶

keys()	Return a view of the keys in the mapping.
values()	Return a view of the values in the mapping.
items()	Return a view of the (key, value) pairs in the…

get(key: _KT, default: _VT | None = None) → _VT | None[source]¶

Return the value associated with the specified key.

If the key is not found in the source mapping, or if it is present but excluded by the view’s filter, the default value is returned.

Parameters:¶

key: _KT¶

The key to look up in the mapping.

default: _VT | None = None¶

The value to return if the key is not found or filtered out. Defaults to None.

Returns:¶

Any | None – The value associated with the key if found and not filtered, otherwise the default value.