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

tnfr/graph_utils.py

@@ -1,84 +0,0 @@
-"""Utilities for graph-level bookkeeping.
-
-This module centralises helpers that operate on the metadata stored inside
-graph objects.  Besides flagging ΔNFR preparation caches it also exposes
-lightweight adapters to obtain the canonical ``graph`` mapping and to read
-validated configuration dictionaries.
-"""
-
-from __future__ import annotations
-
-import warnings
-from types import MappingProxyType
-from typing import Any, Mapping
-
-__all__ = (
-    "get_graph",
-    "get_graph_mapping",
-    "mark_dnfr_prep_dirty",
-    "supports_add_edge",
-)
-
-
-def get_graph(obj: Any) -> Any:
-    """Return ``obj.graph`` when present or ``obj`` otherwise."""
-    return getattr(obj, "graph", obj)
-
-
-def get_graph_mapping(
-    G: Any, key: str, warn_msg: str
-) -> Mapping[str, Any] | None:
-    """Return an immutable view of ``G``'s stored mapping for ``key``.
-
-    The helper normalises access to ``G.graph[key]`` by returning
-    ``None`` when the key is missing or holds a non-mapping value.  When a
-    mapping is found it is wrapped in :class:`types.MappingProxyType` to guard
-    against accidental mutation.  ``warn_msg`` is emitted via
-    :func:`warnings.warn` when the stored value is not a mapping.
-    """
-    graph = get_graph(G)
-    getter = getattr(graph, "get", None)
-    if getter is None:
-        return None
-
-    data = getter(key)
-    if data is None:
-        return None
-    if not isinstance(data, Mapping):
-        warnings.warn(warn_msg, UserWarning, stacklevel=2)
-        return None
-    return MappingProxyType(data)
-
-
-def mark_dnfr_prep_dirty(G: Any) -> None:
-    """Flag ΔNFR preparation data as stale.
-
-    Parameters
-    ----------
-    G : Any
-        Graph-like object whose ``graph`` attribute will receive the
-        ``"_dnfr_prep_dirty"`` flag.
-
-    Returns
-    -------
-    None
-        This function mutates ``G`` in place.
-    """
-    graph = get_graph(G)
-    graph["_dnfr_prep_dirty"] = True
-
-
-def supports_add_edge(graph: Any) -> bool:
-    """Return ``True`` if ``graph`` exposes an ``add_edge`` method.
-
-    Parameters
-    ----------
-    graph : Any
-        Object representing a graph.
-
-    Returns
-    -------
-    bool
-        ``True`` when ``graph`` implements ``add_edge``; ``False`` otherwise.
-    """
-    return hasattr(graph, "add_edge")

tnfr/import_utils.py

