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

tnfr/utils/init.pyi

@@ -0,0 +1,78 @@
+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 __call__(
+        self,
+        data: Mapping[Hashable, Any] | Hashable,
+        value: Any | None = ...,
+    ) -> None: ...
+    def clear(self) -> None: ...
+
+class LazyImportProxy:
+    def __init__(
+        self,
+        module_name: str,
+        attr: str | None,
+        emit: Literal["warn", "log", "both"],
+        fallback: Any | None,
+    ) -> None: ...
+    def __getattr__(self, name: str) -> Any: ...
+    def __call__(self, *args: Any, **kwargs: Any) -> Any: ...
+    def __bool__(self) -> bool: ...
+    def __iter__(self) -> Iterator[Any]: ...
+    def resolve(self) -> Any: ...
+
+class ImportRegistry:
+    limit: int
+    failed: Mapping[str, None]
+    warned: set[str]
+    lock: Any
+
+    def record_failure(self, key: str, *, module: str | None = ...) -> None: ...
+    def discard(self, key: str) -> None: ...
+    def mark_warning(self, module: str) -> bool: ...
+    def clear(self) -> None: ...
+    def __contains__(self, key: str) -> bool: ...
+
+EMIT_MAP: Mapping[str, Callable[[str], None]]
+IMPORT_LOG: ImportRegistry
+_IMPORT_STATE: ImportRegistry
+_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 = ...,
+    *,
+    fallback: Any | None = ...,
+    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],
+    attr: str | None = ...,
+    fallback: Any | None = ...,
+    emit: Literal["warn", "log", "both"] = ...,
+    lazy: bool = ...,
+    resolve: bool = ...,
+) -> Any | dict[str, Any | None]: ...
+def get_logger(name: str) -> logging.Logger: ...
+def get_numpy() -> Any | None: ...
+def get_nodenx() -> Any | None: ...
+def prune_failed_imports(*modules: str) -> None: ...
+def warn_once(logger: logging.Logger, msg: str, *, maxsize: int = ...) -> WarnOnce: ...

tnfr/utils/io.py

