tnfr 4.5.2__py3-none-any.whl → 6.0.0__py3-none-any.whl

tnfr/rng.py

@@ -2,17 +2,21 @@
 
 from __future__ import annotations
 
-import random
 import hashlib
+import random
 import struct
+import threading
 from collections.abc import Iterator, MutableMapping
-from typing import Any, Generic, Hashable, TypeVar
+from dataclasses import dataclass
+from typing import Any, Generic, Hashable, TypeVar, cast
 
 
-from cachetools import LRUCache, cached
+from cachetools import cached  # type: ignore[import-untyped]
 from .constants import DEFAULTS, get_param
-from .graph_utils import get_graph
+from .cache import CacheManager, InstrumentedLRUCache
+from .utils import get_graph
 from .locking import get_lock
+from .types import GraphLike, TNFRGraph
 
 MASK64 = 0xFFFFFFFFFFFFFFFF
 
@@ -22,110 +26,264 @@ _CACHE_MAXSIZE = _DEFAULT_CACHE_MAXSIZE
 _CACHE_LOCKED = False
 
 K = TypeVar("K", bound=Hashable)
+V = TypeVar("V")
+
+
+@dataclass
+class _SeedCacheState:
+    cache: InstrumentedLRUCache[tuple[int, int], int] | None
+    maxsize: int
+
+
+@dataclass
+class _CounterState(Generic[K]):
+    cache: InstrumentedLRUCache[K, int]
+    locks: dict[K, threading.RLock]
+    max_entries: int
+
+
+_RNG_CACHE_MANAGER = CacheManager(default_capacity=_DEFAULT_CACHE_MAXSIZE)
 
 
 class _SeedHashCache(MutableMapping[tuple[int, int], int]):
     """Mutable mapping proxy exposing a configurable LRU cache."""
 
-    def __init__(self, maxsize: int) -> None:
-        self._maxsize = 0
-        self._cache: LRUCache[tuple[int, int], int] | None = None
-        self.configure(maxsize)
+    def __init__(
+        self,
+        *,
+        manager: CacheManager | None = None,
+        state_key: str = "seed_hash_cache",
+        default_maxsize: int = _DEFAULT_CACHE_MAXSIZE,
+    ) -> None:
+        self._manager = manager or _RNG_CACHE_MANAGER
+        self._state_key = state_key
+        self._default_maxsize = int(default_maxsize)
+        if not self._manager.has_override(self._state_key):
+            self._manager.configure(
+                overrides={self._state_key: self._default_maxsize}
+            )
+        self._manager.register(
+            self._state_key,
+            self._create_state,
+            reset=self._reset_state,
+        )
+
+    def _resolved_size(self, requested: int | None = None) -> int:
+        size = self._manager.get_capacity(
+            self._state_key,
+            requested=requested,
+            fallback=self._default_maxsize,
+        )
+        if size is None:
+            return 0
+        return int(size)
+
+    def _create_state(self) -> _SeedCacheState:
+        size = self._resolved_size()
+        if size <= 0:
+            return _SeedCacheState(cache=None, maxsize=0)
+        return _SeedCacheState(
+            cache=InstrumentedLRUCache(
+                size,
+                manager=self._manager,
+                metrics_key=self._state_key,
+            ),
+            maxsize=size,
+        )
+
+    def _reset_state(self, state: _SeedCacheState | None) -> _SeedCacheState:
+        return self._create_state()
+
+    def _get_state(self, *, create: bool = True) -> _SeedCacheState | None:
+        state = self._manager.get(self._state_key, create=create)
+        if state is None:
+            return None
+        if not isinstance(state, _SeedCacheState):
+            state = self._create_state()
+            self._manager.store(self._state_key, state)
+        return state
 
     def configure(self, maxsize: int) -> None:
-        """Configure internal cache size, clearing previous entries."""
-
-        self._maxsize = int(maxsize)
-        if self._maxsize <= 0:
-            self._cache = None
-        else:
-            self._cache = LRUCache(maxsize=self._maxsize)
+        size = int(maxsize)
+        if size < 0:
+            raise ValueError("maxsize must be non-negative")
+        self._manager.configure(overrides={self._state_key: size})
+        self._manager.update(self._state_key, lambda _: self._create_state())
 
     def __getitem__(self, key: tuple[int, int]) -> int:
-        if self._cache is None:
+        state = self._get_state()
+        if state is None or state.cache is None:
             raise KeyError(key)
-        return self._cache[key]
+        value = state.cache[key]
+        self._manager.increment_hit(self._state_key)
+        return value
 
     def __setitem__(self, key: tuple[int, int], value: int) -> None:
