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

tnfr/glyph_history.py

@@ -2,15 +2,15 @@
 
 from __future__ import annotations
 
-from typing import Any
-from collections import deque, Counter
+from collections import Counter, deque
+from collections.abc import Iterable, Mapping, MutableMapping
 from itertools import islice
-from collections.abc import Iterable, Mapping
-from functools import lru_cache
+from typing import Any, cast
 
-from .constants import get_param
-from .collections_utils import ensure_collection
-from .logging_utils import get_logger
+from .constants import get_param, normalise_state_token
+from .glyph_runtime import last_glyph
+from .types import TNFRGraph
+from .utils import ensure_collection, get_logger
 
 logger = get_logger(__name__)
 
@@ -21,28 +21,28 @@ __all__ = (
     "ensure_history",
     "current_step_idx",
     "append_metric",
-    "last_glyph",
     "count_glyphs",
 )
 
 
-@lru_cache(maxsize=1)
-def _resolve_validate_window():
-    from .validators import validate_window
-
-    return validate_window
-
-
-def _validate_window(window: int, *, positive: bool = False) -> int:
-    return _resolve_validate_window()(window, positive=positive)
+_NU_F_HISTORY_KEYS = (
+    "nu_f_rate_hz_str",
+    "nu_f_rate_hz",
+    "nu_f_ci_lower_hz_str",
+    "nu_f_ci_upper_hz_str",
+    "nu_f_ci_lower_hz",
+    "nu_f_ci_upper_hz",
+)
 
 
 def _ensure_history(
-    nd: dict[str, Any], window: int, *, create_zero: bool = False
-) -> tuple[int, deque | None]:
+    nd: MutableMapping[str, Any], window: int, *, create_zero: bool = False
+) -> tuple[int, deque[str] | None]:
     """Validate ``window`` and ensure ``nd['glyph_history']`` deque."""
 
-    v_window = _validate_window(window)
+    from tnfr.validation.window import validate_window
+
+    v_window = validate_window(window)
     if v_window == 0 and not create_zero:
         return v_window, None
     hist = nd.setdefault("glyph_history", deque(maxlen=v_window))
