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

tnfr/helpers/__init__.py

@@ -0,0 +1,151 @@
+"""Curated high-level helpers exposed by :mod:`tnfr.helpers`.
+
+The module is intentionally small and surfaces utilities that are stable for
+external use, covering data preparation, glyph history management, and graph
+cache invalidation.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import TYPE_CHECKING, Any, Callable, Mapping, MutableMapping, Protocol, cast
+
+from ..types import TNFRGraph
+
+if TYPE_CHECKING:  # pragma: no cover - import-time only for typing
+    from ..utils import (
+        CacheManager,
+        EdgeCacheManager,
+        cached_node_list,
+        cached_nodes_and_A,
+        edge_version_cache,
+        edge_version_update,
+        ensure_node_index_map,
+        ensure_node_offset_map,
+        get_graph,
+        get_graph_mapping,
+        increment_edge_version,
+        mark_dnfr_prep_dirty,
+        node_set_checksum,
+        stable_json,
+    )
+    from ..glyph_history import HistoryDict
+from .numeric import (
+    angle_diff,
+    clamp,
+    clamp01,
+    kahan_sum_nd,
+)
+
+__all__ = (
+    "CacheManager",
+    "EdgeCacheManager",
+    "angle_diff",
+    "cached_node_list",
+    "cached_nodes_and_A",
+    "clamp",
+    "clamp01",
+    "edge_version_cache",
+    "edge_version_update",
+    "ensure_node_index_map",
+    "ensure_node_offset_map",
+    "get_graph",
+    "get_graph_mapping",
+    "increment_edge_version",
+    "kahan_sum_nd",
+    "mark_dnfr_prep_dirty",
+    "node_set_checksum",
+    "stable_json",
+    "count_glyphs",
+    "ensure_history",
+    "last_glyph",
+    "push_glyph",
+    "recent_glyph",
+    "__getattr__",
+)
+
+
+_UTIL_EXPORTS = {
+    "CacheManager",
+    "EdgeCacheManager",
+    "cached_node_list",
+    "cached_nodes_and_A",
+    "edge_version_cache",
+    "edge_version_update",
+    "ensure_node_index_map",
+    "ensure_node_offset_map",
+    "get_graph",
+    "get_graph_mapping",
+    "increment_edge_version",
+    "mark_dnfr_prep_dirty",
+    "node_set_checksum",
+    "stable_json",
+}
+
+
+def __getattr__(name: str) -> Any:  # pragma: no cover - simple delegation
+    if name in _UTIL_EXPORTS:
+        from .. import utils as _utils
+
+        value = getattr(_utils, name)
+        globals()[name] = value
+        return value
+    raise AttributeError(name)
+
+
+def __dir__() -> list[str]:  # pragma: no cover - simple reflection
+    return sorted(set(__all__))
+
+
+class _PushGlyphCallable(Protocol):
+    def __call__(self, nd: MutableMapping[str, Any], glyph: str, window: int) -> None:
+        ...
+
+
+class _RecentGlyphCallable(Protocol):
+    def __call__(self, nd: MutableMapping[str, Any], glyph: str, window: int) -> bool:
+        ...
+
+
+class _EnsureHistoryCallable(Protocol):
+    def __call__(self, G: TNFRGraph) -> "HistoryDict | dict[str, Any]":
+        ...
+
+
+class _LastGlyphCallable(Protocol):
+    def __call__(self, nd: Mapping[str, Any]) -> str | None:
+        ...
+
+
+class _CountGlyphsCallable(Protocol):
+    def __call__(
+        self, G: TNFRGraph, window: int | None = ..., *, last_only: bool = ...
+    ) -> Counter[str]:
+        ...
+
+
+def _glyph_history_proxy(name: str) -> Callable[..., Any]:
+    """Return a wrapper that delegates to :mod:`tnfr.glyph_history` lazily."""
+
+    target: dict[str, Callable[..., Any] | None] = {"func": None}
+
+    def _call(*args: Any, **kwargs: Any) -> Any:
+        func = target["func"]
+        if func is None:
+            from .. import glyph_history as _glyph_history
+
+            func = getattr(_glyph_history, name)
+            target["func"] = func
+        return func(*args, **kwargs)
+
+    _call.__name__ = name
+    _call.__qualname__ = name
+    _call.__doc__ = f"Proxy for :func:`tnfr.glyph_history.{name}`."
+    return _call
+
+
+count_glyphs = cast(_CountGlyphsCallable, _glyph_history_proxy("count_glyphs"))
+ensure_history = cast(_EnsureHistoryCallable, _glyph_history_proxy("ensure_history"))
+last_glyph = cast(_LastGlyphCallable, _glyph_history_proxy("last_glyph"))
+push_glyph = cast(_PushGlyphCallable, _glyph_history_proxy("push_glyph"))
+recent_glyph = cast(_RecentGlyphCallable, _glyph_history_proxy("recent_glyph"))

tnfr/helpers/__init__.pyi

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..cache import CacheManager as CacheManager
+from ..glyph_history import (
+    HistoryDict,
+    count_glyphs as count_glyphs,
+    ensure_history as ensure_history,
+    last_glyph as last_glyph,
+    push_glyph as push_glyph,
+    recent_glyph as recent_glyph,
+)
+from ..utils.cache import (
+    EdgeCacheManager as EdgeCacheManager,
+    cached_node_list as cached_node_list,
+    cached_nodes_and_A as cached_nodes_and_A,
+    edge_version_cache as edge_version_cache,
+    edge_version_update as edge_version_update,
+    ensure_node_index_map as ensure_node_index_map,
+    ensure_node_offset_map as ensure_node_offset_map,
+    node_set_checksum as node_set_checksum,
+    stable_json as stable_json,
+)
+from ..utils.graph import (
+    get_graph as get_graph,
+    get_graph_mapping as get_graph_mapping,
+    increment_edge_version as increment_edge_version,
+    mark_dnfr_prep_dirty as mark_dnfr_prep_dirty,
+)
+from .numeric import (
+    angle_diff as angle_diff,
+    clamp as clamp,
+    clamp01 as clamp01,
+    kahan_sum_nd as kahan_sum_nd,
+)
+
+__all__ = (
+    "CacheManager",
+    "EdgeCacheManager",
+    "angle_diff",
+    "cached_node_list",
+    "cached_nodes_and_A",
+    "clamp",
+    "clamp01",
+    "edge_version_cache",
+    "edge_version_update",
+    "ensure_node_index_map",
+    "ensure_node_offset_map",
+    "get_graph",
+    "get_graph_mapping",
+    "increment_edge_version",
+    "kahan_sum_nd",
+    "mark_dnfr_prep_dirty",
+    "node_set_checksum",
+    "stable_json",
+    "count_glyphs",
+    "ensure_history",
+    "last_glyph",
+    "push_glyph",
+    "recent_glyph",
+    "__getattr__",
+)
+
+
+def __getattr__(name: str) -> Any: ...

tnfr/helpers/numeric.py

@@ -0,0 +1,88 @@
+"""Numeric helper functions and compensated summation utilities."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+import math
+
+__all__ = (
+    "clamp",
+    "clamp01",
+    "within_range",
+    "similarity_abs",
+    "kahan_sum_nd",
+    "angle_diff",
+)
+
+
+def clamp(x: float, a: float, b: float) -> float:
+    """Return ``x`` clamped to the ``[a, b]`` interval."""
+    return max(a, min(b, x))
+
+
+def clamp01(x: float) -> float:
+    """Clamp ``x`` to the ``[0,1]`` interval."""
+    return clamp(float(x), 0.0, 1.0)
+
+
+def within_range(val: float, lower: float, upper: float, tol: float = 1e-9) -> bool:
+    """Return ``True`` if ``val`` lies in ``[lower, upper]`` within ``tol``.
+
+    The comparison uses absolute differences instead of :func:`math.isclose`.
+    """
+
+    v = float(val)
+    return lower <= v <= upper or abs(v - lower) <= tol or abs(v - upper) <= tol
+
+
+def _norm01(x: float, lo: float, hi: float) -> float:
+    """Normalize ``x`` to the unit interval given bounds.
+
+    ``lo`` and ``hi`` delimit the original value range. When ``hi`` is not
+    greater than ``lo`` the function returns ``0.0`` to avoid division by
+    zero. The result is clamped to ``[0,1]``.
+    """
+
+    if hi <= lo:
+        return 0.0
+    return clamp01((float(x) - float(lo)) / (float(hi) - float(lo)))
+
+
+def similarity_abs(a: float, b: float, lo: float, hi: float) -> float:
+    """Return absolute similarity of ``a`` and ``b`` over ``[lo, hi]``.
+
+    It computes ``1`` minus the normalized absolute difference between
+    ``a`` and ``b``. Values are scaled using :func:`_norm01` so the result
+    falls within ``[0,1]``.
+    """
+
+    return 1.0 - _norm01(abs(float(a) - float(b)), 0.0, hi - lo)
+
+
+def kahan_sum_nd(
+    values: Iterable[Sequence[float]], dims: int
+) -> tuple[float, ...]:
+    """Return compensated sums of ``values`` with ``dims`` components.
+
+    Each component of the tuples in ``values`` is summed independently using the
+    Kahan–Babuška (Neumaier) algorithm to reduce floating point error.
+    """
+    if dims < 1:
+        raise ValueError("dims must be >= 1")
+    totals = [0.0] * dims
+    comps = [0.0] * dims
+    for vs in values:
+        for i in range(dims):
+            v = vs[i]
+            t = totals[i] + v
+            if abs(totals[i]) >= abs(v):
+                comps[i] += (totals[i] - t) + v
+            else:
+                comps[i] += (v - t) + totals[i]
+            totals[i] = t
+    return tuple(float(totals[i] + comps[i]) for i in range(dims))
+
+
+def angle_diff(a: float, b: float) -> float:
+    """Return the minimal difference between two angles in radians."""
+    return (float(a) - float(b) + math.pi) % math.tau - math.pi

tnfr/helpers/numeric.pyi

@@ -0,0 +1,12 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+angle_diff: Any
+clamp: Any
+clamp01: Any
+kahan_sum_nd: Any
+similarity_abs: Any
+within_range: Any

tnfr/immutable.py

@@ -0,0 +1,214 @@
+"""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
+
+from contextlib import contextmanager
+from dataclasses import asdict, is_dataclass
+from functools import lru_cache, partial, singledispatch, wraps
+from typing import Any, Callable, Iterable, Iterator, cast
+from collections.abc import Mapping
+from types import MappingProxyType
+import threading
+import weakref
+
+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]:
+    """Decorator applying :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 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
+
+    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
+
+    return result
+
+
+__all__ = (
+    "_freeze",
+    "_is_immutable",
+    "_is_immutable_inner",
+    "_IMMUTABLE_CACHE",
+)

tnfr/immutable.pyi

@@ -0,0 +1,37 @@
+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]