hbutils.collection.stacked

Stacked mapping utilities for layered lookup behavior.

This module provides a read-only stacked mapping implementation that allows multiple mapping-like objects (e.g., dictionaries) to be layered together and accessed as a single unified mapping. When a key exists in multiple mappings, the value from the most recently stacked mapping takes precedence.

The module contains the following main component:

• StackedMapping - Read-only stacked mapping with layered key lookup

Note

The stacked mapping is read-only. Because it is ambiguous which underlying mapping should be modified, item assignment and deletion are intentionally unsupported.

Example:

>>> from hbutils.collection.stacked import StackedMapping
>>> d1 = {'a': 1, 'b': 2}
>>> d2 = {'b': 3, 'c': 4, 'd': 5}
>>> d3 = {'c': 6, 'e': 7}
>>> s = StackedMapping(d1, d2, d3)  # d3 > d2 > d1
>>> s['a']
1
>>> s['b']
3
>>> s['c']
6
>>> list(s)
['a', 'b', 'c', 'd', 'e']

__all__

hbutils.collection.stacked.__all__ = ['StackedMapping']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

StackedMapping

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

Read-only stacked mapping data structure for layered key lookup.

Multiple mapping-like objects (such as dict) can be stacked together and accessed as a single mapping. When the same key exists in multiple mappings, the value from the most recently stacked mapping is returned.

Note

StackedMapping is read-only. The behavior of __setitem__ and __delitem__ cannot be defined because it is ambiguous which underlying mapping should be modified.

Example:

>>> 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)  # d3 > d2 > d1
>>> list(s.items())
[('a', 1), ('b', 3), ('c', 6), ('d', 5), ('e', 7)]
>>> s['c']
6
>>> 'f' in s
False
>>> len(s)
5

__getitem__(k: _KeyType) → _ValueType

Get the value associated with the given key.

This method 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']  # from d2 (last mapping)
2
>>> s['b']
3

__init__(*mps: Mapping) → None

Initialize a stacked mapping instance.

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

Parameters:

mps (Mapping) – Mapping objects to stack together, in order of precedence.

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)
3