-        if self._cache is not None:
-            self._cache[key] = value
+        state = self._get_state()
+        if state is not None and state.cache is not None:
+            state.cache[key] = value
 
     def __delitem__(self, key: tuple[int, int]) -> None:
-        if self._cache is None:
+        state = self._get_state()
+        if state is None or state.cache is None:
             raise KeyError(key)
-        del self._cache[key]
+        del state.cache[key]
 
     def __iter__(self) -> Iterator[tuple[int, int]]:
-        if self._cache is None:
+        state = self._get_state(create=False)
+        if state is None or state.cache is None:
             return iter(())
-        return iter(self._cache)
+        return iter(state.cache)
 
     def __len__(self) -> int:
-        if self._cache is None:
+        state = self._get_state(create=False)
+        if state is None or state.cache is None:
             return 0
-        return len(self._cache)
+        return len(state.cache)
 
     def clear(self) -> None:  # type: ignore[override]
-        if self._cache is not None:
-            self._cache.clear()
+        self._manager.clear(self._state_key)
 
     @property
     def maxsize(self) -> int:
-        return self._maxsize
+        state = self._get_state()
+        return 0 if state is None else state.maxsize
 
     @property
     def enabled(self) -> bool:
-        return self._cache is not None
+        state = self._get_state(create=False)
+        return bool(state and state.cache is not None)
 
     @property
-    def data(self) -> LRUCache[tuple[int, int], int] | None:
+    def data(self) -> InstrumentedLRUCache[tuple[int, int], int] | None:
         """Expose the underlying cache for diagnostics/tests."""
 
-        return self._cache
+        state = self._get_state(create=False)
+        return None if state is None else state.cache
 
 
 class ScopedCounterCache(Generic[K]):
     """Thread-safe LRU cache storing monotonic counters by ``key``."""
 
-    def __init__(self, name: str, max_entries: int) -> None:
-        if max_entries < 0:
+    def __init__(
+        self,
+        name: str,
+        max_entries: int | None = None,
+        *,
+        manager: CacheManager | None = None,
+        default_max_entries: int = _DEFAULT_CACHE_MAXSIZE,
+    ) -> None:
+        self._name = name
+        self._manager = manager or _RNG_CACHE_MANAGER
+        self._state_key = f"scoped_counter:{name}"
+        self._default_max_entries = int(default_max_entries)
+        requested = None if max_entries is None else int(max_entries)
+        if requested is not None and requested < 0:
             raise ValueError("max_entries must be non-negative")
-        self._lock = get_lock(name)
-        self._max_entries = int(max_entries)
-        self._cache: LRUCache[K, int] = LRUCache(maxsize=self._max_entries)
+        if not self._manager.has_override(self._state_key):
+            fallback = requested
+            if fallback is None:
+                fallback = self._default_max_entries
+            self._manager.configure(overrides={self._state_key: fallback})
+        elif requested is not None:
+            self._manager.configure(overrides={self._state_key: requested})
+        self._manager.register(
+            self._state_key,
+            self._create_state,
+            lock_factory=lambda: get_lock(name),
+            reset=self._reset_state,
+        )
+
+    def _resolved_entries(self, requested: int | None = None) -> int:
+        size = self._manager.get_capacity(
+            self._state_key,
+            requested=requested,
+            fallback=self._default_max_entries,
+        )
+        if size is None:
+            return 0
+        return int(size)
+
+    def _create_state(self, requested: int | None = None) -> _CounterState[K]:
+        size = self._resolved_entries(requested)
+        locks: dict[K, threading.RLock] = {}
+        return _CounterState(
+            cache=InstrumentedLRUCache(
+                size,
+                manager=self._manager,
+                metrics_key=self._state_key,
+                locks=locks,
+            ),
+            locks=locks,
+            max_entries=size,
+        )
+
+    def _reset_state(self, state: _CounterState[K] | None) -> _CounterState[K]:
+        return self._create_state()
+
+    def _get_state(self) -> _CounterState[K]:
+        state = self._manager.get(self._state_key)
+        if not isinstance(state, _CounterState):
+            state = self._create_state(0)
+            self._manager.store(self._state_key, state)
+        return state
 
     @property
-    def lock(self):
+    def lock(self) -> threading.Lock | threading.RLock:
         """Return the lock guarding access to the underlying cache."""
 
-        return self._lock
+        return self._manager.get_lock(self._state_key)
 
     @property
     def max_entries(self) -> int:
         """Return the configured maximum number of cached entries."""
 
