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

tnfr/{collections_utils.py → utils/data.py}

@@ -1,50 +1,171 @@
-"""Utilities for working with generic collections and weight mappings."""
+"""Utilities for manipulating collections and scalar values within TNFR."""
 
 from __future__ import annotations
 
 import logging
+import math
 from collections import deque
 from collections.abc import Collection, Iterable, Mapping, Sequence
+from numbers import Real
 from itertools import islice
 from typing import Any, Callable, Iterator, TypeVar, cast
 
-from .logging_utils import get_logger
-from .logging_utils import warn_once as _warn_once_factory
-from .value_utils import convert_value
-from .helpers.numeric import kahan_sum_nd
+from .numeric import kahan_sum_nd
+from .init import get_logger
+from .init import warn_once as _warn_once_factory
 
 T = TypeVar("T")
 
-logger = get_logger(__name__)
+_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"
 
-_NEGATIVE_WARN_ONCE_MAXSIZE = 1024
+_MAX_NEGATIVE_WARN_ONCE = 1024
 
+__all__ = (
+    "convert_value",
+    "normalize_optional_int",
+    "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 negative_weights_warn_once(
-    *, maxsize: int = _NEGATIVE_WARN_ONCE_MAXSIZE
-) -> Callable[[Mapping[str, float]], None]:
-    """Return a ``WarnOnce`` callable for negative weight warnings.
 
-    The returned callable may be reused across multiple
-    :func:`normalize_weights` invocations to suppress duplicate warnings for
-    the same keys.
+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:
+        converted = 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
+    if isinstance(converted, float) and not math.isfinite(converted):
+        if strict:
+            target = f"{key!r}" if key is not None else "value"
+            raise ValueError(f"Non-finite value {converted!r} for {target}")
+        level = log_level if log_level is not None else logging.DEBUG
+        if key is not None:
+            _value_logger.log(level, "Non-finite value for %r: %s", key, converted)
+        else:
+            _value_logger.log(level, "Non-finite value: %s", converted)
+        return False, None
+    return True, converted
+
+
+_DEFAULT_SENTINELS = frozenset({"auto", "none", "null"})
+
+
+def normalize_optional_int(
+    value: Any,
+    *,
+    sentinels: Collection[str] | None = _DEFAULT_SENTINELS,
+    allow_non_positive: bool = True,
+    strict: bool = False,
+    error_message: str | None = None,
+) -> int | None:
+    """Normalise optional integers shared by CLI and runtime helpers.
+
+    Parameters
+    ----------
+    value:
+        Arbitrary object obtained from configuration, CLI options or graph
+        metadata.
+    sentinels:
+        Collection of case-insensitive strings that should be interpreted as
+        ``None``. When ``None`` or empty, no sentinel mapping is applied.
+    allow_non_positive:
+        When ``False`` values ``<= 0`` are rejected and converted to ``None``.
+    strict:
+        When ``True`` invalid inputs raise :class:`ValueError` instead of
+        returning ``None``.
+    error_message:
+        Optional message used when ``strict`` mode raises due to invalid input
+        or disallowed non-positive values.
     """
 
-    return _warn_once_factory(logger, NEGATIVE_WEIGHTS_MSG, maxsize=maxsize)
+    if value is None:
+        return None
+
+    if isinstance(value, int):
+        result = value
+    elif isinstance(value, Real):
+        result = int(value)
+    else:
+        text = str(value).strip()
+        if not text:
+            if strict:
+                raise ValueError(
+                    error_message
+                    or "Empty value is not allowed for configuration options."
+                )
+            return None
+        sentinel_set: set[str] | None = None
+        if sentinels:
+            sentinel_set = {s.lower() for s in sentinels}
+            lowered = text.lower()
+            if lowered in sentinel_set:
+                return None
+        try:
+            result = int(text)
+        except (TypeError, ValueError) as exc:
+            if strict:
+                raise ValueError(
+                    error_message or f"Invalid integer value: {value!r}"
+                ) from exc
+            return None
+
+    if not allow_non_positive and result <= 0:
+        if strict:
+            raise ValueError(
+                error_message
+                or "Non-positive values are not permitted for this option."
+            )
+        return None
+
+    return result
+
+
+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."""
 
-    logger.warning(NEGATIVE_WEIGHTS_MSG, negatives)
+    _collections_logger.warning(NEGATIVE_WEIGHTS_MSG, negatives)
 
 
 def _resolve_negative_warn_handler(
-    warn_once: bool | Callable[[Mapping[str, float]], None]
+    warn_once: bool | Callable[[Mapping[str, float]], None],
 ) -> Callable[[Mapping[str, float]], None]:
     """Return a callable that logs negative weight warnings."""
 
