tnfr 3.0.3__py3-none-any.whl → 8.5.0__py3-none-any.whl

tnfr/glyph_history.py

@@ -0,0 +1,377 @@
+"""Utilities for tracking structural operator emission history and related metrics.
+
+This module tracks the history of glyphs (structural symbols like AL, EN, IL, etc.)
+that are emitted when structural operators (Emission, Reception, Coherence, etc.)
+are applied to nodes in the TNFR network.
+"""
+
+from __future__ import annotations
+
+from collections import Counter, deque
+from collections.abc import Iterable, Mapping, MutableMapping
+from itertools import islice
+from typing import Any, cast
+
+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__)
+
+__all__ = (
+    "HistoryDict",
+    "push_glyph",
+    "recent_glyph",
+    "ensure_history",
+    "current_step_idx",
+    "append_metric",
+    "count_glyphs",
+)
+
+_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: MutableMapping[str, Any], window: int, *, create_zero: bool = False
+) -> tuple[int, deque[str] | None]:
+    """Validate ``window`` and ensure ``nd['glyph_history']`` deque."""
+
+    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))
+    if not isinstance(hist, deque) or hist.maxlen != v_window:
+        # Rebuild deque from any iterable, ignoring raw strings/bytes and scalars
+        if isinstance(hist, (str, bytes, bytearray)):
+            items: Iterable[Any] = ()
+        else:
+            try:
+                items = ensure_collection(hist, max_materialize=None)
+            except TypeError:
+                logger.debug("Discarding non-iterable glyph history value %r", hist)
+                items = ()
+        hist = deque((str(item) for item in items), maxlen=v_window)
+        nd["glyph_history"] = hist
+    return v_window, hist
+
+
+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
+    :func:`_ensure_history`.
+    """
+
+    _, hist = _ensure_history(nd, window, create_zero=True)
+    hist.append(str(glyph))
+
+
+def recent_glyph(nd: MutableMapping[str, Any], glyph: str, window: int) -> bool:
+    """Return ``True`` if ``glyph`` appeared in last ``window`` emissions.
+
+    This is a **read-only** operation that checks the existing history without
+    modifying it. If ``window`` is zero, returns ``False``. Negative values
+    raise :class:`ValueError`.
+
+    Notes
+    -----
+    This function intentionally does NOT call ``_ensure_history`` to avoid
+    accidentally truncating the glyph_history deque when checking with a
+    smaller window than the deque's maxlen. This preserves the canonical
+    principle that reading history should not modify it.
+
+    Reuses ``validate_window`` and ``ensure_collection`` utilities.
+    """
+    from tnfr.validation.window import validate_window
+
+    v_window = validate_window(window)
+    if v_window == 0:
+        return False
+
+    # Read existing history without modifying it
+    hist = nd.get("glyph_history")
+    if hist is None:
+        return False
+
+    gl = str(glyph)
+
+    # Use canonical ensure_collection to materialize history
+    try:
+        items = list(ensure_collection(hist, max_materialize=None))
+    except (TypeError, ValueError):
+        return False
+
+    # Check only the last v_window items
+    recent_items = items[-v_window:] if len(items) > v_window else items
+    return gl in recent_items
+
+
+class HistoryDict(dict[str, Any]):
+    """Dict specialized for bounded history series and usage counts.
+
+    Usage counts are tracked explicitly via :meth:`get_increment`. Accessing
+    keys through ``__getitem__`` or :meth:`get` does not affect the internal
+    counters, avoiding surprising evictions on mere reads. Counting is now
+    handled with :class:`collections.Counter` alone, relying on
+    :meth:`Counter.most_common` to locate least-used entries when required.
+
+    Parameters
+    ----------
+    data:
+        Initial mapping to populate the dictionary.
+    maxlen:
+        Maximum length for history lists stored as values.
+    """
+
+    def __init__(
+        self,
+        data: Mapping[str, Any] | None = None,
+        *,
+        maxlen: int = 0,
+    ) -> None:
+        super().__init__(data or {})
+        self._maxlen = maxlen
+        self._counts: Counter[str] = Counter()
+        if self._maxlen > 0:
+            for k, v in list(self.items()):
+                if isinstance(v, list):
+                    super().__setitem__(k, deque(v, maxlen=self._maxlen))
+                self._counts[k] = 0
+        else:
+            for k in self:
+                self._counts[k] = 0
+        # ``_heap`` is no longer required with ``Counter.most_common``.
+
+    def _increment(self, key: str) -> None:
+        """Increase usage count for ``key``."""
+        self._counts[key] += 1
+
+    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
+        the deque, while single values are wrapped. Existing deques are
+        returned unchanged.
+        """
+
+        if isinstance(val, deque):
+            return val
+        if isinstance(val, Iterable) and not isinstance(val, (str, bytes)):
+            return deque(val, maxlen=self._maxlen)
+        return deque([val], maxlen=self._maxlen)
+
+    def _resolve_value(self, key: str, default: Any, *, insert: bool) -> Any:
+        if insert:
+            val = super().setdefault(key, default)
+        else:
+            val = super().__getitem__(key)
+        if self._maxlen > 0:
+            if not isinstance(val, Mapping):
+                val = self._to_deque(val)
+            super().__setitem__(key, val)
+        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: 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: 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: 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: 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:
+            self._counts[key] = 0
+        return val
+
+    def pop_least_used(self) -> Any:
+        """Remove and return the value with the smallest usage count."""
+        while self._counts:
+            key = min(self._counts, key=self._counts.get)
+            self._counts.pop(key, None)
+            if key in self:
+                return super().pop(key)
+        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()
+            except KeyError:
+                break
+
+
+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
+    :class:`ValueError` is raised. When ``HISTORY_MAXLEN`` is zero, a regular
+    ``dict`` is used.
+    """
+    maxlen, _ = _ensure_history({}, int(get_param(G, "HISTORY_MAXLEN")))
+    hist = G.graph.get("history")
+    sentinel_key = "_metrics_history_id"
+    replaced = False
+    if maxlen == 0:
+        if isinstance(hist, HistoryDict):
+            hist = dict(hist)
+            G.graph["history"] = hist
+            replaced = True
+        elif hist is None:
+            hist = {}
+            G.graph["history"] = hist
+            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:
+        hist = HistoryDict(hist, maxlen=maxlen)
+        G.graph["history"] = hist
+        replaced = True
+    excess = len(hist) - maxlen
+    if excess > 0:
+        hist.pop_least_used_batch(excess)
+    if replaced:
+        G.graph.pop(sentinel_key, None)
+    _normalise_state_streams(cast(MutableMapping[str, Any], hist))
+    return hist
+
+
+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: MutableMapping[str, list[Any]], key: str, value: Any) -> None:
+    """Append ``value`` to ``hist[key]`` list, creating it if missing."""
+    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: 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
+    ``window`` of zero yields an empty :class:`Counter`. Negative values raise
+    :class:`ValueError`.
+    """
+
+    if window is not None:
+        from tnfr.validation.window import validate_window
+
+        window = validate_window(window)
+        if window == 0:
+            return Counter()
+
+    counts: Counter[str] = Counter()
+    for _, nd in G.nodes(data=True):
+        if last_only:
+            g = last_glyph(nd)
+            if g:
+                counts[g] += 1
+            continue
+        hist = nd.get("glyph_history")
+        if not hist:
+            continue
+        if window is None:
+            seq = hist
+        else:
+            start = max(len(hist) - window, 0)
+            seq = islice(hist, start, None)
+        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,19 @@
+"""Runtime helpers for structural operator glyphs decoupled from validation internals.
+
+This module provides utilities for working with glyphs (structural symbols like
+AL, EN, IL, etc.) that represent the application of structural operators to nodes.
+"""
+
+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,8 @@
+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

