Skip to content

omnipy.util.weak

Weak-reference containers keyed by object identity.

This module provides helpers for storing values against live objects without keeping those keys alive, while still performing lookups by object identity.

CLASS DESCRIPTION
KeyRef

Identity-based weak-dictionary key wrapper.
WeakKeyRefContainer

Map live objects to values without keeping the keys alive.

KeyRef

Bases: list


              flowchart BT
              omnipy.util.weak.KeyRef[KeyRef]

              

              click omnipy.util.weak.KeyRef href "" "omnipy.util.weak.KeyRef"

Identity-based weak-dictionary key wrapper.

PARAMETER DESCRIPTION
obj

Object whose identity should be used as the key value.

TYPE: object

METHOD DESCRIPTION
__init__
Source code in src/omnipy/util/weak.py 
16
17
18
19
20
21
22
23
24
25
26
class KeyRef(list):
    """Identity-based weak-dictionary key wrapper.

    Args:
        obj: Object whose identity should be used as the key value.
    """
    def __init__(self, obj: object) -> None:
        super().__init__([id(obj)])

    def __hash__(self) -> int:  # type: ignore[override]
        return self[0]

__init__ 

__init__(obj: object) -> None
Source code in src/omnipy/util/weak.py 
22
23
def __init__(self, obj: object) -> None:
    super().__init__([id(obj)])

WeakKeyRefContainer

Bases: Generic[_AnyKeyT, _ValT]


              flowchart BT
              omnipy.util.weak.WeakKeyRefContainer[WeakKeyRefContainer]

              

              click omnipy.util.weak.WeakKeyRefContainer href "" "omnipy.util.weak.WeakKeyRefContainer"

Map live objects to values without keeping the keys alive.

The container stores a weak reference to each original key object and uses a stable identity wrapper so callers can retrieve values with the original object instance while automatic cleanup still works when keys are collected.

Subclassed by:
METHOD DESCRIPTION
__init__
clear

Remove all key and value references from the container.
get

Return the value associated with a live key object.
Source code in src/omnipy/util/weak.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
class WeakKeyRefContainer(Generic[_AnyKeyT, _ValT]):
    """Map live objects to values without keeping the keys alive.

    The container stores a weak reference to each original key object and uses a
    stable identity wrapper so callers can retrieve values with the original
    object instance while automatic cleanup still works when keys are collected.
    """
    def __init__(self) -> None:
        self._key_dict: WeakValueDictionary[KeyRef, _AnyKeyT] = WeakValueDictionary()
        self._value_dict: WeakKeyDictionary[KeyRef, _ValT] = WeakKeyDictionary()

    def __contains__(self, key: _AnyKeyT) -> bool:
        return KeyRef(key) in self._value_dict

    def get(self, key: _AnyKeyT) -> _ValT | None:
        """Return the value associated with a live key object.

        Args:
            key: Key object to look up by identity.

        Returns:
            The stored value for the key, or ``None`` when no entry exists.
        """
        key_ref = KeyRef(key)
        if key_ref in self._value_dict:
            return self._value_dict[key_ref]
        else:
            return None

    def __getitem__(self, key: _AnyKeyT) -> _ValT:
        key_ref = KeyRef(key)
        if key_ref in self._value_dict:
            return self._value_dict[key_ref]
        else:
            raise KeyError(f'{key} is not in {self.__class__.__name__}')

    def __setitem__(self, key: _AnyKeyT, value: _ValT) -> None:
        key_ref = KeyRef(key)
        self._key_dict[key_ref] = key
        self._value_dict[key_ref] = value

    def __len__(self) -> int:
        return len(self._value_dict)

    def clear(self) -> None:
        """Remove all key and value references from the container."""
        self._key_dict.clear()
        self._value_dict.clear()

__init__ 

__init__() -> None
Source code in src/omnipy/util/weak.py 
36
37
38
def __init__(self) -> None:
    self._key_dict: WeakValueDictionary[KeyRef, _AnyKeyT] = WeakValueDictionary()
    self._value_dict: WeakKeyDictionary[KeyRef, _ValT] = WeakKeyDictionary()

clear 

clear() -> None

Remove all key and value references from the container.

Source code in src/omnipy/util/weak.py 
73
74
75
76
def clear(self) -> None:
    """Remove all key and value references from the container."""
    self._key_dict.clear()
    self._value_dict.clear()

get 

get(key: _AnyKeyT) -> _ValT | None

Return the value associated with a live key object.

PARAMETER DESCRIPTION
key

Key object to look up by identity.

TYPE: _AnyKeyT

RETURNS DESCRIPTION
_ValT | None

The stored value for the key, or None when no entry exists.
Source code in src/omnipy/util/weak.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
def get(self, key: _AnyKeyT) -> _ValT | None:
    """Return the value associated with a live key object.

    Args:
        key: Key object to look up by identity.

    Returns:
        The stored value for the key, or ``None`` when no entry exists.
    """
    key_ref = KeyRef(key)
    if key_ref in self._value_dict:
        return self._value_dict[key_ref]
    else:
        return None