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

tnfr/utils/cache.pyi

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable, Hashable, Iterable, Iterator, Mapping, MutableMapping
+from typing import Any, ContextManager, Generic, TypeVar
+
+import networkx as nx
+
+from ..cache import CacheCapacityConfig, CacheManager
+from ..types import GraphLike, NodeId, TNFRGraph, TimingContext
+
+K = TypeVar("K", bound=Hashable)
+V = TypeVar("V")
+T = TypeVar("T")
+
+__all__ = (
+    "EdgeCacheManager",
+    "NODE_SET_CHECKSUM_KEY",
+    "cached_node_list",
+    "cached_nodes_and_A",
+    "clear_node_repr_cache",
+    "configure_graph_cache_limits",
+    "edge_version_cache",
+    "edge_version_update",
+    "ensure_node_index_map",
+    "ensure_node_offset_map",
+    "get_graph_version",
+    "increment_edge_version",
+    "increment_graph_version",
+    "node_set_checksum",
+    "stable_json",
+)
+
+NODE_SET_CHECKSUM_KEY: str
+
+
+class LRUCache(MutableMapping[K, V], Generic[K, V]):
+    def __init__(self, maxsize: int = ...) -> None: ...
+
+    def __getitem__(self, __key: K) -> V: ...
+
+    def __setitem__(self, __key: K, __value: V) -> None: ...
+
+    def __delitem__(self, __key: K) -> None: ...
+
+    def __iter__(self) -> Iterator[K]: ...
+
+    def __len__(self) -> int: ...
+
+
+class EdgeCacheState:
+    cache: MutableMapping[Hashable, Any]
+    locks: MutableMapping[Hashable, threading.RLock]
+    max_entries: int | None
+
+
+class EdgeCacheManager:
+    _STATE_KEY: str
+
+    def __init__(self, graph: MutableMapping[str, Any]) -> None: ...
+
+    def record_hit(self) -> None: ...
+
+    def record_miss(self, *, track_metrics: bool = ...) -> None: ...
+
+    def record_eviction(self, *, track_metrics: bool = ...) -> None: ...
+
+    def timer(self) -> TimingContext: ...
+
+    def _default_state(self) -> EdgeCacheState: ...
+
+    def resolve_max_entries(self, max_entries: int | None | object) -> int | None: ...
+
+    def _build_state(self, max_entries: int | None) -> EdgeCacheState: ...
+
+    def _ensure_state(
+        self, state: EdgeCacheState | None, max_entries: int | None | object
+    ) -> EdgeCacheState: ...
+
+    def _reset_state(self, state: EdgeCacheState | None) -> EdgeCacheState: ...
+
+    def get_cache(
+        self,
+        max_entries: int | None | object,
+        *,
+        create: bool = ...,
+    ) -> tuple[
+        MutableMapping[Hashable, Any] | None,
+        MutableMapping[Hashable, threading.RLock] | None,
+    ]: ...
+
+    def clear(self) -> None: ...
+
+
+def get_graph_version(graph: Any, key: str, default: int = ...) -> int: ...
+
+
+def increment_graph_version(graph: Any, key: str) -> int: ...
+
+
+def stable_json(obj: Any) -> str: ...
+
+
+def clear_node_repr_cache() -> None: ...
+
+
+def node_set_checksum(
+    G: nx.Graph,
+    nodes: Iterable[Any] | None = ...,
+    *,
+    presorted: bool = ...,
+    store: bool = ...,
+) -> str: ...
+
+
+def cached_node_list(G: nx.Graph) -> tuple[Any, ...]: ...
+
+
+def ensure_node_index_map(G: TNFRGraph) -> dict[NodeId, int]: ...
+
+
+def ensure_node_offset_map(G: TNFRGraph) -> dict[NodeId, int]: ...
+
+
+def configure_graph_cache_limits(
+    G: GraphLike | TNFRGraph | MutableMapping[str, Any],
+    *,
+    default_capacity: int | None | object = CacheManager._MISSING,
+    overrides: Mapping[str, int | None] | None = ...,
+    replace_overrides: bool = ...,
+) -> CacheCapacityConfig: ...
+
+
+def increment_edge_version(G: Any) -> None: ...
+
+
+def edge_version_cache(
+    G: Any,
+    key: Hashable,
+    builder: Callable[[], T],
+    *,
+    max_entries: int | None | object = CacheManager._MISSING,
+) -> T: ...
+
+
+def cached_nodes_and_A(
+    G: nx.Graph,
+    *,
+    cache_size: int | None = ...,
+    require_numpy: bool = ...,
+    prefer_sparse: bool = ...,
+    nodes: tuple[Any, ...] | None = ...,
+) -> tuple[tuple[Any, ...], Any]: ...
+
+
+def edge_version_update(G: TNFRGraph) -> ContextManager[None]: ...