@@ -57,6 +178,7 @@ def _resolve_negative_warn_handler(
 
 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))
 
 
@@ -65,20 +187,7 @@ def flatten_structure(
     *,
     expand: Callable[[Any], Iterable[Any] | None] | None = None,
 ) -> Iterator[Any]:
-    """Yield leaf items from ``obj``.
-
-    The order of yielded items follows the order of the input iterable when it
-    is defined. For unordered iterables like :class:`set` the resulting order is
-    arbitrary. Mappings are treated as atomic items and not expanded.
-
-    Parameters
-    ----------
-    obj:
-        Object that may contain nested iterables.
-    expand:
-        Optional callable returning a replacement iterable for ``item``. When
-        it returns ``None`` the ``item`` is processed normally.
-    """
+    """Yield leaf items from ``obj`` following breadth-first semantics."""
 
     stack = deque([obj])
     seen: set[int] = set()
@@ -100,30 +209,13 @@ def flatten_structure(
             yield item
 
 
-__all__ = (
-    "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",
-)
-
 MAX_MATERIALIZE_DEFAULT: int = 1000
-"""Default materialization limit used by :func:`ensure_collection`.
-
-This guard prevents accidentally consuming huge or infinite iterables when a
-limit is not explicitly provided. Pass ``max_materialize=None`` to disable the
-limit.
-"""
+"""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)
@@ -138,34 +230,17 @@ def ensure_collection(
     max_materialize: int | None = MAX_MATERIALIZE_DEFAULT,
     error_msg: str | None = None,
 ) -> Collection[T]:
-    """Return ``it`` as a :class:`Collection`, materializing when needed.
-
-    Checks are executed in the following order:
-
-    1. Existing collections are returned directly. String-like inputs
-       (``str``, ``bytes`` and ``bytearray``) are wrapped as a single item
-       tuple.
-    2. The object must be an :class:`Iterable`; otherwise ``TypeError`` is
-       raised.
-    3. Remaining iterables are materialized up to ``max_materialize`` items.
-       ``None`` disables the limit. ``error_msg`` customizes the
-       :class:`ValueError` raised when the iterable yields more items than
-       allowed. The input is consumed at most once and no extra items beyond the
-       limit are stored in memory.
-    """
+    """Return ``it`` as a :class:`Collection`, materializing when needed."""
 
-    # Step 1: early-return for collections and raw strings/bytes
     if isinstance(it, Collection):
         if isinstance(it, STRING_TYPES):
             return (cast(T, it),)
         else:
             return it
 
-    # Step 2: ensure the input is iterable
     if not isinstance(it, Iterable):
         raise TypeError(f"{it!r} is not iterable")
 
-    # Step 3: validate limit and materialize items once
     limit = normalize_materialize_limit(max_materialize)
     if limit is None:
         return tuple(it)
@@ -231,28 +306,8 @@ def normalize_weights(
     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.
-
-    ``keys`` may be any iterable of strings and is materialized once while
-    collapsing repeated entries preserving their first occurrence.
-
-    Negative weights are handled according to ``error_on_negative``. When
-    ``True`` a :class:`ValueError` is raised. Otherwise negatives are logged,
-    replaced with ``0`` and the remaining weights are renormalized. If all
-    weights are non-positive a uniform distribution is returned.
-
-    Conversion errors are controlled separately by ``error_on_conversion``. When
-    ``True`` any :class:`TypeError` or :class:`ValueError` while converting a
-    value to ``float`` is propagated. Otherwise the error is logged and the
-    ``default`` value is used.
-
-    ``warn_once`` accepts either a boolean or a callable. ``False`` logs all
-    negative weights using :func:`logging.Logger.warning`. ``True`` (the
-    default) creates a fresh :class:`~tnfr.logging_utils.WarnOnce` instance for
-    the call, emitting a single warning containing all negative keys. To reuse
-    deduplication state across calls, pass a callable such as
-    :func:`negative_weights_warn_once`.
-    """
+    """Normalize ``keys`` in mapping ``dict_like`` so their sum is 1."""
+
     weights, keys_list, total = _convert_and_validate_weights(
         dict_like,
         keys,
@@ -273,6 +328,7 @@ 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
@@ -287,6 +343,7 @@ def mix_groups(
     prefix: str = "_",
 ) -> dict[str, float]:
     """Aggregate values of ``dist`` according to ``groups``."""
+
     out: dict[str, float] = dict(dist)
     out.update(
         {

tnfr/utils/data.pyi

@@ -0,0 +1,64 @@
+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 normalize_optional_int(
+    value: Any,
+    *,
+    sentinels: Collection[str] | None = ...,
+    allow_non_positive: bool = ...,
+    strict: bool = ...,
+    error_message: str | None = ...,
+) -> int | 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,85 @@
+"""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