@@ -0,0 +1,456 @@
+"""Structured file and JSON utilities shared across the TNFR engine."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from dataclasses import dataclass
+from functools import partial
+from pathlib import Path
+from typing import Any, Callable
+
+from .init import LazyImportProxy, cached_import, get_logger, warn_once
+
+logger = get_logger(__name__)
+
+_ORJSON_PARAMS_MSG = "'ensure_ascii', 'separators', 'cls' and extra kwargs are ignored when using orjson: %s"
+
+_warn_ignored_params_once = warn_once(logger, _ORJSON_PARAMS_MSG)
+
+
+def clear_orjson_param_warnings() -> None:
+    """Reset cached warnings for ignored :mod:`orjson` parameters."""
+
+    _warn_ignored_params_once.clear()
+
+
+def _format_ignored_params(combo: frozenset[str]) -> str:
+    """Return a stable representation for ignored parameter combinations."""
+
+    return "{" + ", ".join(map(repr, sorted(combo))) + "}"
+
+
+@dataclass(frozen=True)
+class JsonDumpsParams:
+    """Container describing the parameters used by :func:`json_dumps`."""
+
+    sort_keys: bool = False
+    default: Callable[[Any], Any] | None = None
+    ensure_ascii: bool = True
+    separators: tuple[str, str] = (",", ":")
+    cls: type[json.JSONEncoder] | None = None
+    to_bytes: bool = False
+
+
+DEFAULT_PARAMS = JsonDumpsParams()
+
+
+def _collect_ignored_params(
+    params: JsonDumpsParams, extra_kwargs: dict[str, Any]
+) -> frozenset[str]:
+    """Return a stable set of parameters ignored by :mod:`orjson`."""
+
+    ignored: set[str] = set()
+    if params.ensure_ascii is not True:
+        ignored.add("ensure_ascii")
+    if params.separators != (",", ":"):
+        ignored.add("separators")
+    if params.cls is not None:
+        ignored.add("cls")
+    if extra_kwargs:
+        ignored.update(extra_kwargs.keys())
+    return frozenset(ignored)
+
+
+def _json_dumps_orjson(
+    orjson: Any,
+    obj: Any,
+    params: JsonDumpsParams,
+    **kwargs: Any,
+) -> bytes | str:
+    """Serialize using :mod:`orjson` and warn about unsupported parameters."""
+
+    ignored = _collect_ignored_params(params, kwargs)
+    if ignored:
+        _warn_ignored_params_once(ignored, _format_ignored_params(ignored))
+
+    option = orjson.OPT_SORT_KEYS if params.sort_keys else 0
+    data = orjson.dumps(obj, option=option, default=params.default)
+    return data if params.to_bytes else data.decode("utf-8")
+
+
+def _json_dumps_std(
+    obj: Any,
+    params: JsonDumpsParams,
+    **kwargs: Any,
+) -> bytes | str:
+    """Serialize using the standard library :func:`json.dumps`."""
+
+    result = json.dumps(
+        obj,
+        sort_keys=params.sort_keys,
+        ensure_ascii=params.ensure_ascii,
+        separators=params.separators,
+        cls=params.cls,
+        default=params.default,
+        **kwargs,
+    )
+    return result if not params.to_bytes else result.encode("utf-8")
+
+
+def json_dumps(
+    obj: Any,
+    *,
+    sort_keys: bool = False,
+    default: Callable[[Any], Any] | None = None,
+    ensure_ascii: bool = True,
+    separators: tuple[str, str] = (",", ":"),
+    cls: type[json.JSONEncoder] | None = None,
+    to_bytes: bool = False,
+    **kwargs: Any,
+) -> bytes | str:
+    """Serialize ``obj`` to JSON using ``orjson`` when available."""
+
+    if not isinstance(sort_keys, bool):
+        raise TypeError("sort_keys must be a boolean")
+    if default is not None and not callable(default):
+        raise TypeError("default must be callable when provided")
+    if not isinstance(ensure_ascii, bool):
+        raise TypeError("ensure_ascii must be a boolean")
+    if not isinstance(separators, tuple) or len(separators) != 2:
+        raise TypeError("separators must be a tuple of two strings")
+    if not all(isinstance(part, str) for part in separators):
+        raise TypeError("separators must be a tuple of two strings")
+    if cls is not None:
+        if not isinstance(cls, type) or not issubclass(cls, json.JSONEncoder):
+            raise TypeError("cls must be a subclass of json.JSONEncoder")
+    if not isinstance(to_bytes, bool):
+        raise TypeError("to_bytes must be a boolean")
+
+    if (
+        sort_keys is False
+        and default is None
+        and ensure_ascii is True
+        and separators == (",", ":")
+        and cls is None
+        and to_bytes is False
+    ):
+        params = DEFAULT_PARAMS
+    else:
+        params = JsonDumpsParams(
+            sort_keys=sort_keys,
+            default=default,
+            ensure_ascii=ensure_ascii,
+            separators=separators,
+            cls=cls,
+            to_bytes=to_bytes,
+        )
+    orjson = cached_import("orjson", emit="log")
+    if orjson is not None:
+        return _json_dumps_orjson(orjson, obj, params, **kwargs)
+    return _json_dumps_std(obj, params, **kwargs)
+
+
+def _raise_import_error(name: str, *_: Any, **__: Any) -> Any:
+    raise ImportError(f"{name} is not installed")
+
+
+_MISSING_TOML_ERROR = type(
+    "MissingTOMLDependencyError",
+    (Exception,),
+    {"__doc__": "Fallback error used when tomllib/tomli is missing."},
+)
+
+_MISSING_YAML_ERROR = type(
+    "MissingPyYAMLDependencyError",
+    (Exception,),
+    {"__doc__": "Fallback error used when pyyaml is missing."},
+)
+
+
+def _resolve_lazy(value: Any) -> Any:
+    if isinstance(value, LazyImportProxy):
+        return value.resolve()
+    return value
+
+
+class _LazyBool:
+    __slots__ = ("_value",)
+
+    def __init__(self, value: Any) -> None:
+        self._value = value
+
+    def __bool__(self) -> bool:
+        return _resolve_lazy(self._value) is not None
+
+
+_TOMLI_MODULE = cached_import("tomli", emit="log", lazy=True)
+tomllib = cached_import(
+    "tomllib",
+    emit="log",
+    lazy=True,
+    fallback=_TOMLI_MODULE,
+)
+has_toml = _LazyBool(tomllib)
+
+
+_TOMLI_TOML_ERROR = cached_import(
+    "tomli",
+    "TOMLDecodeError",
+    emit="log",
+    lazy=True,
+    fallback=_MISSING_TOML_ERROR,
+)
+TOMLDecodeError = cached_import(
+    "tomllib",
+    "TOMLDecodeError",
+    emit="log",
+    lazy=True,
+    fallback=_TOMLI_TOML_ERROR,
+)
+
+
+_TOMLI_LOADS = cached_import(
+    "tomli",
+    "loads",
+    emit="log",
+    lazy=True,
+    fallback=partial(_raise_import_error, "tomllib/tomli"),
+)
+_TOML_LOADS: Callable[[str], Any] = cached_import(
+    "tomllib",
+    "loads",
+    emit="log",
+    lazy=True,
+    fallback=_TOMLI_LOADS,
+)
+
+
+yaml = cached_import("yaml", emit="log", lazy=True)
+
+
+YAMLError = cached_import(
+    "yaml",
+    "YAMLError",
+    emit="log",
+    lazy=True,
+    fallback=_MISSING_YAML_ERROR,
+)
+
+
+_YAML_SAFE_LOAD: Callable[[str], Any] = cached_import(
+    "yaml",
+    "safe_load",
+    emit="log",
+    lazy=True,
+    fallback=partial(_raise_import_error, "pyyaml"),
+)
+
+
+def _parse_yaml(text: str) -> Any:
+    """Parse YAML ``text`` using ``safe_load`` if available."""
+
+    return _YAML_SAFE_LOAD(text)
+
+
+def _parse_toml(text: str) -> Any:
+    """Parse TOML ``text`` using ``tomllib`` or ``tomli``."""
+
+    return _TOML_LOADS(text)
+
+
+PARSERS = {
+    ".json": json.loads,
+    ".yaml": _parse_yaml,
+    ".yml": _parse_yaml,
+    ".toml": _parse_toml,
+}
+
+
+def _get_parser(suffix: str) -> Callable[[str], Any]:
+    try:
+        return PARSERS[suffix]
+    except KeyError as exc:
+        raise ValueError(f"Unsupported suffix: {suffix}") from exc
+
+
+_BASE_ERROR_MESSAGES: dict[type[BaseException], str] = {
+    OSError: "Could not read {path}: {e}",
+    UnicodeDecodeError: "Encoding error while reading {path}: {e}",
+    json.JSONDecodeError: "Error parsing JSON file at {path}: {e}",
+    ImportError: "Missing dependency parsing {path}: {e}",
+}
+
+
+def _resolve_exception_type(candidate: Any) -> type[BaseException] | None:
+    resolved = _resolve_lazy(candidate)
+    if isinstance(resolved, type) and issubclass(resolved, BaseException):
+        return resolved
+    return None
+
+
+_OPTIONAL_ERROR_MESSAGE_FACTORIES: tuple[
+    tuple[Callable[[], type[BaseException] | None], str],
+    ...,
+] = (
+    (
+        lambda: _resolve_exception_type(YAMLError),
+        "Error parsing YAML file at {path}: {e}",
+    ),
+    (
+        lambda: _resolve_exception_type(TOMLDecodeError),
+        "Error parsing TOML file at {path}: {e}",
+    ),
+)
+
+
+_BASE_STRUCTURED_EXCEPTIONS = (
+    OSError,
+    UnicodeDecodeError,
+    json.JSONDecodeError,
+    ImportError,
+)
+
+
+def _iter_optional_exceptions() -> list[type[BaseException]]:
+    errors: list[type[BaseException]] = []
+    for resolver, _ in _OPTIONAL_ERROR_MESSAGE_FACTORIES:
+        exc_type = resolver()
+        if exc_type is not None:
+            errors.append(exc_type)
+    return errors
+
+
+def _is_structured_error(exc: Exception) -> bool:
+    if isinstance(exc, _BASE_STRUCTURED_EXCEPTIONS):
+        return True
+    for optional_exc in _iter_optional_exceptions():
+        if isinstance(exc, optional_exc):
+            return True
+    return False
+
+
+def _format_structured_file_error(path: Path, e: Exception) -> str:
+    for exc, msg in _BASE_ERROR_MESSAGES.items():
+        if isinstance(e, exc):
+            return msg.format(path=path, e=e)
+
+    for resolver, msg in _OPTIONAL_ERROR_MESSAGE_FACTORIES:
+        exc_type = resolver()
+        if exc_type is not None and isinstance(e, exc_type):
+            return msg.format(path=path, e=e)
+
+    return f"Error parsing {path}: {e}"
+
+
+class StructuredFileError(Exception):
+    """Error while reading or parsing a structured file."""
+
+    def __init__(self, path: Path, original: Exception) -> None:
+        super().__init__(_format_structured_file_error(path, original))
+        self.path = path
+
+
+def read_structured_file(path: Path) -> Any:
+    """Read a JSON, YAML or TOML file and return parsed data."""
+
+    suffix = path.suffix.lower()
+    try:
+        parser = _get_parser(suffix)
+    except ValueError as e:
+        raise StructuredFileError(path, e) from e
+    try:
+        text = path.read_text(encoding="utf-8")
+        return parser(text)
+    except Exception as e:
+        if _is_structured_error(e):
+            raise StructuredFileError(path, e) from e
+        raise
+
+
+def safe_write(
+    path: str | Path,
+    write: Callable[[Any], Any],
+    *,
+    mode: str = "w",
+    encoding: str | None = "utf-8",
+    atomic: bool = True,
+    sync: bool | None = None,
+    **open_kwargs: Any,
+) -> None:
+    """Write to ``path`` ensuring parent directory exists and handle errors.
+
+    Parameters
+    ----------
+    path:
+        Destination file path.
+    write:
+        Callback receiving the opened file object and performing the actual
+        write.
+    mode:
+        File mode passed to :func:`open`. Text modes (default) use UTF-8
+        encoding unless ``encoding`` is ``None``. When a binary mode is used
+        (``'b'`` in ``mode``) no encoding parameter is supplied so
+        ``write`` may write bytes.
+    encoding:
+        Encoding for text modes. Ignored for binary modes.
+    atomic:
+        When ``True`` (default) writes to a temporary file and atomically
+        replaces the destination after flushing to disk. When ``False``
+        writes directly to ``path`` without any atomicity guarantee.
+    sync:
+        When ``True`` flushes and fsyncs the file descriptor after writing.
+        ``None`` uses ``atomic`` to determine syncing behaviour.
+    """
+
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    open_params = dict(mode=mode, **open_kwargs)
+    if "b" not in mode and encoding is not None:
+        open_params["encoding"] = encoding
+    if sync is None:
+        sync = atomic
+    tmp_path: Path | None = None
+    try:
+        if atomic:
+            tmp_fd = tempfile.NamedTemporaryFile(dir=path.parent, delete=False)
+            tmp_path = Path(tmp_fd.name)
+            tmp_fd.close()
+            with open(tmp_path, **open_params) as fd:
+                write(fd)
+                if sync:
+                    fd.flush()
+                    os.fsync(fd.fileno())
+            try:
+                os.replace(tmp_path, path)
+            except OSError as e:
+                logger.error(
+                    "Atomic replace failed for %s -> %s: %s", tmp_path, path, e
+                )
+                raise
+        else:
+            with open(path, **open_params) as fd:
+                write(fd)
+                if sync:
+                    fd.flush()
+                    os.fsync(fd.fileno())
+    except (OSError, ValueError, TypeError) as e:
+        raise type(e)(f"Failed to write file {path}: {e}") from e
+    finally:
+        if tmp_path is not None:
+            tmp_path.unlink(missing_ok=True)
+
+
+__all__ = (
+    "JsonDumpsParams",
+    "DEFAULT_PARAMS",
+    "clear_orjson_param_warnings",
+    "json_dumps",
+    "read_structured_file",
+    "safe_write",
+    "StructuredFileError",
+    "TOMLDecodeError",
+    "YAMLError",
+)
+

tnfr/{helpers → utils}/numeric.py

@@ -2,8 +2,9 @@
 
 from __future__ import annotations
 
-from collections.abc import Iterable, Sequence
 import math
+from collections.abc import Iterable, Sequence
+from typing import Any
 
 __all__ = (
     "clamp",
@@ -12,36 +13,31 @@ __all__ = (
     "similarity_abs",
     "kahan_sum_nd",
     "angle_diff",
+    "angle_diff_array",
 )
 
 
 def clamp(x: float, a: float, b: float) -> float:
     """Return ``x`` clamped to the ``[a, b]`` interval."""
+
     return max(a, min(b, x))
 
 
 def clamp01(x: float) -> float:
     """Clamp ``x`` to the ``[0,1]`` interval."""
+
     return clamp(float(x), 0.0, 1.0)
 
 
 def within_range(val: float, lower: float, upper: float, tol: float = 1e-9) -> bool:
-    """Return ``True`` if ``val`` lies in ``[lower, upper]`` within ``tol``.
-
-    The comparison uses absolute differences instead of :func:`math.isclose`.
-    """
+    """Return ``True`` if ``val`` lies in ``[lower, upper]`` within ``tol``."""
 
     v = float(val)
     return lower <= v <= upper or abs(v - lower) <= tol or abs(v - upper) <= tol
 
 
 def _norm01(x: float, lo: float, hi: float) -> float:
-    """Normalize ``x`` to the unit interval given bounds.
-
-    ``lo`` and ``hi`` delimit the original value range. When ``hi`` is not
-    greater than ``lo`` the function returns ``0.0`` to avoid division by
-    zero. The result is clamped to ``[0,1]``.
-    """
+    """Normalize ``x`` to the unit interval given bounds."""
 
     if hi <= lo:
         return 0.0
@@ -49,23 +45,14 @@ def _norm01(x: float, lo: float, hi: float) -> float:
 
 
 def similarity_abs(a: float, b: float, lo: float, hi: float) -> float:
-    """Return absolute similarity of ``a`` and ``b`` over ``[lo, hi]``.
-
-    It computes ``1`` minus the normalized absolute difference between
-    ``a`` and ``b``. Values are scaled using :func:`_norm01` so the result
-    falls within ``[0,1]``.
-    """
+    """Return absolute similarity of ``a`` and ``b`` over ``[lo, hi]``."""
 
     return 1.0 - _norm01(abs(float(a) - float(b)), 0.0, hi - lo)
 
-def kahan_sum_nd(
-    values: Iterable[Sequence[float]], dims: int
-) -> tuple[float, ...]:
-    """Return compensated sums of ``values`` with ``dims`` components.
 