@@ -54,16 +54,14 @@ def _ensure_history(
             try:
                 items = ensure_collection(hist, max_materialize=None)
             except TypeError:
-                logger.debug(
-                    "Discarding non-iterable glyph history value %r", hist
-                )
+                logger.debug("Discarding non-iterable glyph history value %r", hist)
                 items = ()
-        hist = deque(items, maxlen=v_window)
+        hist = deque((str(item) for item in items), maxlen=v_window)
         nd["glyph_history"] = hist
     return v_window, hist
 
 
-def push_glyph(nd: dict[str, Any], glyph: str, window: int) -> None:
+def push_glyph(nd: MutableMapping[str, Any], glyph: str, window: int) -> None:
     """Add ``glyph`` to node history with maximum size ``window``.
 
     ``window`` validation and deque creation are handled by
@@ -74,7 +72,7 @@ def push_glyph(nd: dict[str, Any], glyph: str, window: int) -> None:
     hist.append(str(glyph))
 
 
-def recent_glyph(nd: dict[str, Any], glyph: str, window: int) -> bool:
+def recent_glyph(nd: MutableMapping[str, Any], glyph: str, window: int) -> bool:
     """Return ``True`` if ``glyph`` appeared in last ``window`` emissions.
 
     ``window`` validation and deque creation are handled by
@@ -89,7 +87,7 @@ def recent_glyph(nd: dict[str, Any], glyph: str, window: int) -> bool:
     return gl in hist
 
 
-class HistoryDict(dict):
+class HistoryDict(dict[str, Any]):
     """Dict specialized for bounded history series and usage counts.
 
     Usage counts are tracked explicitly via :meth:`get_increment`. Accessing
@@ -108,7 +106,7 @@ class HistoryDict(dict):
 
     def __init__(
         self,
-        data: dict[str, Any] | None = None,
+        data: Mapping[str, Any] | None = None,
         *,
         maxlen: int = 0,
     ) -> None:
@@ -129,7 +127,7 @@ class HistoryDict(dict):
         """Increase usage count for ``key``."""
         self._counts[key] += 1
 
-    def _to_deque(self, val: Any) -> deque:
+    def _to_deque(self, val: Any) -> deque[Any]:
         """Coerce ``val`` to a deque respecting ``self._maxlen``.
 
         ``Iterable`` inputs (excluding ``str`` and ``bytes``) are expanded into
@@ -155,26 +153,36 @@ class HistoryDict(dict):
         return val
 
     def get_increment(self, key: str, default: Any = None) -> Any:
+        """Return value for ``key`` and increment its usage counter."""
+
         insert = key not in self
         val = self._resolve_value(key, default, insert=insert)
         self._increment(key)
         return val
 
-    def __getitem__(self, key):  # type: ignore[override]
+    def __getitem__(self, key: str) -> Any:  # type: ignore[override]
+        """Return the tracked value for ``key`` ensuring deque normalisation."""
+
         return self._resolve_value(key, None, insert=False)
 
-    def get(self, key, default=None):  # type: ignore[override]
+    def get(self, key: str, default: Any | None = None) -> Any:  # type: ignore[override]
+        """Return ``key`` when present; otherwise fall back to ``default``."""
+
         try:
             return self._resolve_value(key, None, insert=False)
         except KeyError:
             return default
 
-    def __setitem__(self, key, value):  # type: ignore[override]
+    def __setitem__(self, key: str, value: Any) -> None:  # type: ignore[override]
+        """Store ``value`` for ``key`` while initialising usage tracking."""
+
         super().__setitem__(key, value)
         if key not in self._counts:
             self._counts[key] = 0
 
-    def setdefault(self, key, default=None):  # type: ignore[override]
+    def setdefault(self, key: str, default: Any | None = None) -> Any:  # type: ignore[override]
+        """Return existing value for ``key`` or insert ``default`` when absent."""
+
         insert = key not in self
         val = self._resolve_value(key, default, insert=insert)
         if insert:
@@ -191,6 +199,8 @@ class HistoryDict(dict):
         raise KeyError("HistoryDict is empty; cannot pop least used")
 
     def pop_least_used_batch(self, k: int) -> None:
+        """Remove up to ``k`` least-used entries from the history."""
+
         for _ in range(max(0, int(k))):
             try:
                 self.pop_least_used()
@@ -198,7 +208,7 @@ class HistoryDict(dict):
                 break
 
 
-def ensure_history(G) -> dict[str, Any]:
+def ensure_history(G: TNFRGraph) -> HistoryDict | dict[str, Any]:
     """Ensure ``G.graph['history']`` exists and return it.
 
     ``HISTORY_MAXLEN`` must be non-negative; otherwise a
@@ -220,11 +230,10 @@ def ensure_history(G) -> dict[str, Any]:
             replaced = True
         if replaced:
             G.graph.pop(sentinel_key, None)
+        if isinstance(hist, MutableMapping):
+            _normalise_state_streams(hist)
         return hist
-    if (
-        not isinstance(hist, HistoryDict)
-        or hist._maxlen != maxlen
-    ):
+    if not isinstance(hist, HistoryDict) or hist._maxlen != maxlen:
         hist = HistoryDict(hist, maxlen=maxlen)
         G.graph["history"] = hist
         replaced = True
@@ -233,31 +242,44 @@ def ensure_history(G) -> dict[str, Any]:
         hist.pop_least_used_batch(excess)
     if replaced:
         G.graph.pop(sentinel_key, None)
+    _normalise_state_streams(cast(MutableMapping[str, Any], hist))
+    for key in _NU_F_HISTORY_KEYS:
+        hist.setdefault(key, [])
     return hist
 
 
-def current_step_idx(G) -> int:
+def current_step_idx(G: TNFRGraph | Mapping[str, Any]) -> int:
     """Return the current step index from ``G`` history."""
 
     graph = getattr(G, "graph", G)
     return len(graph.get("history", {}).get("C_steps", []))
 
-    
 
-def append_metric(hist: dict[str, Any], key: str, value: Any) -> None:
+def append_metric(hist: MutableMapping[str, list[Any]], key: str, value: Any) -> None:
     """Append ``value`` to ``hist[key]`` list, creating it if missing."""
-    hist.setdefault(key, []).append(value)
-
-
-def last_glyph(nd: dict[str, Any]) -> str | None:
-    """Return the most recent glyph for node or ``None``."""
-    hist = nd.get("glyph_history")
-    return hist[-1] if hist else None
-
+    if key == "phase_state" and isinstance(value, str):
+        value = normalise_state_token(value)
+    elif key == "nodal_diag" and isinstance(value, Mapping):
+        snapshot: dict[Any, Any] = {}
+        for node, payload in value.items():
+            if isinstance(payload, Mapping):
+                state_value = payload.get("state")
+                if isinstance(payload, MutableMapping):
+                    updated = payload
+                else:
+                    updated = dict(payload)
+                if isinstance(state_value, str):
+                    updated["state"] = normalise_state_token(state_value)
+                snapshot[node] = updated
+            else:
+                snapshot[node] = payload
+        hist.setdefault(key, []).append(snapshot)
+        return
 
+    hist.setdefault(key, []).append(value)
 def count_glyphs(
-    G, window: int | None = None, *, last_only: bool = False
-) -> Counter:
+    G: TNFRGraph, window: int | None = None, *, last_only: bool = False
+) -> Counter[str]:
     """Count recent glyphs in the network.
 
     If ``window`` is ``None``, the full history for each node is used. A
@@ -266,7 +288,9 @@ def count_glyphs(
     """
 
     if window is not None:
-        window = _validate_window(window)
+        from tnfr.validation.window import validate_window
+
+        window = validate_window(window)
         if window == 0:
             return Counter()
 
@@ -288,3 +312,37 @@ def count_glyphs(
         counts.update(seq)
 
     return counts
+
+
+def _normalise_state_streams(hist: MutableMapping[str, Any]) -> None:
+    """Normalise legacy state tokens stored in telemetry history."""
+
+    phase_state = hist.get("phase_state")
+    if isinstance(phase_state, deque):
+        canonical = [normalise_state_token(str(item)) for item in phase_state]
+        if canonical != list(phase_state):
+            phase_state.clear()
+            phase_state.extend(canonical)
+    elif isinstance(phase_state, list):
+        canonical = [normalise_state_token(str(item)) for item in phase_state]
+        if canonical != phase_state:
+            hist["phase_state"] = canonical
+
+    diag_history = hist.get("nodal_diag")
+    if isinstance(diag_history, list):
+        for snapshot in diag_history:
+            if not isinstance(snapshot, Mapping):
+                continue
+            for node, payload in snapshot.items():
+                if not isinstance(payload, Mapping):
+                    continue
+                state_value = payload.get("state")
+                if not isinstance(state_value, str):
+                    continue
+                canonical = normalise_state_token(state_value)
+                if canonical == state_value:
+                    continue
+                if isinstance(payload, MutableMapping):
+                    payload["state"] = canonical
+                else:
+                    snapshot[node] = {**payload, "state": canonical}

tnfr/glyph_history.pyi

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Mapping, MutableMapping
+from typing import Any
+
+from .types import TNFRGraph
+
+__all__: tuple[str, ...]
+
+class HistoryDict(dict[str, Any]):
+    _maxlen: int
+    _counts: Counter[str]
+
+    def __init__(
+        self, data: Mapping[str, Any] | None = ..., *, maxlen: int = ...
+    ) -> None: ...
+    def get_increment(self, key: str, default: Any = ...) -> Any: ...
+    def __getitem__(self, key: str) -> Any: ...
+    def get(self, key: str, default: Any | None = ...) -> Any: ...
+    def __setitem__(self, key: str, value: Any) -> None: ...
+    def setdefault(self, key: str, default: Any | None = ...) -> Any: ...
+    def pop_least_used(self) -> Any: ...
+    def pop_least_used_batch(self, k: int) -> None: ...
+
+def push_glyph(nd: MutableMapping[str, Any], glyph: str, window: int) -> None: ...
+def recent_glyph(nd: MutableMapping[str, Any], glyph: str, window: int) -> bool: ...
+def ensure_history(G: TNFRGraph) -> HistoryDict | dict[str, Any]: ...
+def current_step_idx(G: TNFRGraph | Mapping[str, Any]) -> int: ...
+def append_metric(
+    hist: MutableMapping[str, list[Any]], key: str, value: Any
+) -> None: ...
+def count_glyphs(
+    G: TNFRGraph, window: int | None = ..., *, last_only: bool = ...
+) -> Counter[str]: ...

tnfr/glyph_runtime.py

@@ -0,0 +1,16 @@
+"""Runtime glyph helpers decoupled from validation internals."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+__all__ = ("last_glyph",)
+
+
+def last_glyph(nd: Mapping[str, Any]) -> str | None:
+    """Return the most recent glyph for node or ``None``."""
+
+    hist = nd.get("glyph_history")
+    return hist[-1] if hist else None
+

tnfr/glyph_runtime.pyi

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+__all__: tuple[str, ...]
+
+def last_glyph(nd: Mapping[str, Any]) -> str | None: ...
+

tnfr/immutable.py

@@ -7,23 +7,47 @@ encountered.
 
 from __future__ import annotations
 
+import threading
+import weakref
+from collections.abc import Mapping
 from contextlib import contextmanager
 from dataclasses import asdict, is_dataclass
-from functools import lru_cache, singledispatch, wraps, partial
-from typing import Any, Callable
-from collections.abc import Mapping
+from functools import lru_cache, partial, singledispatch, wraps
 from types import MappingProxyType
-import threading
-import weakref
+from typing import Any, Callable, Iterable, Iterator, cast
+
+from ._compat import TypeAlias
 
 # Types considered immutable without further inspection
-IMMUTABLE_SIMPLE = frozenset(
-    {int, float, complex, str, bool, bytes, type(None)}
+IMMUTABLE_SIMPLE = frozenset({int, float, complex, str, bool, bytes, type(None)})
+
+
+FrozenPrimitive: TypeAlias = int | float | complex | str | bool | bytes | None
+"""Primitive immutable values handled directly by :func:`_freeze`."""
+
+FrozenCollectionItems: TypeAlias = tuple["FrozenSnapshot", ...]
+"""Frozen representation for generic iterables."""
+
+FrozenMappingItems: TypeAlias = tuple[tuple[Any, "FrozenSnapshot"], ...]
+"""Frozen representation for mapping ``items()`` snapshots."""
+
+FrozenTaggedCollection: TypeAlias = tuple[str, FrozenCollectionItems]
+"""Tagged iterable snapshot identifying the original container type."""
+
+FrozenTaggedMapping: TypeAlias = tuple[str, FrozenMappingItems]
+"""Tagged mapping snapshot identifying the original mapping flavour."""
+
+FrozenSnapshot: TypeAlias = (
+    FrozenPrimitive
+    | FrozenCollectionItems
+    | FrozenTaggedCollection
+    | FrozenTaggedMapping
 )
+"""Union describing the immutable snapshot returned by :func:`_freeze`."""
 
 
 @contextmanager
-def _cycle_guard(value: Any, seen: set[int] | None = None):
+def _cycle_guard(value: Any, seen: set[int] | None = None) -> Iterator[set[int]]:
     """Context manager that detects reference cycles during freezing."""
     if seen is None:
         seen = set()
@@ -37,18 +61,20 @@ def _cycle_guard(value: Any, seen: set[int] | None = None):
         seen.remove(obj_id)
 
 
-def _check_cycle(func: Callable[[Any, set[int] | None], Any]):
-    """Decorator applying :func:`_cycle_guard` to ``func``."""
+def _check_cycle(
+    func: Callable[[Any, set[int] | None], FrozenSnapshot],
+) -> Callable[[Any, set[int] | None], FrozenSnapshot]:
+    """Apply :func:`_cycle_guard` to ``func``."""
 
     @wraps(func)
-    def wrapper(value: Any, seen: set[int] | None = None):
-        with _cycle_guard(value, seen) as seen:
-            return func(value, seen)
+    def wrapper(value: Any, seen: set[int] | None = None) -> FrozenSnapshot:
+        with _cycle_guard(value, seen) as guard_seen:
+            return func(value, guard_seen)
 
     return wrapper
 
 
-def _freeze_dataclass(value: Any, seen: set[int]):
+def _freeze_dataclass(value: Any, seen: set[int]) -> FrozenTaggedMapping:
     params = getattr(type(value), "__dataclass_params__", None)
     frozen = bool(params and params.frozen)
     data = asdict(value)
@@ -58,9 +84,10 @@ def _freeze_dataclass(value: Any, seen: set[int]):
 
 @singledispatch
 @_check_cycle
-def _freeze(value: Any, seen: set[int] | None = None):
+def _freeze(value: Any, seen: set[int] | None = None) -> FrozenSnapshot:
     """Recursively convert ``value`` into an immutable representation."""
     if is_dataclass(value) and not isinstance(value, type):
+        assert seen is not None
         return _freeze_dataclass(value, seen)
     if type(value) in IMMUTABLE_SIMPLE:
         return value
@@ -69,22 +96,31 @@ def _freeze(value: Any, seen: set[int] | None = None):
 
 @_freeze.register(tuple)
 @_check_cycle
-def _freeze_tuple(value: tuple, seen: set[int] | None = None):  # noqa: F401
+def _freeze_tuple(
+    value: tuple[Any, ...], seen: set[int] | None = None
+) -> FrozenCollectionItems:  # noqa: F401
+    assert seen is not None
     return tuple(_freeze(v, seen) for v in value)
 
 
-def _freeze_iterable(container: Any, tag: str, seen: set[int] | None) -> tuple[str, tuple]:
+def _freeze_iterable(
+    container: Iterable[Any], tag: str, seen: set[int]
+) -> FrozenTaggedCollection:
     return (tag, tuple(_freeze(v, seen) for v in container))
 
 
 def _freeze_iterable_with_tag(
-    value: Any, seen: set[int] | None = None, *, tag: str
-) -> tuple[str, tuple]:
+    value: Iterable[Any], seen: set[int] | None = None, *, tag: str
+) -> FrozenTaggedCollection:
+    assert seen is not None
     return _freeze_iterable(value, tag, seen)
 
 
 def _register_iterable(cls: type, tag: str) -> None:
-    _freeze.register(cls)(_check_cycle(partial(_freeze_iterable_with_tag, tag=tag)))
+    handler = _check_cycle(partial(_freeze_iterable_with_tag, tag=tag))
+    _freeze.register(cls)(
+        cast(Callable[[Any, set[int] | None], FrozenSnapshot], handler)
+    )
 
 
 for _cls, _tag in (
@@ -98,17 +134,22 @@ for _cls, _tag in (
 
 @_freeze.register(Mapping)
 @_check_cycle
-def _freeze_mapping(value: Mapping, seen: set[int] | None = None):  # noqa: F401
+def _freeze_mapping(
+    value: Mapping[Any, Any], seen: set[int] | None = None
+) -> FrozenTaggedMapping:  # noqa: F401
+    assert seen is not None
     tag = "dict" if hasattr(value, "__setitem__") else "mapping"
     return (tag, tuple((k, _freeze(v, seen)) for k, v in value.items()))
 
 
-def _all_immutable(iterable) -> bool:
+def _all_immutable(iterable: Iterable[Any]) -> bool:
     return all(_is_immutable_inner(v) for v in iterable)
 
 
 # Dispatch table kept immutable to avoid accidental mutation.
-_IMMUTABLE_TAG_DISPATCH: Mapping[str, Callable[[tuple], bool]] = MappingProxyType(
+ImmutableTagHandler: TypeAlias = Callable[[tuple[Any, ...]], bool]
+
+_IMMUTABLE_TAG_DISPATCH: Mapping[str, ImmutableTagHandler] = MappingProxyType(
     {
         "mapping": lambda v: _all_immutable(v[1]),
         "frozenset": lambda v: _all_immutable(v[1]),
@@ -123,11 +164,13 @@ _IMMUTABLE_TAG_DISPATCH: Mapping[str, Callable[[tuple], bool]] = MappingProxyTyp
 @lru_cache(maxsize=1024)
 @singledispatch
 def _is_immutable_inner(value: Any) -> bool:
+    """Return ``True`` when ``value`` belongs to the canonical immutable set."""
+
     return type(value) in IMMUTABLE_SIMPLE
 
 
 @_is_immutable_inner.register(tuple)
-def _is_immutable_inner_tuple(value: tuple) -> bool:  # noqa: F401
+def _is_immutable_inner_tuple(value: tuple[Any, ...]) -> bool:  # noqa: F401
     if value and isinstance(value[0], str):
         handler = _IMMUTABLE_TAG_DISPATCH.get(value[0])
         if handler is not None:
@@ -136,13 +179,11 @@ def _is_immutable_inner_tuple(value: tuple) -> bool:  # noqa: F401
 
 
 @_is_immutable_inner.register(frozenset)
-def _is_immutable_inner_frozenset(value: frozenset) -> bool:  # noqa: F401
+def _is_immutable_inner_frozenset(value: frozenset[Any]) -> bool:  # noqa: F401
     return _all_immutable(value)
 
 
-_IMMUTABLE_CACHE: weakref.WeakKeyDictionary[Any, bool] = (
-    weakref.WeakKeyDictionary()
-)
+_IMMUTABLE_CACHE: weakref.WeakKeyDictionary[Any, bool] = weakref.WeakKeyDictionary()
 _IMMUTABLE_CACHE_LOCK = threading.Lock()
 
 

tnfr/immutable.pyi

@@ -0,0 +1,34 @@
+from typing import Any, Callable, Iterator, Mapping
+
+from ._compat import TypeAlias
+
+FrozenPrimitive: TypeAlias = int | float | complex | str | bool | bytes | None
+FrozenCollectionItems: TypeAlias = tuple["FrozenSnapshot", ...]
+FrozenMappingItems: TypeAlias = tuple[tuple[Any, "FrozenSnapshot"], ...]
+FrozenTaggedCollection: TypeAlias = tuple[str, FrozenCollectionItems]
+FrozenTaggedMapping: TypeAlias = tuple[str, FrozenMappingItems]
+FrozenSnapshot: TypeAlias = (
+    FrozenPrimitive
+    | FrozenCollectionItems
+    | FrozenTaggedCollection
+    | FrozenTaggedMapping
+)
+ImmutableTagHandler: TypeAlias = Callable[[tuple[Any, ...]], bool]
+
+__all__: tuple[str, ...]
+
+def __getattr__(name: str) -> Any: ...
+def _cycle_guard(value: Any, seen: set[int] | None = ...) -> Iterator[set[int]]: ...
+def _check_cycle(
+    func: Callable[[Any, set[int] | None], FrozenSnapshot],
+) -> Callable[[Any, set[int] | None], FrozenSnapshot]: ...
+def _freeze(value: Any, seen: set[int] | None = ...) -> FrozenSnapshot: ...
+def _freeze_mapping(
+    value: Mapping[Any, Any],
+    seen: set[int] | None = ...,
+) -> FrozenTaggedMapping: ...
+def _is_immutable(value: Any) -> bool: ...
+def _is_immutable_inner(value: Any) -> bool: ...
+
+_IMMUTABLE_CACHE: Any
+_IMMUTABLE_TAG_DISPATCH: Mapping[str, ImmutableTagHandler]