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

tnfr/utils/io.py

@@ -1,26 +1,21 @@
-"""Serialisation helpers for TNFR, including JSON convenience wrappers."""
+"""Structured file and JSON utilities shared across the TNFR engine."""
 
 from __future__ import annotations
 
-from dataclasses import dataclass
 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 cached_import, get_logger, warn_once
-
-__all__ = (
-    "JsonDumpsParams",
-    "DEFAULT_PARAMS",
-    "json_dumps",
-    "clear_orjson_param_warnings",
-)
-
-_ORJSON_PARAMS_MSG = (
-    "'ensure_ascii', 'separators', 'cls' and extra kwargs are ignored when using orjson: %s"
-)
+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)
 
 
@@ -155,3 +150,307 @@ def json_dumps(
     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,24 +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.
+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.
-    """
     if dims < 1:
         raise ValueError("dims must be >= 1")
     totals = [0.0] * dims
@@ -85,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: ...

tnfr/validation/__init__.py

@@ -1,25 +1,113 @@
-"""Validation helpers for TNFR sequences."""
+"""Unified validation interface consolidating grammar, graph and spectral checks.
+
+This package re-exports the canonical grammar helpers implemented in
+``tnfr.operators.grammar`` so downstream code can rely on a single import path for
+structural validation primitives.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Generic, Mapping, Protocol, TypeVar, runtime_checkable
+
+SubjectT = TypeVar("SubjectT")
+
+
+@dataclass(slots=True)
+class ValidationOutcome(Generic[SubjectT]):
+    """Result emitted by all canonical TNFR validators."""
+
+    subject: SubjectT
+    """The validated subject in canonical form."""
+
+    passed: bool
+    """Whether the validation succeeded without invariant violations."""
+
+    summary: Mapping[str, Any]
+    """Structured diagnostics describing the performed checks."""
+
+    artifacts: Mapping[str, Any] | None = None
+    """Optional artefacts (e.g. clamped nodes, normalised vectors)."""
+
+
+@runtime_checkable
+class Validator(Protocol[SubjectT]):
+    """Contract implemented by runtime and spectral validators."""
+
+    def validate(self, subject: SubjectT, /, **kwargs: Any) -> ValidationOutcome[SubjectT]:
+        """Validate ``subject`` returning a :class:`ValidationOutcome`."""
+
+    def report(self, outcome: "ValidationOutcome[SubjectT]") -> str:
+        """Produce a concise textual explanation for ``outcome``."""
+
 
 from .compatibility import CANON_COMPAT, CANON_FALLBACK
-from .grammar import (
+from ..operators.grammar import (
     GrammarContext,
+    MutationPreconditionError,
+    RepeatWindowError,
+    SequenceValidationResult,
+    SequenceSyntaxError,
+    StructuralGrammarError,
+    TholClosureError,
+    TransitionCompatibilityError,
     apply_glyph_with_grammar,
     enforce_canonical_grammar,
     on_applied_glyph,
+    record_grammar_violation,
 )
-from .rules import coerce_glyph, glyph_fallback, normalized_dnfr, get_norm
-from .syntax import validate_sequence
+from .graph import GRAPH_VALIDATORS, run_validators
+from .window import validate_window
+from .runtime import GraphCanonicalValidator, apply_canonical_clamps, validate_canon
+from .rules import coerce_glyph, get_norm, glyph_fallback, normalized_dnfr
+from .soft_filters import (
+    acceleration_norm,
+    check_repeats,
+    maybe_force,
+    soft_grammar_filters,
+)
+from ..operators.grammar import validate_sequence
 
 __all__ = (
+    "ValidationOutcome",
+    "Validator",
     "validate_sequence",
     "GrammarContext",
+    "StructuralGrammarError",
+    "RepeatWindowError",
+    "MutationPreconditionError",
+    "TholClosureError",
+    "TransitionCompatibilityError",
+    "SequenceValidationResult",
+    "SequenceSyntaxError",
     "apply_glyph_with_grammar",
     "enforce_canonical_grammar",
     "on_applied_glyph",
+    "record_grammar_violation",
+    "validate_window",
+    "run_validators",
+    "GRAPH_VALIDATORS",
     "coerce_glyph",
     "glyph_fallback",
     "normalized_dnfr",
     "get_norm",
+    "acceleration_norm",
+    "check_repeats",
+    "maybe_force",
+    "soft_grammar_filters",
     "CANON_COMPAT",
     "CANON_FALLBACK",
+    "GraphCanonicalValidator",
+    "apply_canonical_clamps",
+    "validate_canon",
+    "NFRValidator",
 )
+
+
+def __getattr__(name: str) -> Any:
+    if name == "NFRValidator":
+        from .spectral import NFRValidator as _NFRValidator
+
+        return _NFRValidator
+    raise AttributeError(name)
+

tnfr/validation/__init__.pyi

@@ -1,17 +1,77 @@
-from typing import Any
-
-__all__: Any
-
-def __getattr__(name: str) -> Any: ...
-
-CANON_COMPAT: Any
-CANON_FALLBACK: Any
-GrammarContext: Any
-apply_glyph_with_grammar: Any
-coerce_glyph: Any
-enforce_canonical_grammar: Any
-get_norm: Any
-glyph_fallback: Any
-normalized_dnfr: Any
-on_applied_glyph: Any
-validate_sequence: Any
+from collections.abc import Mapping
+from typing import Any, Generic, Protocol, TypeVar
+
+from ..types import Glyph, TNFRGraph
+from .compatibility import CANON_COMPAT as CANON_COMPAT, CANON_FALLBACK as CANON_FALLBACK
+from ..operators.grammar import (
+    GrammarContext,
+    MutationPreconditionError,
+    RepeatWindowError,
+    SequenceSyntaxError,
+    SequenceValidationResult,
+    StructuralGrammarError,
+    TholClosureError,
+    TransitionCompatibilityError,
+    apply_glyph_with_grammar,
+    enforce_canonical_grammar,
+    on_applied_glyph,
+    record_grammar_violation,
+)
+from .graph import GRAPH_VALIDATORS, run_validators
+from .window import validate_window
+from .rules import coerce_glyph, get_norm, glyph_fallback, normalized_dnfr
+from .soft_filters import (acceleration_norm, check_repeats, maybe_force, soft_grammar_filters)
+from .runtime import GraphCanonicalValidator, apply_canonical_clamps, validate_canon
+from .spectral import NFRValidator
+from ..operators.grammar import validate_sequence
+
+SubjectT = TypeVar("SubjectT")
+
+
+class ValidationOutcome(Generic[SubjectT]):
+    subject: SubjectT
+    passed: bool
+    summary: Mapping[str, Any]
+    artifacts: Mapping[str, Any] | None
+
+
+class Validator(Protocol[SubjectT]):
+    def validate(self, subject: SubjectT, /, **kwargs: Any) -> ValidationOutcome[SubjectT]: ...
+
+    def report(self, outcome: ValidationOutcome[SubjectT]) -> str: ...
+
+
+__all__ = (
+    "ValidationOutcome",
+    "Validator",
+    "validate_sequence",
+    "GrammarContext",
+    "StructuralGrammarError",
+    "RepeatWindowError",
+    "MutationPreconditionError",
+    "TholClosureError",
+    "TransitionCompatibilityError",
+    "SequenceSyntaxError",
+    "SequenceValidationResult",
+    "apply_glyph_with_grammar",
+    "enforce_canonical_grammar",
+    "on_applied_glyph",
+    "record_grammar_violation",
+    "validate_window",
+    "run_validators",
+    "GRAPH_VALIDATORS",
+    "coerce_glyph",
+    "glyph_fallback",
+    "normalized_dnfr",
+    "get_norm",
+    "acceleration_norm",
+    "check_repeats",
+    "maybe_force",
+    "soft_grammar_filters",
+    "CANON_COMPAT",
+    "CANON_FALLBACK",
+    "GraphCanonicalValidator",
+    "apply_canonical_clamps",
+    "validate_canon",
+    "NFRValidator",
+)