-    Each component of the tuples in ``values`` is summed independently using the
-    Kahan–Babuška (Neumaier) algorithm to reduce floating point error.
-    """
+def kahan_sum_nd(values: Iterable[Sequence[float]], dims: int) -> tuple[float, ...]:
+    """Return compensated sums of ``values`` with ``dims`` components."""
+
     if dims < 1:
         raise ValueError("dims must be >= 1")
     totals = [0.0] * dims
@@ -84,4 +71,44 @@ def kahan_sum_nd(
 
 def angle_diff(a: float, b: float) -> float:
     """Return the minimal difference between two angles in radians."""
+
     return (float(a) - float(b) + math.pi) % math.tau - math.pi
+
+
+def angle_diff_array(
+    a: Sequence[float] | "np.ndarray",
+    b: Sequence[float] | "np.ndarray",
+    *,
+    np: Any,
+    out: "np.ndarray | None" = None,
+    where: "np.ndarray | None" = None,
+) -> "np.ndarray":
+    """Vectorised :func:`angle_diff` compatible with NumPy arrays."""
+
+    if np is None:
+        raise TypeError("angle_diff_array requires a NumPy module")
+
+    kwargs = {"where": where} if where is not None else {}
+    minuend = np.asarray(a, dtype=float)
+    subtrahend = np.asarray(b, dtype=float)
+    if out is None:
+        out = np.empty_like(minuend, dtype=float)
+        if where is not None:
+            out.fill(0.0)
+    else:
+        if getattr(out, "shape", None) != minuend.shape:
+            raise ValueError("out must match the broadcasted shape of inputs")
+
+    np.subtract(minuend, subtrahend, out=out, **kwargs)
+    np.add(out, math.pi, out=out, **kwargs)
+    if where is not None:
+        mask = np.asarray(where, dtype=bool)
+        if mask.shape != out.shape:
+            raise ValueError("where mask must match the broadcasted shape of inputs")
+        selected = out[mask]
+        if selected.size:
+            out[mask] = np.remainder(selected, math.tau)
+    else:
+        np.remainder(out, math.tau, out=out)
+    np.subtract(out, math.pi, out=out, **kwargs)
+    return out

tnfr/utils/numeric.pyi

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from typing import Any
+
+__all__: tuple[str, ...]
+
+def clamp(x: float, a: float, b: float) -> float: ...
+def clamp01(x: float) -> float: ...
+def within_range(val: float, lower: float, upper: float, tol: float = ...) -> bool: ...
+def similarity_abs(a: float, b: float, lo: float, hi: float) -> float: ...
+def kahan_sum_nd(values: Iterable[Sequence[float]], dims: int) -> tuple[float, ...]: ...
+def angle_diff(a: float, b: float) -> float: ...
+def angle_diff_array(
+    a: Sequence[float] | Any,
+    b: Sequence[float] | Any,
+    *,
+    np: Any,
+    out: Any | None = ...,
+    where: Any | None = ...,
+) -> Any: ...