-        return self._max_entries
+        return self._get_state().max_entries
 
     @property
-    def cache(self) -> LRUCache[K, int]:
-        """Expose the underlying ``LRUCache`` for inspection."""
+    def cache(self) -> InstrumentedLRUCache[K, int]:
+        """Expose the instrumented cache for inspection."""
 
-        return self._cache
+        return self._get_state().cache
+
+    @property
+    def locks(self) -> dict[K, threading.RLock]:
+        """Return the mapping of per-key locks tracked by the cache."""
+
+        return self._get_state().locks
 
     def configure(
         self, *, force: bool = False, max_entries: int | None = None
     ) -> None:
         """Resize or reset the cache keeping previous settings."""
 
-        size = self._max_entries if max_entries is None else int(max_entries)
-        if size < 0:
-            raise ValueError("max_entries must be non-negative")
-        with self._lock:
-            if size != self._max_entries:
-                self._max_entries = size
-                force = True
-            if force:
-                self._cache = LRUCache(maxsize=self._max_entries)
+        if max_entries is None:
+            size = self._resolved_entries()
+            update_policy = False
+        else:
+            size = int(max_entries)
+            if size < 0:
+                raise ValueError("max_entries must be non-negative")
+            update_policy = True
+
+        def _update(state: _CounterState[K] | None) -> _CounterState[K]:
+            if not isinstance(state, _CounterState) or force or state.max_entries != size:
+                locks: dict[K, threading.RLock] = {}
+                return _CounterState(
+                    cache=InstrumentedLRUCache(
+                        size,
+                        manager=self._manager,
+                        metrics_key=self._state_key,
+                        locks=locks,
+                    ),
+                    locks=locks,
+                    max_entries=size,
+                )
+            return cast(_CounterState[K], state)
+
+        if update_policy:
+            self._manager.configure(overrides={self._state_key: size})
+        self._manager.update(self._state_key, _update)
 
     def clear(self) -> None:
         """Clear stored counters preserving ``max_entries``."""
@@ -135,22 +293,31 @@ class ScopedCounterCache(Generic[K]):
     def bump(self, key: K) -> int:
         """Return current counter for ``key`` and increment it atomically."""
 
-        with self._lock:
-            value = int(self._cache.get(key, 0))
-            self._cache[key] = value + 1
-            return value
+        result: dict[str, Any] = {}
 
-    def __len__(self) -> int:
-        return len(self._cache)
+        def _update(state: _CounterState[K] | None) -> _CounterState[K]:
+            if not isinstance(state, _CounterState):
+                state = self._create_state(0)
+            cache = state.cache
+            locks = state.locks
+            if key not in locks:
+                locks[key] = threading.RLock()
+            value = int(cache.get(key, 0))
+            cache[key] = value + 1
+            result["value"] = value
+            return state
 
+        self._manager.update(self._state_key, _update)
+        return int(result.get("value", 0))
 
-_seed_hash_cache = _SeedHashCache(_CACHE_MAXSIZE)
+    def __len__(self) -> int:
+        return len(self.cache)
 
 
-@cached(cache=_seed_hash_cache, lock=_RNG_LOCK)
-def seed_hash(seed_int: int, key_int: int) -> int:
-    """Return a 64-bit hash derived from ``seed_int`` and ``key_int``."""
+_seed_hash_cache = _SeedHashCache()
+
 
+def _compute_seed_hash(seed_int: int, key_int: int) -> int:
     seed_bytes = struct.pack(
         ">QQ",
         seed_int & MASK64,
@@ -161,7 +328,24 @@ def seed_hash(seed_int: int, key_int: int) -> int:
     )
 
 
-def _sync_cache_size(G: Any | None) -> None:
+@cached(cache=_seed_hash_cache, lock=_RNG_LOCK)
+def _cached_seed_hash(seed_int: int, key_int: int) -> int:
+    return _compute_seed_hash(seed_int, key_int)
+
+
+def seed_hash(seed_int: int, key_int: int) -> int:
+    """Return a 64-bit hash derived from ``seed_int`` and ``key_int``."""
+
+    if _CACHE_MAXSIZE <= 0 or not _seed_hash_cache.enabled:
+        return _compute_seed_hash(seed_int, key_int)
+    return _cached_seed_hash(seed_int, key_int)
+
+
+seed_hash.cache_clear = cast(Any, _cached_seed_hash).cache_clear  # type: ignore[attr-defined]
+seed_hash.cache = _seed_hash_cache  # type: ignore[attr-defined]
+
+
+def _sync_cache_size(G: TNFRGraph | GraphLike | None) -> None:
     """Synchronise cache size with ``G`` when needed."""
 
     global _CACHE_MAXSIZE
