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

tnfr/immutable.py

@@ -0,0 +1,178 @@
+"""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, singledispatch, wraps, partial
+from typing import Any, Callable
+from collections.abc import Mapping
+from types import MappingProxyType
+import threading
+import weakref
+
+# Types considered immutable without further inspection
+IMMUTABLE_SIMPLE = frozenset(
+    {int, float, complex, str, bool, bytes, type(None)}
+)
+
+
+@contextmanager
+def _cycle_guard(value: Any, seen: set[int] | None = None):
+    """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], Any]):
+    """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)
+
+    return wrapper
+
+
+def _freeze_dataclass(value: Any, seen: set[int]):
+    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):
+    """Recursively convert ``value`` into an immutable representation."""
+    if is_dataclass(value) and not isinstance(value, type):
+        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, seen: set[int] | None = None):  # noqa: F401
+    return tuple(_freeze(v, seen) for v in value)
+
+
+def _freeze_iterable(container: Any, tag: str, seen: set[int] | None) -> tuple[str, tuple]:
+    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]:
+    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)))
+
+
+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, seen: set[int] | None = None):  # noqa: F401
+    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:
+    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(
+    {
+        "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) -> 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) -> 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/import_utils.py

@@ -0,0 +1,228 @@
+"""Helpers for optional imports and cached access to heavy modules.
+
+This module centralises caching for optional dependencies. It exposes
+:func:`cached_import`, backed by a small :func:`functools.lru_cache`, alongside a
+light-weight registry that tracks failed imports and warnings. Use
+:func:`prune_failed_imports` or ``cached_import.cache_clear`` to reset state when
+new packages become available at runtime.
+"""
+
+from __future__ import annotations
+
+import importlib
+import warnings
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from functools import lru_cache
+from typing import Any, Callable, Literal
+import threading
+
+from .logging_utils import get_logger
+
+__all__ = (
+    "cached_import",
+    "get_numpy",
+    "get_nodonx",
+    "prune_failed_imports",
+    "IMPORT_LOG",
+)
+
+
+logger = get_logger(__name__)
+
+
+def _emit(message: str, mode: Literal["warn", "log", "both"]) -> None:
+    """Emit ``message`` via :mod:`warnings`, logger or both."""
+
+    if mode in ("warn", "both"):
+        warnings.warn(message, RuntimeWarning, stacklevel=2)
+    if mode in ("log", "both"):
+        logger.warning(message)
+
+
+EMIT_MAP: dict[str, Callable[[str], None]] = {
+    "warn": lambda msg: _emit(msg, "warn"),
+    "log": lambda msg: _emit(msg, "log"),
+    "both": lambda msg: _emit(msg, "both"),
+}
+
+
+def _format_failure_message(module: str, attr: str | None, err: Exception) -> str:
+    """Return a standardised failure message."""
+
+    return (
+        f"Failed to import module '{module}': {err}"
+        if isinstance(err, ImportError)
+        else f"Module '{module}' has no attribute '{attr}': {err}"
+    )
+
+
+_FAILED_IMPORT_LIMIT = 128
+_DEFAULT_CACHE_SIZE = 128
+
+
+@dataclass(slots=True)
+class ImportRegistry:
+    """Process-wide registry tracking failed imports and emitted warnings."""
+
+    limit: int = _FAILED_IMPORT_LIMIT
+    failed: OrderedDict[str, None] = field(default_factory=OrderedDict)
+    warned: set[str] = field(default_factory=set)
+    lock: threading.Lock = field(default_factory=threading.Lock)
+
+    def _insert(self, key: str) -> None:
+        self.failed[key] = None
+        self.failed.move_to_end(key)
+        while len(self.failed) > self.limit:
+            self.failed.popitem(last=False)
+
+    def record_failure(self, key: str, *, module: str | None = None) -> None:
+        """Record ``key`` and, optionally, ``module`` as failed imports."""
+
+        with self.lock:
+            self._insert(key)
+            if module and module != key:
+                self._insert(module)
+
+    def discard(self, key: str) -> None:
+        """Remove ``key`` from the registry and clear its warning state."""
+
+        with self.lock:
+            self.failed.pop(key, None)
+            self.warned.discard(key)
+
+    def mark_warning(self, module: str) -> bool:
+        """Mark ``module`` as warned and return ``True`` if it was new."""
+
+        with self.lock:
+            if module in self.warned:
+                return False
+            self.warned.add(module)
+            return True
+
+    def clear(self) -> None:
+        """Remove all failure records and warning markers."""
+
+        with self.lock:
+            self.failed.clear()
+            self.warned.clear()
+
+    def __contains__(self, key: str) -> bool:  # pragma: no cover - trivial
+        with self.lock:
+            return key in self.failed
+
+
+_IMPORT_STATE = ImportRegistry()
+# Public alias to ease direct introspection in tests and diagnostics.
+IMPORT_LOG = _IMPORT_STATE
+
+
+@lru_cache(maxsize=_DEFAULT_CACHE_SIZE)
+def _import_cached(module_name: str, attr: str | None) -> tuple[bool, Any]:
+    """Import ``module_name`` (and optional ``attr``) capturing failures."""
+
+    try:
+        module = importlib.import_module(module_name)
+        obj = getattr(module, attr) if attr else module
+    except (ImportError, AttributeError) as exc:
+        return False, exc
+    return True, obj
+
+
+def _warn_failure(
+    module: str,
+    attr: str | None,
+    err: Exception,
+    *,
+    emit: Literal["warn", "log", "both"] = "warn",
+) -> None:
+    """Emit a warning about a failed import."""
+
+    msg = _format_failure_message(module, attr, err)
+    if _IMPORT_STATE.mark_warning(module):
+        EMIT_MAP[emit](msg)
+    else:
+        logger.debug(msg)
+
+
+def cached_import(
+    module_name: str,
+    attr: str | None = None,
+    *,
+    fallback: Any | None = None,
+    emit: Literal["warn", "log", "both"] = "warn",
+) -> Any | None:
+    """Import ``module_name`` (and optional ``attr``) with caching and fallback.
+
+    Parameters
+    ----------
+    module_name:
+        Module to import.
+    attr:
+        Optional attribute to fetch from the module.
+    fallback:
+        Value returned when the import fails.
+    emit:
+        Destination for warnings emitted on failure (``"warn"``/``"log"``/``"both"``).
+    """
+
+    key = module_name if attr is None else f"{module_name}.{attr}"
+    success, result = _import_cached(module_name, attr)
+    if success:
+        _IMPORT_STATE.discard(key)
+        if attr is not None:
+            _IMPORT_STATE.discard(module_name)
+        return result
+    exc = result
+    include_module = isinstance(exc, ImportError)
+    _warn_failure(module_name, attr, exc, emit=emit)
+    _IMPORT_STATE.record_failure(key, module=module_name if include_module else None)
+    return fallback
+
+
+def _clear_default_cache() -> None:
+    global _NP_MISSING_LOGGED
+
+    _import_cached.cache_clear()
+    _NP_MISSING_LOGGED = False
+
+
+cached_import.cache_clear = _clear_default_cache  # type: ignore[attr-defined]
+
+
+_NP_MISSING_LOGGED = False
+
+
+def get_numpy() -> Any | None:
+    """Return the cached :mod:`numpy` module when available.
+
+    Import attempts are delegated to :func:`cached_import`, which already caches
+    successes and failures. A lightweight flag suppresses duplicate debug logs
+    when :mod:`numpy` is unavailable so callers can repeatedly probe without
+    spamming the logger.
+    """
+
+    global _NP_MISSING_LOGGED
+
+    np = cached_import("numpy")
+    if np is None:
+        if not _NP_MISSING_LOGGED:
+            logger.debug("Failed to import numpy; continuing in non-vectorised mode")
+            _NP_MISSING_LOGGED = True
+        return None
+
+    if _NP_MISSING_LOGGED:
+        _NP_MISSING_LOGGED = False
+    return np
+
+
+def get_nodonx() -> type | None:
+    """Return :class:`tnfr.node.NodoNX` using import caching."""
+
+    return cached_import("tnfr.node", "NodoNX")
+
+
+def prune_failed_imports() -> None:
+    """Clear the registry of recorded import failures and warnings."""
+
+    _IMPORT_STATE.clear()

tnfr/initialization.py

@@ -0,0 +1,197 @@
+"""Node initialization."""
+
+from __future__ import annotations
+import random
+from typing import TYPE_CHECKING
+
+from dataclasses import dataclass
+
+from .constants import VF_KEY, THETA_KEY, get_graph_param
+from .helpers.numeric import clamp
+from .rng import make_rng
+
+if TYPE_CHECKING:  # pragma: no cover
+    import networkx as nx  # type: ignore[import-untyped]
+
+__all__ = ("InitParams", "init_node_attrs")
+
+
+@dataclass
+class InitParams:
+    """Parametros de inicialización nodal."""
+
+    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":
+        """Construir ``InitParams`` desde ``G.graph``."""
+
+        return cls(
+            seed=get_graph_param(G, "RANDOM_SEED", int),
+            init_rand_phase=get_graph_param(G, "INIT_RANDOM_PHASE", bool),
+            th_min=get_graph_param(G, "INIT_THETA_MIN"),
+            th_max=get_graph_param(G, "INIT_THETA_MAX"),
+            vf_mode=str(get_graph_param(G, "INIT_VF_MODE", str)).lower(),
+            vf_min_lim=get_graph_param(G, "VF_MIN"),
+            vf_max_lim=get_graph_param(G, "VF_MAX"),
+            vf_uniform_min=get_graph_param(G, "INIT_VF_MIN"),
+            vf_uniform_max=get_graph_param(G, "INIT_VF_MAX"),
+            vf_mean=get_graph_param(G, "INIT_VF_MEAN"),
+            vf_std=get_graph_param(G, "INIT_VF_STD"),
+            clamp_to_limits=get_graph_param(
+                G, "INIT_VF_CLAMP_TO_LIMITS", bool
+            ),
+            si_min=get_graph_param(G, "INIT_SI_MIN"),
+            si_max=get_graph_param(G, "INIT_SI_MAX"),
+            epi_val=get_graph_param(G, "INIT_EPI_VALUE"),
+        )
+
+
+def _init_phase(
+    nd: dict,
+    rng: random.Random,
+    *,
+    override: bool,
+    random_phase: bool,
+    th_min: float,
+    th_max: float,
+) -> None:
+    """Initialise ``θ`` in ``nd``."""
+    if random_phase:
+        if override or THETA_KEY not in nd:
+            nd[THETA_KEY] = rng.uniform(th_min, th_max)
+    else:
+        if override:
+            nd[THETA_KEY] = 0.0
+        else:
+            nd.setdefault(THETA_KEY, 0.0)
+
+
+def _init_vf(
+    nd: dict,
+    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:
+    """Initialise ``νf`` in ``nd``."""
+    if mode == "uniform":
+        vf = rng.uniform(vf_uniform_min, vf_uniform_max)
+    elif mode == "normal":
+        for _ in range(16):
+            cand = rng.normalvariate(vf_mean, vf_std)
+            if vf_min_lim <= cand <= vf_max_lim:
+                vf = cand
+                break
+        else:
+            vf = min(
+                max(rng.normalvariate(vf_mean, vf_std), vf_min_lim),
+                vf_max_lim,
+            )
+    else:
+        vf = float(nd.get(VF_KEY, 0.5))
+    if clamp_to_limits:
+        vf = clamp(vf, vf_min_lim, vf_max_lim)
+    if override or VF_KEY not in nd:
+        nd[VF_KEY] = vf
+
+
+def _init_si_epi(
+    nd: dict,
+    rng: random.Random,
+    *,
+    override: bool,
+    si_min: float,
+    si_max: float,
+    epi_val: float,
+) -> None:
+    """Initialise ``Si`` and ``EPI`` in ``nd``."""
+    if override or "EPI" not in nd:
+        nd["EPI"] = epi_val
+
+    si = rng.uniform(si_min, si_max)
+    if override or "Si" not in nd:
+        nd["Si"] = si
+
+
+def init_node_attrs(G: "nx.Graph", *, override: bool = True) -> "nx.Graph":
+    """Initialise EPI, θ, νf and Si on the nodes of ``G``.
+
+    Parameters can be customised via ``G.graph`` entries:
+    ``RANDOM_SEED``, ``INIT_RANDOM_PHASE``, ``INIT_THETA_MIN/MAX``,
+    ``INIT_VF_MODE``, ``VF_MIN``, ``VF_MAX``, ``INIT_VF_MIN/MAX``,
+    ``INIT_VF_MEAN``, ``INIT_VF_STD`` and ``INIT_VF_CLAMP_TO_LIMITS``.
+    Ranges for ``Si`` are added via ``INIT_SI_MIN`` and ``INIT_SI_MAX``, and
+    for ``EPI`` via ``INIT_EPI_VALUE``. If ``INIT_VF_MIN`` is greater than
+    ``INIT_VF_MAX``, values are swapped and clamped to ``VF_MIN``/``VF_MAX``.
+    """
+    params = InitParams.from_graph(G)
+
+    vf_uniform_min = params.vf_uniform_min
+    vf_uniform_max = params.vf_uniform_max
+    vf_min_lim = params.vf_min_lim
+    vf_max_lim = params.vf_max_lim
+    if vf_uniform_min is None:
+        vf_uniform_min = vf_min_lim
+    if vf_uniform_max is None:
+        vf_uniform_max = vf_max_lim
+    if vf_uniform_min > vf_uniform_max:
+        vf_uniform_min, vf_uniform_max = vf_uniform_max, vf_uniform_min
+    params.vf_uniform_min = max(vf_uniform_min, vf_min_lim)
+    params.vf_uniform_max = min(vf_uniform_max, vf_max_lim)
+
+    rng = make_rng(params.seed, -1, G)
+    for _, nd in G.nodes(data=True):
+
+        _init_phase(
+            nd,
+            rng,
+            override=override,
+            random_phase=params.init_rand_phase,
+            th_min=params.th_min,
+            th_max=params.th_max,
+        )
+        _init_vf(
+            nd,
+            rng,
+            override=override,
+            mode=params.vf_mode,
+            vf_uniform_min=params.vf_uniform_min,
+            vf_uniform_max=params.vf_uniform_max,
+            vf_mean=params.vf_mean,
+            vf_std=params.vf_std,
+            vf_min_lim=params.vf_min_lim,
+            vf_max_lim=params.vf_max_lim,
+            clamp_to_limits=params.clamp_to_limits,
+        )
+        _init_si_epi(
+            nd,
+            rng,
+            override=override,
+            si_min=params.si_min,
+            si_max=params.si_max,
+            epi_val=params.epi_val,
+        )
+
+    return G