@@ -1,228 +0,0 @@
-"""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/logging_utils.py

@@ -1,116 +0,0 @@
-"""Logging utilities for TNFR.
-
-Centralises creation of module-specific loggers so that all TNFR
-modules share a consistent configuration.
-"""
-
-from __future__ import annotations
-
-import logging
-import threading
-from typing import Any, Hashable, Mapping
-
-__all__ = ("_configure_root", "get_logger", "WarnOnce", "warn_once")
-
-_LOGGING_CONFIGURED = False
-
-
-def _configure_root() -> None:
-    """Ensure the root logger has handlers and a default format."""
-
-    global _LOGGING_CONFIGURED
-    if _LOGGING_CONFIGURED:
-        return
-
-    root = logging.getLogger()
-    if not root.handlers:
-        kwargs = {"format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"}
-        if root.level == logging.NOTSET:
-            kwargs["level"] = logging.INFO
-        logging.basicConfig(**kwargs)
-
-    _LOGGING_CONFIGURED = True
-
-
-def get_logger(name: str) -> logging.Logger:
-    """Return a module-specific logger."""
-    _configure_root()
-    return logging.getLogger(name)
-
-
-class WarnOnce:
-    """Log a warning only once for each unique key.
-
-    ``WarnOnce`` tracks seen keys in a bounded :class:`set`. When ``maxsize`` is
-    reached an arbitrary key is evicted to keep memory usage stable; ordered
-    eviction is intentionally avoided to keep the implementation lightweight.
-    Instances are callable and accept either a mapping of keys to values or a
-    single key/value pair. Passing ``maxsize <= 0`` disables caching and logs on
-    every invocation.
-    """
-
-    def __init__(self, logger: logging.Logger, msg: str, *, maxsize: int = 1024) -> None:
-        self._logger = logger
-        self._msg = msg
-        self._maxsize = maxsize
-        self._seen: set[Hashable] = set()
-        self._lock = threading.Lock()
-
-    def _mark_seen(self, key: Hashable) -> bool:
-        """Return ``True`` when ``key`` has not been seen before."""
-
-        if self._maxsize <= 0:
-            # Caching disabled – always log.
-            return True
-        if key in self._seen:
-            return False
-        if len(self._seen) >= self._maxsize:
-            # ``set.pop()`` removes an arbitrary element which is acceptable for
-            # this lightweight cache.
-            self._seen.pop()
-        self._seen.add(key)
-        return True
-
-    def __call__(
-        self,
-        data: Mapping[Hashable, Any] | Hashable,
-        value: Any | None = None,
-    ) -> None:
-        """Log new keys found in ``data``.
-
-        ``data`` may be a mapping of keys to payloads or a single key. When
-        called with a single key ``value`` customises the payload passed to the
-        logging message; the key itself is used when ``value`` is omitted.
-        """
-
-        if isinstance(data, Mapping):
-            new_items: dict[Hashable, Any] = {}
-            with self._lock:
-                for key, item_value in data.items():
-                    if self._mark_seen(key):
-                        new_items[key] = item_value
-            if new_items:
-                self._logger.warning(self._msg, new_items)
-            return
-
-        key = data
-        payload = value if value is not None else data
-        with self._lock:
-            should_log = self._mark_seen(key)
-        if should_log:
-            self._logger.warning(self._msg, payload)
-
-    def clear(self) -> None:
-        """Reset tracked keys."""
-        with self._lock:
-            self._seen.clear()
-
-
-def warn_once(
-    logger: logging.Logger,
-    msg: str,
-    *,
-    maxsize: int = 1024,
-) -> WarnOnce:
-    """Return a :class:`WarnOnce` logger."""
-    return WarnOnce(logger, msg, maxsize=maxsize)

tnfr/validators.py

@@ -1,84 +0,0 @@
-"""Validation utilities."""
-
-from __future__ import annotations
-
-import numbers
-import sys
-
-from .constants import get_aliases, get_param
-from .alias import get_attr
-from .sense import sigma_vector_from_graph
-from .helpers.numeric import within_range
-from .constants_glyphs import GLYPHS_CANONICAL_SET
-
-ALIAS_EPI = get_aliases("EPI")
-ALIAS_VF = get_aliases("VF")
-
-__all__ = ("validate_window", "run_validators")
-
-
-def validate_window(window: int, *, positive: bool = False) -> int:
-    """Validate ``window`` as an ``int`` and return it.
-
-    Non-integer values raise :class:`TypeError`. When ``positive`` is ``True``
-    the value must be strictly greater than zero; otherwise it may be zero.
-    Negative values always raise :class:`ValueError`.
-    """
-
-    if isinstance(window, bool) or not isinstance(window, numbers.Integral):
-        raise TypeError("'window' must be an integer")
-    if window < 0 or (positive and window == 0):
-        kind = "positive" if positive else "non-negative"
-        raise ValueError(f"'window'={window} must be {kind}")
-    return int(window)
-
-
-def _require_attr(data, alias, node, name):
-    """Return attribute value or raise if missing."""
-    val = get_attr(data, alias, None)
-    if val is None:
-        raise ValueError(f"Missing {name} attribute in node {node}")
-    return val
-
-
-def _validate_sigma(G) -> None:
-    sv = sigma_vector_from_graph(G)
-    if sv.get("mag", 0.0) > 1.0 + sys.float_info.epsilon:
-        raise ValueError("σ norm exceeds 1")
-
-
-def _check_epi_vf(epi, vf, epi_min, epi_max, vf_min, vf_max, n):
-    _check_range(epi, epi_min, epi_max, "EPI", n)
-    _check_range(vf, vf_min, vf_max, "VF", n)
-
-
-def _out_of_range_msg(name, node, val):
-    return f"{name} out of range in node {node}: {val}"
-
-
-def _check_range(val, lower, upper, name, node, tol: float = 1e-9):
-    if not within_range(val, lower, upper, tol):
-        raise ValueError(_out_of_range_msg(name, node, val))
-
-
-def _check_glyph(g, n):
-    if g and g not in GLYPHS_CANONICAL_SET:
-        raise KeyError(f"Invalid glyph {g} in node {n}")
-
-
-def run_validators(G) -> None:
-    """Run all invariant validators on ``G`` with a single node pass."""
-    from .glyph_history import last_glyph
-
-    epi_min = float(get_param(G, "EPI_MIN"))
-    epi_max = float(get_param(G, "EPI_MAX"))
-    vf_min = float(get_param(G, "VF_MIN"))
-    vf_max = float(get_param(G, "VF_MAX"))
-
-    for n, data in G.nodes(data=True):
-        epi = _require_attr(data, ALIAS_EPI, n, "EPI")
-        vf = _require_attr(data, ALIAS_VF, n, "VF")
-        _check_epi_vf(epi, vf, epi_min, epi_max, vf_min, vf_max, n)
-        _check_glyph(last_glyph(data), n)
-
-    _validate_sigma(G)

tnfr/value_utils.py

@@ -1,59 +0,0 @@
-"""Conversion helpers with logging for value normalisation.
-
-Wraps conversion callables to standardise error handling and logging.
-"""
-
-from __future__ import annotations
-
-from typing import Any, Callable, TypeVar
-import logging
-from .logging_utils import get_logger
-
-T = TypeVar("T")
-
-logger = get_logger(__name__)
-
-__all__ = ("convert_value",)
-
-
-def convert_value(
-    value: Any,
-    conv: Callable[[Any], T],
-    *,
-    strict: bool = False,
-    key: str | None = None,
-    log_level: int | None = None,
-) -> tuple[bool, T | None]:
-    """Attempt to convert a value and report failures.
-
-    Parameters
-    ----------
-    value : Any
-        Input value to convert.
-    conv : Callable[[Any], T]
-        Callable performing the conversion.
-    strict : bool, optional
-        Raise exceptions directly instead of logging them. Defaults to ``False``.
-    key : str, optional
-        Name associated with the value for logging context.
-    log_level : int, optional
-        Logging level used when reporting failures. Defaults to
-        ``logging.DEBUG``.
-
-    Returns
-    -------
-    tuple[bool, T | None]
-        ``(True, result)`` on success or ``(False, None)`` when conversion
-        fails.
-    """
-    try:
-        return True, conv(value)
-    except (ValueError, TypeError) as exc:
-        if strict:
-            raise
-        level = log_level if log_level is not None else logging.DEBUG
-        if key is not None:
-            logger.log(level, "Could not convert value for %r: %s", key, exc)
-        else:
-            logger.log(level, "Could not convert value: %s", exc)
-        return False, None