@@ -169,12 +353,14 @@ def _sync_cache_size(G: Any | None) -> None:
         return
     size = get_cache_maxsize(G)
     with _RNG_LOCK:
-        if size != _CACHE_MAXSIZE:
+        if size != _seed_hash_cache.maxsize:
             _seed_hash_cache.configure(size)
-            _CACHE_MAXSIZE = size
+            _CACHE_MAXSIZE = _seed_hash_cache.maxsize
 
 
-def make_rng(seed: int, key: int, G: Any | None = None) -> random.Random:
+def make_rng(
+    seed: int, key: int, G: TNFRGraph | GraphLike | None = None
+) -> random.Random:
     """Return a ``random.Random`` for ``seed`` and ``key``.
 
     When ``G`` is provided, ``JITTER_CACHE_SIZE`` is read from ``G`` and the
@@ -188,17 +374,17 @@ def make_rng(seed: int, key: int, G: Any | None = None) -> random.Random:
 
 def clear_rng_cache() -> None:
     """Clear cached seed hashes."""
-    if _CACHE_MAXSIZE <= 0 or not _seed_hash_cache.enabled:
+    if _seed_hash_cache.maxsize <= 0 or not _seed_hash_cache.enabled:
         return
-    seed_hash.cache_clear()
+    seed_hash.cache_clear()  # type: ignore[attr-defined]
 
 
-def get_cache_maxsize(G: Any) -> int:
+def get_cache_maxsize(G: TNFRGraph | GraphLike) -> int:
     """Return RNG cache maximum size for ``G``."""
     return int(get_param(G, "JITTER_CACHE_SIZE"))
 
 
-def cache_enabled(G: Any | None = None) -> bool:
+def cache_enabled(G: TNFRGraph | GraphLike | None = None) -> bool:
     """Return ``True`` if RNG caching is enabled.
 
     When ``G`` is provided, the cache size is synchronised with
@@ -207,12 +393,12 @@ def cache_enabled(G: Any | None = None) -> bool:
     # Only synchronise the cache size with ``G`` when caching is enabled.  This
     # preserves explicit calls to :func:`set_cache_maxsize(0)` which are used in
     # tests to temporarily disable caching regardless of graph defaults.
-    if _CACHE_MAXSIZE > 0:
+    if _seed_hash_cache.maxsize > 0:
         _sync_cache_size(G)
-    return _CACHE_MAXSIZE > 0
+    return _seed_hash_cache.maxsize > 0
 
 
-def base_seed(G: Any) -> int:
+def base_seed(G: TNFRGraph | GraphLike) -> int:
     """Return base RNG seed stored in ``G.graph``."""
     graph = get_graph(G)
     return int(graph.get("RANDOM_SEED", 0))
@@ -238,7 +424,7 @@ def set_cache_maxsize(size: int) -> None:
         raise ValueError("size must be non-negative")
     with _RNG_LOCK:
         _seed_hash_cache.configure(new_size)
-        _CACHE_MAXSIZE = new_size
+        _CACHE_MAXSIZE = _seed_hash_cache.maxsize
     _CACHE_LOCKED = new_size != _DEFAULT_CACHE_MAXSIZE
 
 

tnfr/rng.pyi

@@ -0,0 +1,14 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+ScopedCounterCache: Any
+base_seed: Any
+cache_enabled: Any
+clear_rng_cache: Any
+get_cache_maxsize: Any
+make_rng: Any
+seed_hash: Any
+set_cache_maxsize: Any

tnfr/selector.py

@@ -8,32 +8,34 @@ from __future__ import annotations
 
 import threading
 from operator import itemgetter
-from typing import Any, Mapping, TYPE_CHECKING
+from typing import Any, Mapping, TYPE_CHECKING, cast
 from weakref import WeakKeyDictionary
 
 if TYPE_CHECKING:  # pragma: no cover
-    import networkx as nx  # type: ignore[import-untyped]
+    import networkx as nx
 
 from .constants import DEFAULTS
 from .constants.core import SELECTOR_THRESHOLD_DEFAULTS
 from .helpers.numeric import clamp01
 from .metrics.common import compute_dnfr_accel_max