tnfr/utils/data.py

@@ -0,0 +1,267 @@
+"""Utilities for manipulating collections and scalar values within TNFR."""
+
+from __future__ import annotations
+
+import logging
+from collections import deque
+from collections.abc import Collection, Iterable, Mapping, Sequence
+from itertools import islice
+from typing import Any, Callable, Iterator, TypeVar, cast
+
+from ..helpers.numeric import kahan_sum_nd
+from .init import get_logger, warn_once as _warn_once_factory
+
+T = TypeVar("T")
+
+_collections_logger = get_logger("tnfr.utils.data.collections")
+_value_logger = get_logger("tnfr.utils.data")
+
+STRING_TYPES = (str, bytes, bytearray)
+
+NEGATIVE_WEIGHTS_MSG = "Negative weights detected: %s"
+
+_MAX_NEGATIVE_WARN_ONCE = 1024
+
+__all__ = (
+    "convert_value",
+    "MAX_MATERIALIZE_DEFAULT",
+    "normalize_materialize_limit",
+    "is_non_string_sequence",
+    "flatten_structure",
+    "STRING_TYPES",
+    "ensure_collection",
+    "normalize_weights",
+    "negative_weights_warn_once",
+    "normalize_counter",
+    "mix_groups",
+)
+
+
+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."""
+
+    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:
+            _value_logger.log(level, "Could not convert value for %r: %s", key, exc)
+        else:
+            _value_logger.log(level, "Could not convert value: %s", exc)
+        return False, None
+
+
+def negative_weights_warn_once(
+    *, maxsize: int = _MAX_NEGATIVE_WARN_ONCE
+) -> Callable[[Mapping[str, float]], None]:
+    """Return a ``WarnOnce`` callable for negative weight warnings."""
+
+    return _warn_once_factory(_collections_logger, NEGATIVE_WEIGHTS_MSG, maxsize=maxsize)
+
+
+def _log_negative_weights(negatives: Mapping[str, float]) -> None:
+    """Log negative weight warnings without deduplicating keys."""
+
+    _collections_logger.warning(NEGATIVE_WEIGHTS_MSG, negatives)
+
+
+def _resolve_negative_warn_handler(
+    warn_once: bool | Callable[[Mapping[str, float]], None]
+) -> Callable[[Mapping[str, float]], None]:
+    """Return a callable that logs negative weight warnings."""
+
+    if callable(warn_once):
+        return warn_once
+    if warn_once:
+        return negative_weights_warn_once()
+    return _log_negative_weights
+
+
+def is_non_string_sequence(obj: Any) -> bool:
+    """Return ``True`` if ``obj`` is an ``Iterable`` but not string-like or a mapping."""
+
+    return isinstance(obj, Iterable) and not isinstance(obj, (*STRING_TYPES, Mapping))
+
+
+def flatten_structure(
+    obj: Any,
+    *,
+    expand: Callable[[Any], Iterable[Any] | None] | None = None,
+) -> Iterator[Any]:
+    """Yield leaf items from ``obj`` following breadth-first semantics."""
+
+    stack = deque([obj])
+    seen: set[int] = set()
+    while stack:
+        item = stack.pop()
+        item_id = id(item)
+        if item_id in seen:
+            continue
+        if expand is not None:
+            replacement = expand(item)
+            if replacement is not None:
+                seen.add(item_id)
+                stack.extendleft(replacement)
+                continue
+        if is_non_string_sequence(item):
+            seen.add(item_id)
+            stack.extendleft(item)
+        else:
+            yield item
+
+
+MAX_MATERIALIZE_DEFAULT: int = 1000
+"""Default materialization limit used by :func:`ensure_collection`."""
+
+
+def normalize_materialize_limit(max_materialize: int | None) -> int | None:
+    """Normalize and validate ``max_materialize`` returning a usable limit."""
+
+    if max_materialize is None:
+        return None
+    limit = int(max_materialize)
+    if limit < 0:
+        raise ValueError("'max_materialize' must be non-negative")
+    return limit
+
+
+def ensure_collection(
+    it: Iterable[T],
+    *,
+    max_materialize: int | None = MAX_MATERIALIZE_DEFAULT,
+    error_msg: str | None = None,
+) -> Collection[T]:
+    """Return ``it`` as a :class:`Collection`, materializing when needed."""
+
+    if isinstance(it, Collection):
+        if isinstance(it, STRING_TYPES):
+            return (cast(T, it),)
+        else:
+            return it
+
+    if not isinstance(it, Iterable):
+        raise TypeError(f"{it!r} is not iterable")
+
+    limit = normalize_materialize_limit(max_materialize)
+    if limit is None:
+        return tuple(it)
+    if limit == 0:
+        return ()
+
+    items = tuple(islice(it, limit + 1))
+    if len(items) > limit:
+        examples = ", ".join(repr(x) for x in items[:3])
+        msg = error_msg or (
+            f"Iterable produced {len(items)} items, exceeds limit {limit}; first items: [{examples}]"
+        )
+        raise ValueError(msg)
+    return items
+
+
+def _convert_and_validate_weights(
+    dict_like: Mapping[str, Any],
+    keys: Iterable[str] | Sequence[str],
+    default: float,
+    *,
+    error_on_conversion: bool,
+    error_on_negative: bool,
+    warn_once: bool | Callable[[Mapping[str, float]], None],
+) -> tuple[dict[str, float], list[str], float]:
+    """Return converted weights, deduplicated keys and the accumulated total."""
+
+    keys_list = list(dict.fromkeys(keys))
+    default_float = float(default)
+
+    def convert(k: str) -> float:
+        ok, val = convert_value(
+            dict_like.get(k, default_float),
+            float,
+            strict=error_on_conversion,
+            key=k,
+            log_level=logging.WARNING,
+        )
+        return cast(float, val) if ok else default_float
+
+    weights = {k: convert(k) for k in keys_list}
+    negatives = {k: w for k, w in weights.items() if w < 0}
+    total = kahan_sum_nd(((w,) for w in weights.values()), dims=1)[0]
+
+    if negatives:
+        if error_on_negative:
+            raise ValueError(NEGATIVE_WEIGHTS_MSG % negatives)
+        warn_negative = _resolve_negative_warn_handler(warn_once)
+        warn_negative(negatives)
+        for key, weight in negatives.items():
+            weights[key] = 0.0
+            total -= weight
+
+    return weights, keys_list, total
+
+
+def normalize_weights(
+    dict_like: Mapping[str, Any],
+    keys: Iterable[str] | Sequence[str],
+    default: float = 0.0,
+    *,
+    error_on_negative: bool = False,
+    warn_once: bool | Callable[[Mapping[str, float]], None] = True,
+    error_on_conversion: bool = False,
+) -> dict[str, float]:
+    """Normalize ``keys`` in mapping ``dict_like`` so their sum is 1."""
+
+    weights, keys_list, total = _convert_and_validate_weights(
+        dict_like,
+        keys,
+        default,
+        error_on_conversion=error_on_conversion,
+        error_on_negative=error_on_negative,
+        warn_once=warn_once,
+    )
+    if not keys_list:
+        return {}
+    if total <= 0:
+        uniform = 1.0 / len(keys_list)
+        return {k: uniform for k in keys_list}
+    return {k: w / total for k, w in weights.items()}
+
+
+def normalize_counter(
+    counts: Mapping[str, float | int],
+) -> tuple[dict[str, float], float]:
+    """Normalize a ``Counter`` returning proportions and total."""
+
+    total = kahan_sum_nd(((c,) for c in counts.values()), dims=1)[0]
+    if total <= 0:
+        return {}, 0
+    dist = {k: v / total for k, v in counts.items() if v}
+    return dist, total
+
+
+def mix_groups(
+    dist: Mapping[str, float],
+    groups: Mapping[str, Iterable[str]],
+    *,
+    prefix: str = "_",
+) -> dict[str, float]:
+    """Aggregate values of ``dist`` according to ``groups``."""
+
+    out: dict[str, float] = dict(dist)
+    out.update(
+        {
+            f"{prefix}{label}": kahan_sum_nd(
+                ((dist.get(k, 0.0),) for k in keys),
+                dims=1,
+            )[0]
+            for label, keys in groups.items()
+        }
+    )
+    return out

tnfr/utils/data.pyi

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from collections.abc import Collection, Iterable, Iterator, Mapping, Sequence
+from typing import Any, Callable, TypeVar
+
+T = TypeVar("T")
+
+STRING_TYPES: tuple[type[str] | type[bytes] | type[bytearray], ...]
+MAX_MATERIALIZE_DEFAULT: int
+NEGATIVE_WEIGHTS_MSG: str
+
+__all__: tuple[str, ...]
+
+
+def convert_value(
+    value: Any,
+    conv: Callable[[Any], T],
+    *,
+    strict: bool = ...,
+    key: str | None = ...,
+    log_level: int | None = ...,
+) -> tuple[bool, T | None]: ...
+
+
+def negative_weights_warn_once(
+    *,
+    maxsize: int = ...,
+) -> Callable[[Mapping[str, float]], None]: ...
+
+
+def is_non_string_sequence(obj: Any) -> bool: ...
+
+
+def flatten_structure(
+    obj: Any,
+    *,
+    expand: Callable[[Any], Iterable[Any] | None] | None = ...,
+) -> Iterator[Any]: ...
+
+
+def normalize_materialize_limit(max_materialize: int | None) -> int | None: ...
+
+
+def ensure_collection(
+    it: Iterable[T],
+    *,
+    max_materialize: int | None = ...,
+    error_msg: str | None = ...,
+) -> Collection[T]: ...
+
+
+def normalize_weights(
+    dict_like: Mapping[str, Any],
+    keys: Iterable[str] | Sequence[str],
+    default: float = ...,
+    *,
+    error_on_negative: bool = ...,
+    warn_once: bool | Callable[[Mapping[str, float]], None] = ...,
+    error_on_conversion: bool = ...,
+) -> dict[str, float]: ...
+
+
+def normalize_counter(
+    counts: Mapping[str, float | int],
+) -> tuple[dict[str, float], float]: ...
+
+
+def mix_groups(
+    dist: Mapping[str, float],
+    groups: Mapping[str, Iterable[str]],
+    *,
+    prefix: str = ...,
+) -> dict[str, float]: ...

tnfr/utils/graph.py

@@ -0,0 +1,87 @@
+"""Utilities for graph-level bookkeeping shared by TNFR components."""
+
+from __future__ import annotations
+
+import warnings
+from types import MappingProxyType
+from typing import Any, Mapping, MutableMapping
+
+from ..types import GraphLike, TNFRGraph
+
+__all__ = (
+    "get_graph",
+    "get_graph_mapping",
+    "mark_dnfr_prep_dirty",
+    "supports_add_edge",
+    "GraphLike",
+)
+
+
+def get_graph(
+    obj: GraphLike | TNFRGraph | MutableMapping[str, Any]
+) -> MutableMapping[str, Any]:
+    """Return the graph-level metadata mapping for ``obj``.
+
+    ``obj`` must be a :class:`~tnfr.types.TNFRGraph` instance or fulfil the
+    :class:`~tnfr.types.GraphLike` protocol. The function normalises access to
+    the ``graph`` attribute exposed by ``networkx``-style graphs and wrappers,
+    always returning the underlying metadata mapping. A pre-extracted mapping
+    is also accepted for legacy call sites.
+    """
+
+    graph = getattr(obj, "graph", None)
+    if graph is not None:
+        return graph
+    if isinstance(obj, MutableMapping):
+        return obj
+    raise TypeError("Unsupported graph object: metadata mapping not accessible")
+
+
+def get_graph_mapping(
+    G: GraphLike | TNFRGraph | MutableMapping[str, Any], key: str, warn_msg: str
+) -> Mapping[str, Any] | None:
+    """Return an immutable view of ``G``'s stored mapping for ``key``.
+
+    The ``G`` argument follows the :class:`~tnfr.types.GraphLike` protocol, is
+    a concrete :class:`~tnfr.types.TNFRGraph` or provides the metadata mapping
+    directly. The helper validates that the stored value is a mapping before
+    returning a read-only proxy.
+    """
+
+    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: GraphLike | TNFRGraph | MutableMapping[str, Any]
+) -> None:
+    """Flag ΔNFR preparation data as stale by marking ``G.graph``.
+
+    ``G`` is constrained to the :class:`~tnfr.types.GraphLike` protocol, a
+    concrete :class:`~tnfr.types.TNFRGraph` or an explicit metadata mapping,
+    ensuring the metadata storage is available for mutation.
+    """
+
+    graph = get_graph(G)
+    graph["_dnfr_prep_dirty"] = True
+
+
+def supports_add_edge(graph: GraphLike | TNFRGraph) -> bool:
+    """Return ``True`` if ``graph`` exposes an ``add_edge`` method.
+
+    The ``graph`` parameter must implement :class:`~tnfr.types.GraphLike` or be
+    a :class:`~tnfr.types.TNFRGraph`, aligning runtime expectations with the
+    type contract enforced throughout the engine.
+    """
+
+    return hasattr(graph, "add_edge")

tnfr/utils/graph.pyi

@@ -0,0 +1,10 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+get_graph: Any
+get_graph_mapping: Any
+mark_dnfr_prep_dirty: Any
+supports_add_edge: Any