@@ -0,0 +1,218 @@
+"""Utilities for freezing objects and checking immutability.
+
+Handlers registered via :func:`functools.singledispatch` live in this module
+and are triggered indirectly by the dispatcher when matching types are
+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, partial, singledispatch, wraps
+from types import MappingProxyType
+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)})
+
+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) -> Iterator[set[int]]:
+    """Context manager that detects reference cycles during freezing."""
+    if seen is None:
+        seen = set()
+    obj_id = id(value)
+    if obj_id in seen:
+        raise ValueError("cycle detected")
+    seen.add(obj_id)
+    try:
+        yield seen
+    finally:
+        seen.remove(obj_id)
+
+
+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) -> FrozenSnapshot:
+        with _cycle_guard(value, seen) as guard_seen:
+            return func(value, guard_seen)
+
+    return wrapper
+
+
+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)
+    tag = "mapping" if frozen else "dict"
+    return (tag, tuple((k, _freeze(v, seen)) for k, v in data.items()))
+
+
+@singledispatch
+@_check_cycle
+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
+    raise TypeError
+
+
+@_freeze.register(tuple)
+@_check_cycle
+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: Iterable[Any], tag: str, seen: set[int]
+) -> FrozenTaggedCollection:
+    return (tag, tuple(_freeze(v, seen) for v in container))
+
+
+def _freeze_iterable_with_tag(
+    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:
+    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 (
+    (list, "list"),
+    (set, "set"),
+    (frozenset, "frozenset"),
+    (bytearray, "bytearray"),
+):
+    _register_iterable(_cls, _tag)
+
+
+@_freeze.register(Mapping)
+@_check_cycle
+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: Iterable[Any]) -> bool:
+    return all(_is_immutable_inner(v) for v in iterable)
+
+
+# Dispatch table kept immutable to avoid accidental mutation.
+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]),
+        "list": lambda v: False,
+        "set": lambda v: False,
+        "bytearray": lambda v: False,
+        "dict": lambda v: False,
+    }
+)
+
+
+@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[Any, ...]) -> bool:  # noqa: F401
+    if value and isinstance(value[0], str):
+        handler = _IMMUTABLE_TAG_DISPATCH.get(value[0])
+        if handler is not None:
+            return handler(value)
+    return _all_immutable(value)
+
+
+@_is_immutable_inner.register(frozenset)
+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_LOCK = threading.Lock()
+
+
+def _is_immutable(value: Any) -> bool:
+    """Check recursively if ``value`` is immutable with caching."""
+    with _IMMUTABLE_CACHE_LOCK:
+        try:
+            return _IMMUTABLE_CACHE[value]
+        except (KeyError, TypeError):
+            pass  # Not in cache or value is unhashable
+
+    try:
+        frozen = _freeze(value)
+    except (TypeError, ValueError):
+        result = False
+    else:
+        result = _is_immutable_inner(frozen)
+
+    with _IMMUTABLE_CACHE_LOCK:
+        try:
+            _IMMUTABLE_CACHE[value] = result
+        except TypeError:
+            pass  # Value is unhashable, cannot cache
+
+    return result
+
+
+__all__ = (
+    "_freeze",
+    "_is_immutable",
+    "_is_immutable_inner",
+    "_IMMUTABLE_CACHE",
+)

tnfr/immutable.pyi

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Iterator, Mapping, Union
+
+from ._compat import TypeAlias
+
+FrozenPrimitive: TypeAlias = Union[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 = Union[
+    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]