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

tnfr/utils/data.py

@@ -3,13 +3,16 @@
 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 ..helpers.numeric import kahan_sum_nd
-from .init import get_logger, warn_once as _warn_once_factory
+from .numeric import kahan_sum_nd
+from .init import get_logger
+from .init import warn_once as _warn_once_factory
 
 T = TypeVar("T")
 
@@ -24,6 +27,7 @@ _MAX_NEGATIVE_WARN_ONCE = 1024
 
 __all__ = (
     "convert_value",
+    "normalize_optional_int",
     "MAX_MATERIALIZE_DEFAULT",
     "normalize_materialize_limit",
     "is_non_string_sequence",
@@ -48,7 +52,7 @@ def convert_value(
     """Attempt to convert a value and report failures."""
 
     try:
-        return True, conv(value)
+        converted = conv(value)
     except (ValueError, TypeError) as exc:
         if strict:
             raise
@@ -58,6 +62,90 @@ def convert_value(
         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.
+    """
+
+    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(
@@ -65,7 +153,9 @@ def negative_weights_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)
+    return _warn_once_factory(
+        _collections_logger, NEGATIVE_WEIGHTS_MSG, maxsize=maxsize
+    )
 
 
 def _log_negative_weights(negatives: Mapping[str, float]) -> None:
@@ -75,7 +165,7 @@ def _log_negative_weights(negatives: Mapping[str, float]) -> None:
 
 
 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."""
 

tnfr/utils/data.pyi

@@ -11,7 +11,6 @@ NEGATIVE_WEIGHTS_MSG: str
 
 __all__: tuple[str, ...]
 
-
 def convert_value(
     value: Any,
     conv: Callable[[Any], T],
@@ -20,35 +19,31 @@ def convert_value(
     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],
@@ -58,13 +53,9 @@ def normalize_weights(
     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]],

tnfr/utils/graph.py

@@ -18,7 +18,7 @@ __all__ = (
 
 
 def get_graph(
-    obj: GraphLike | TNFRGraph | MutableMapping[str, Any]
+    obj: GraphLike | TNFRGraph | MutableMapping[str, Any],
 ) -> MutableMapping[str, Any]:
     """Return the graph-level metadata mapping for ``obj``.
 
@@ -62,9 +62,7 @@ def get_graph_mapping(
     return MappingProxyType(data)
 
 
-def mark_dnfr_prep_dirty(
-    G: GraphLike | TNFRGraph | MutableMapping[str, Any]
-) -> None:
+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

tnfr/utils/init.py

@@ -17,7 +17,7 @@ from collections import OrderedDict
 from dataclasses import dataclass, field
 from typing import Any, Callable, Hashable, Iterable, Iterator, Literal, Mapping
 
-from ..cache import CacheManager
+from .cache import CacheManager
 
 __all__ = (
     "_configure_root",
@@ -86,7 +86,9 @@ class WarnOnce:
     every invocation.
     """
 
-    def __init__(self, logger: logging.Logger, msg: str, *, maxsize: int = 1024) -> None:
+    def __init__(
+        self, logger: logging.Logger, msg: str, *, maxsize: int = 1024
+    ) -> None:
         self._logger = logger
         self._msg = msg
         self._maxsize = maxsize
@@ -295,7 +297,9 @@ def _get_success(key: str) -> Any | None:
 
     with _IMPORT_CACHE_MANAGER.timer(_SUCCESS_CACHE_NAME):
 
-        def _lookup(cache: OrderedDict[str, _CacheEntry]) -> OrderedDict[str, _CacheEntry]:
+        def _lookup(
+            cache: OrderedDict[str, _CacheEntry],
+        ) -> OrderedDict[str, _CacheEntry]:
             nonlocal result, hit
             entry = cache.get(key)
             if entry is None:
@@ -327,7 +331,9 @@ def _store_success(key: str, value: Any) -> None:
         _trim_cache(_SUCCESS_CACHE_NAME, cache)
         return cache
 
-    def _purge_failure(cache: OrderedDict[str, Exception]) -> OrderedDict[str, Exception]:
+    def _purge_failure(
+        cache: OrderedDict[str, Exception],
+    ) -> OrderedDict[str, Exception]:
         if cache.pop(key, None) is not None:
             _IMPORT_CACHE_MANAGER.increment_eviction(_FAILURE_CACHE_NAME)
         return cache
@@ -368,7 +374,9 @@ def _store_failure(key: str, exc: Exception) -> None:
         _trim_cache(_FAILURE_CACHE_NAME, cache)
         return cache
 
-    def _purge_success(cache: OrderedDict[str, _CacheEntry]) -> OrderedDict[str, _CacheEntry]:
+    def _purge_success(
+        cache: OrderedDict[str, _CacheEntry],
+    ) -> OrderedDict[str, _CacheEntry]:
         if cache.pop(key, None) is not None:
             _IMPORT_CACHE_MANAGER.increment_eviction(_SUCCESS_CACHE_NAME)
         return cache
@@ -549,24 +557,36 @@ class LazyImportProxy:
         return self._resolve()
 
     def __getattr__(self, item: str) -> Any:
+        """Proxy attribute access to the resolved target."""
+
         return getattr(self._resolve(), item)
 
     def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Invoke the resolved target with ``args``/``kwargs``."""
+
         return self._resolve()(*args, **kwargs)
 
     def __bool__(self) -> bool:
+        """Return truthiness of the resolved target."""
+
         return bool(self._resolve())
 
     def __repr__(self) -> str:  # pragma: no cover - representation helper
+        """Return representation showing resolution status."""
+
         target = self._resolved_target()
         if target is self._UNRESOLVED:
             return f"<LazyImportProxy pending={self._key!r}>"
         return repr(target)
 
     def __str__(self) -> str:  # pragma: no cover - representation helper
+        """Return string representation of the resolved target."""
+
         return str(self._resolve())
 
     def __iter__(self) -> Iterator[Any]:  # pragma: no cover - passthrough helper
+        """Yield iteration from the resolved target."""
+
         return iter(self._resolve())
 
 
@@ -629,7 +649,9 @@ def _normalise_warm_specs(
         if extra:
             raise ValueError("'attr' can only be combined with a single module name")
         if not isinstance(module, str):
-            raise TypeError("'attr' requires the first argument to be a module name string")
+            raise TypeError(
+                "'attr' requires the first argument to be a module name string"
+            )
         return [(module, attr)]
 
     specs: list[_ModuleSpec]
@@ -660,7 +682,9 @@ def _normalise_warm_specs(
                 raise TypeError("Invalid module specification for warm_cached_import")
             normalised.append((module_name, module_attr))
             continue
-        raise TypeError("Module specifications must be strings or (module, attr) tuples")
+        raise TypeError(
+            "Module specifications must be strings or (module, attr) tuples"
+        )
 
     return normalised
 

tnfr/utils/init.pyi

@@ -1,14 +1,15 @@
-from collections.abc import Callable, Iterable, Iterator, Mapping
 import logging
+from collections.abc import Callable, Iterable, Iterator, Mapping
 from typing import Any, Hashable, Literal
 
 __all__: tuple[str, ...]
 
 def __getattr__(name: str) -> Any: ...
 
-
 class WarnOnce:
-    def __init__(self, logger: logging.Logger, msg: str, *, maxsize: int = ...) -> None: ...
+    def __init__(
+        self, logger: logging.Logger, msg: str, *, maxsize: int = ...
+    ) -> None: ...
     def __call__(
         self,
         data: Mapping[Hashable, Any] | Hashable,
@@ -16,7 +17,6 @@ class WarnOnce:
     ) -> None: ...
     def clear(self) -> None: ...
 
-
 class LazyImportProxy:
     def __init__(
         self,
@@ -31,7 +31,6 @@ class LazyImportProxy:
     def __iter__(self) -> Iterator[Any]: ...
     def resolve(self) -> Any: ...
 
-
 class ImportRegistry:
     limit: int
     failed: Mapping[str, None]
@@ -44,7 +43,6 @@ class ImportRegistry:
     def clear(self) -> None: ...
     def __contains__(self, key: str) -> bool: ...
 
-
 EMIT_MAP: Mapping[str, Callable[[str], None]]
 IMPORT_LOG: ImportRegistry
 _IMPORT_STATE: ImportRegistry
@@ -52,13 +50,10 @@ _LOGGING_CONFIGURED: bool
 _DEFAULT_CACHE_SIZE: int
 _FAILED_IMPORT_LIMIT: int
 
-
 def _configure_root() -> None: ...
 def _reset_import_state() -> None: ...
 def _reset_logging_state() -> None: ...
 def _warn_failure(module: str, attr: str | None, err: Exception) -> None: ...
-
-
 def cached_import(
     module_name: str,
     attr: str | None = ...,
@@ -67,8 +62,6 @@ def cached_import(
     emit: Literal["warn", "log", "both"] = ...,
     lazy: bool = ...,
 ) -> Any | None: ...
-
-
 def warm_cached_import(
     module: str | tuple[str, str | None] | Iterable[str | tuple[str, str | None]],
     *extra: str | tuple[str, str | None],