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

tnfr/helpers/__init__.py

@@ -7,19 +7,29 @@ cache invalidation.
 
 from __future__ import annotations
 
-from ..cache import (
-    EdgeCacheManager,
-    cached_node_list,
-    cached_nodes_and_A,
-    edge_version_cache,
-    edge_version_update,
-    ensure_node_index_map,
-    ensure_node_offset_map,
-    increment_edge_version,
-    node_set_checksum,
-    stable_json,
-)
-from ..graph_utils import get_graph, get_graph_mapping, mark_dnfr_prep_dirty
+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,
@@ -27,17 +37,8 @@ from .numeric import (
     kahan_sum_nd,
 )
 
-
-def __getattr__(name: str):
-    if name in _GLYPH_HISTORY_EXPORTS:
-        from .. import glyph_history as _glyph_history
-
-        value = getattr(_glyph_history, name)
-        globals()[name] = value
-        return value
-    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
-
 __all__ = (
+    "CacheManager",
     "EdgeCacheManager",
     "angle_diff",
     "cached_node_list",
@@ -60,12 +61,91 @@ __all__ = (
     "last_glyph",
     "push_glyph",
     "recent_glyph",
+    "__getattr__",
 )
 
-_GLYPH_HISTORY_EXPORTS = (
-    "count_glyphs",
-    "ensure_history",
-    "last_glyph",
-    "push_glyph",
-    "recent_glyph",
-)
+
+_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

@@ -58,6 +58,7 @@ def similarity_abs(a: float, b: float, lo: float, hi: float) -> float:
 
     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, ...]:

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

@@ -9,21 +9,44 @@ from __future__ import annotations
 
 from contextlib import contextmanager
 from dataclasses import asdict, is_dataclass
-from functools import lru_cache, singledispatch, wraps, partial
-from typing import Any, Callable
+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):
+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 +60,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]):
+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):
-        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 +83,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 +95,27 @@ 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 +129,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]),
@@ -127,7 +163,7 @@ def _is_immutable_inner(value: Any) -> bool:
 
 
 @_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,7 +172,7 @@ 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)
 
 

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]

tnfr/initialization.py

@@ -2,23 +2,24 @@
 
 from __future__ import annotations
 import random
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 from dataclasses import dataclass
 
 from .constants import VF_KEY, THETA_KEY, get_graph_param
 from .helpers.numeric import clamp
 from .rng import make_rng
+from .types import NodeInitAttrMap
 
 if TYPE_CHECKING:  # pragma: no cover
-    import networkx as nx  # type: ignore[import-untyped]
+    import networkx as nx
 
 __all__ = ("InitParams", "init_node_attrs")
 
 
 @dataclass
 class InitParams:
-    """Parametros de inicialización nodal."""
+    """Parameters governing node initialisation."""
 
     seed: int | None
     init_rand_phase: bool
@@ -38,7 +39,7 @@ class InitParams:
 
     @classmethod
     def from_graph(cls, G: "nx.Graph") -> "InitParams":
-        """Construir ``InitParams`` desde ``G.graph``."""
+        """Construct ``InitParams`` from ``G.graph`` configuration."""
 
         return cls(
             seed=get_graph_param(G, "RANDOM_SEED", int),
@@ -62,7 +63,7 @@ class InitParams:
 
 
 def _init_phase(
-    nd: dict,
+    nd: NodeInitAttrMap,
     rng: random.Random,
     *,
     override: bool,
@@ -82,7 +83,7 @@ def _init_phase(
 
 
 def _init_vf(
-    nd: dict,
+    nd: NodeInitAttrMap,
     rng: random.Random,
     *,
     override: bool,
@@ -118,7 +119,7 @@ def _init_vf(
 
 
 def _init_si_epi(
-    nd: dict,
+    nd: NodeInitAttrMap,
     rng: random.Random,
     *,
     override: bool,
@@ -163,9 +164,10 @@ def init_node_attrs(G: "nx.Graph", *, override: bool = True) -> "nx.Graph":
 
     rng = make_rng(params.seed, -1, G)
     for _, nd in G.nodes(data=True):
+        node_attrs = cast(NodeInitAttrMap, nd)
 
         _init_phase(
-            nd,
+            node_attrs,
             rng,
             override=override,
             random_phase=params.init_rand_phase,
@@ -173,7 +175,7 @@ def init_node_attrs(G: "nx.Graph", *, override: bool = True) -> "nx.Graph":
             th_max=params.th_max,
         )
         _init_vf(
-            nd,
+            node_attrs,
             rng,
             override=override,
             mode=params.vf_mode,
@@ -186,7 +188,7 @@ def init_node_attrs(G: "nx.Graph", *, override: bool = True) -> "nx.Graph":
             clamp_to_limits=params.clamp_to_limits,
         )
         _init_si_epi(
-            nd,
+            node_attrs,
             rng,
             override=override,
             si_min=params.si_min,

tnfr/initialization.pyi

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import random
+
+import networkx as nx
+
+from .types import NodeInitAttrMap
+
+__all__: tuple[str, str] = ("InitParams", "init_node_attrs")
+
+
+@dataclass
+class InitParams:
+    seed: int | None
+    init_rand_phase: bool
+    th_min: float
+    th_max: float
+    vf_mode: str
+    vf_min_lim: float
+    vf_max_lim: float
+    vf_uniform_min: float | None
+    vf_uniform_max: float | None
+    vf_mean: float
+    vf_std: float
+    clamp_to_limits: bool
+    si_min: float
+    si_max: float
+    epi_val: float
+
+    @classmethod
+    def from_graph(cls, G: nx.Graph) -> InitParams: ...
+
+
+def _init_phase(
+    nd: NodeInitAttrMap,
+    rng: random.Random,
+    *,
+    override: bool,
+    random_phase: bool,
+    th_min: float,
+    th_max: float,
+) -> None: ...
+
+
+def _init_vf(
+    nd: NodeInitAttrMap,
+    rng: random.Random,
+    *,
+    override: bool,
+    mode: str,
+    vf_uniform_min: float,
+    vf_uniform_max: float,
+    vf_mean: float,
+    vf_std: float,
+    vf_min_lim: float,
+    vf_max_lim: float,
+    clamp_to_limits: bool,
+) -> None: ...
+
+
+def _init_si_epi(
+    nd: NodeInitAttrMap,
+    rng: random.Random,
+    *,
+    override: bool,
+    si_min: float,
+    si_max: float,
+    epi_val: float,
+) -> None: ...
+
+
+def init_node_attrs(G: nx.Graph, *, override: bool = True) -> nx.Graph: ...