hbutils.collection.stacked

Overview:

This module provides a stacked mapping data structure that allows multiple mapping-like objects (such as dictionaries) to be layered together and accessed as a single unified mapping. Later mappings in the stack take precedence over earlier ones when accessing values.

The StackedMapping class is read-only and does not support item assignment or deletion operations, as it would be ambiguous which underlying mapping should be modified.

StackedMapping

class hbutils.collection.stacked.StackedMapping(*mps: Mapping)

Overview:

Stacked mapping data structure.

Multiple mapping-liked object (such as dict) can be stacked together and accessed like one mapping object.

Note

StackedMapping is readonly. The __setitem__ and __delitem__’s behaviour cannot be defined, because which dict to write or delete can not be determined.

Examples::

>>> from hbutils.collection import StackedMapping
>>>
>>> d1 = {'a': 1, 'b': 2}
>>> d2 = {'b': 3, 'c': 4, 'd': 5}
>>> d3 = {'c': 6, 'e': 7}
>>> s = StackedMapping(d1, d2, d3)  # stack together, d3 > d2 > d1
>>>
>>> for key, value in s.items():  # __iter__
...     print(key, value)
a 1
b 3
c 6
d 5
e 7
>>> s['a']  # __getitem__, from d1['a']
1
>>> s['b']  # from d2['b'], d2 > d1
3
>>> s['c']  # from d3['c'], d3 > d2
6
>>> s['d']  # from d2['d']
5
>>> s['e']  # from d3['e']
7
>>> 'c' in s  # __contains__
True
>>> 'f' in s  # 'f' not found in neither d1, d2 nor d3
False
>>> s == {'a': 1, 'b': 3, 'c': 6, 'd': 5, 'e': 7}  # __iter__
True
>>> len(s)  # __len__
5
>>>
>>> d2['c'] = 11  # update original dicts
>>> del d2['b']
>>> del d3['c']
>>> del d1['b']
>>>
>>> s['a']  # __getitem__, from d1['a']
1
>>> s['b']  # 'b' nor found in neither d1, d2 nor d3
KeyError: 'b'
>>> s['c']  # from d2['c']
11
>>> s['d']  # from d2['d']
5
>>> s['e']  # from d3['e']
7
>>> len(s)  # 'b' is no longer here
4

__getitem__(k: _KeyType) → _ValueType

Get the value associated with the given key.

Searches through the stacked mappings in reverse order (from last to first), returning the value from the first mapping that contains the key.

Parameters:

k (_KeyType) – The key to look up.

Returns:

The value associated with the key.

Return type:

_ValueType

Raises:

KeyError – If the key is not found in any of the stacked mappings.

Example::

>>> d1 = {'a': 1}
>>> d2 = {'a': 2, 'b': 3}
>>> s = StackedMapping(d1, d2)
>>> s['a']  # Returns value from d2 (last mapping)
2
>>> s['b']  # Returns value from d2
3

__init__(*mps: Mapping)

Constructor of StackedMapping.

Later mappings will be stacked on top of the earlier ones, meaning they take precedence when retrieving values for keys that exist in multiple mappings.

Parameters:

mps (Mapping) – Multiple mapping objects to stack together.

Example::

>>> d1 = {'a': 1}
>>> d2 = {'b': 2}
>>> s = StackedMapping(d1, d2)
>>> len(s)
2

__iter__() → Iterator[_KeyType]

Iterate over all unique keys in the stacked mappings.

Returns:

An iterator over all unique keys.

Return type:

Iterator[_KeyType]

Example::

>>> d1 = {'a': 1, 'b': 2}
>>> d2 = {'c': 3}
>>> s = StackedMapping(d1, d2)
>>> list(s)
['a', 'b', 'c']

__len__() → int

Get the number of unique keys across all stacked mappings.

Returns:

The total number of unique keys.

Return type:

int

Example::

>>> d1 = {'a': 1, 'b': 2}
>>> d2 = {'b': 3, 'c': 4}
>>> s = StackedMapping(d1, d2)
>>> len(s)  # 'a', 'b', 'c' = 3 unique keys
3