-from .collections_utils import is_non_string_sequence
+from .utils import is_non_string_sequence
+from .types import SelectorNorms, SelectorThresholds, SelectorWeights
 
 
 HYSTERESIS_GLYPHS: set[str] = {"IL", "OZ", "ZHIR", "THOL", "NAV", "RA"}
 
 __all__ = (
     "_selector_thresholds",
-    "_norms_para_selector",
+    "_selector_norms",
     "_calc_selector_score",
     "_apply_selector_hysteresis",
 )
 
 
+_SelectorThresholdItems = tuple[tuple[str, float], ...]
 _SelectorThresholdCacheEntry = tuple[
-    tuple[tuple[str, float], ...],
-    dict[str, float],
+    _SelectorThresholdItems,
+    SelectorThresholds,
 ]
 _SELECTOR_THRESHOLD_CACHE: WeakKeyDictionary[
     "nx.Graph",
@@ -42,7 +44,7 @@ _SELECTOR_THRESHOLD_CACHE: WeakKeyDictionary[
 _SELECTOR_THRESHOLD_CACHE_LOCK = threading.Lock()
 
 
-def _sorted_items(mapping: Mapping[str, float]) -> tuple[tuple[str, float], ...]:
+def _sorted_items(mapping: Mapping[str, float]) -> _SelectorThresholdItems:
     """Return mapping items sorted by key.
 
     Parameters
@@ -59,8 +61,8 @@ def _sorted_items(mapping: Mapping[str, float]) -> tuple[tuple[str, float], ...]
 
 
 def _compute_selector_thresholds(
-    thr_sel_items: tuple[tuple[str, float], ...],
-) -> dict[str, float]:
+    thr_sel_items: _SelectorThresholdItems,
+) -> SelectorThresholds:
     """Construct selector thresholds for a graph.
 
     Parameters
@@ -79,10 +81,10 @@ def _compute_selector_thresholds(
     for key, default in SELECTOR_THRESHOLD_DEFAULTS.items():
         val = thr_sel.get(key, default)
         out[key] = clamp01(float(val))
-    return out
+    return cast(SelectorThresholds, out)
 
 
-def _selector_thresholds(G: "nx.Graph") -> dict[str, float]:
+def _selector_thresholds(G: "nx.Graph") -> SelectorThresholds:
     """Return normalised thresholds for Si, ΔNFR and acceleration.
 
     Parameters
@@ -114,8 +116,8 @@ def _selector_thresholds(G: "nx.Graph") -> dict[str, float]:
     return thresholds
 
 
-def _norms_para_selector(G: "nx.Graph") -> dict:
-    """Compute and cache norms for ΔNFR and acceleration.
+def _selector_norms(G: "nx.Graph") -> SelectorNorms:
+    """Compute and cache selector norms for ΔNFR and acceleration.
 
     Parameters
     ----------
@@ -134,7 +136,7 @@ def _norms_para_selector(G: "nx.Graph") -> dict:
 
 
 def _calc_selector_score(
-    Si: float, dnfr: float, accel: float, weights: dict[str, float]
+    Si: float, dnfr: float, accel: float, weights: SelectorWeights
 ) -> float:
     """Compute weighted selector score.
 
@@ -167,7 +169,7 @@ def _apply_selector_hysteresis(
     dnfr: float,
     accel: float,
     thr: dict[str, float],
-    margin: float,
+    margin: float | None,
 ) -> str | None:
     """Apply hysteresis when values are near thresholds.
 
@@ -183,8 +185,10 @@ def _apply_selector_hysteresis(
         Normalised acceleration.
     thr : dict[str, float]
         Thresholds returned by :func:`_selector_thresholds`.
-    margin : float
-        Distance from thresholds below which the previous glyph is reused.
+    margin : float or None
+        When positive, distance from thresholds below which the previous
+        glyph is reused. Falsy margins disable hysteresis entirely, letting
+        selectors bypass the reuse logic.
 
     Returns
     -------
@@ -192,6 +196,9 @@ def _apply_selector_hysteresis(
         Previous glyph if hysteresis applies, otherwise ``None``.
     """
     # Batch extraction reduces dictionary lookups inside loops.
+    if not margin:
+        return None
+
     si_hi, si_lo, dnfr_hi, dnfr_lo, accel_hi, accel_lo = itemgetter(
         "si_hi", "si_lo", "dnfr_hi", "dnfr_lo", "accel_hi", "accel_lo"
     )(thr)

tnfr/selector.pyi

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+def _apply_selector_hysteresis(
+    nd: dict[str, Any],
+    Si: float,
+    dnfr: float,
+    accel: float,
+    thr: Mapping[str, float],
+    margin: float | None,
+) -> str | None: ...
+_calc_selector_score: Any
+_selector_norms: Any
+_selector_thresholds: Any