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

tnfr/io.py

@@ -0,0 +1,246 @@
+"""Structured file I/O utilities.
+
+Optional parsers such as ``tomllib``/``tomli`` and ``pyyaml`` are loaded via
+the :func:`tnfr.import_utils.cached_import` helper. Their import results and
+failure states are cached and can be cleared with
+``cached_import.cache_clear()`` and :func:`tnfr.import_utils.prune_failed_imports`
+when needed.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any, Callable
+from functools import partial
+
+from .import_utils import cached_import
+from .logging_utils import get_logger
+
+
+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."},
+)
+
+
+tomllib = cached_import(
+    "tomllib",
+    emit="log",
+    fallback=cached_import("tomli", emit="log"),
+)
+has_toml = tomllib is not None
+
+
+TOMLDecodeError = cached_import(
+    "tomllib",
+    "TOMLDecodeError",
+    emit="log",
+    fallback=cached_import(
+        "tomli",
+        "TOMLDecodeError",
+        emit="log",
+        fallback=_MISSING_TOML_ERROR,
+    ),
+)
+
+
+_TOML_LOADS: Callable[[str], Any] = cached_import(
+    "tomllib",
+    "loads",
+    emit="log",
+    fallback=cached_import(
+        "tomli",
+        "loads",
+        emit="log",
+        fallback=partial(_raise_import_error, "tomllib/tomli"),
+    ),
+)
+
+
+yaml = cached_import("yaml", emit="log")
+
+
+YAMLError = cached_import(
+    "yaml",
+    "YAMLError",
+    emit="log",
+    fallback=_MISSING_YAML_ERROR,
+)
+
+
+_YAML_SAFE_LOAD: Callable[[str], Any] = cached_import(
+    "yaml",
+    "safe_load",
+    emit="log",
+    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
+
+
+ERROR_MESSAGES = {
+    OSError: "Could not read {path}: {e}",
+    UnicodeDecodeError: "Encoding error while reading {path}: {e}",
+    json.JSONDecodeError: "Error parsing JSON file at {path}: {e}",
+    YAMLError: "Error parsing YAML file at {path}: {e}",
+    ImportError: "Missing dependency parsing {path}: {e}",
+}
+if has_toml:
+    ERROR_MESSAGES[TOMLDecodeError] = "Error parsing TOML file at {path}: {e}"
+
+
+def _format_structured_file_error(path: Path, e: Exception) -> str:
+    for exc, msg in ERROR_MESSAGES.items():
+        if isinstance(e, exc):
+            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):
+        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 (
+        OSError,
+        UnicodeDecodeError,
+        json.JSONDecodeError,
+        YAMLError,
+        TOMLDecodeError,
+        ImportError,
+    ) as e:
+        raise StructuredFileError(path, e) from e
+
+
+logger = get_logger(__name__)
+
+
+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__ = (
+    "read_structured_file",
+    "safe_write",
+    "StructuredFileError",
+    "TOMLDecodeError",
+    "YAMLError",
+)

tnfr/json_utils.py

@@ -0,0 +1,162 @@
+"""JSON helpers with optional :mod:`orjson` support.
+
+This module lazily imports :mod:`orjson` on first use of :func:`json_dumps`.
+The fast serializer is brought in through
+``tnfr.import_utils.cached_import``; its cache and failure registry can be
+reset using ``cached_import.cache_clear()`` and
+:func:`tnfr.import_utils.prune_failed_imports`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from typing import Any, Callable
+
+from .import_utils import cached_import
+from .logging_utils import get_logger, warn_once
+
+_ORJSON_PARAMS_MSG = (
+    "'ensure_ascii', 'separators', 'cls' and extra kwargs are ignored when using orjson: %s"
+)
+
+logger = get_logger(__name__)
+
+_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.
+
+    Returns a ``str`` by default. Pass ``to_bytes=True`` to obtain a ``bytes``
+    result. When :mod:`orjson` is used, the ``ensure_ascii``, ``separators``,
+    ``cls`` and any additional keyword arguments are ignored because they are
+    not supported by :func:`orjson.dumps`. A warning is emitted whenever such
+    ignored parameters are detected.
+    """
+    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)

tnfr/locking.py

@@ -0,0 +1,37 @@
+"""Utilities for named locks.
+
+This module provides helpers to obtain process-wide ``threading.Lock``
+instances identified by name. Locks are created lazily and reused,
+allowing different modules to synchronise on shared resources without
+redefining locks repeatedly.
+"""
+
+from __future__ import annotations
+
+import threading
+from weakref import WeakValueDictionary
+
+# Registry of locks by name guarded by ``_REGISTRY_LOCK``.
+# Using ``WeakValueDictionary`` ensures that once a lock is no longer
+# referenced elsewhere, it is removed from the registry automatically,
+# keeping the catalogue aligned with active coherence nodes.
+_locks: WeakValueDictionary[str, threading.Lock] = WeakValueDictionary()
+_REGISTRY_LOCK = threading.Lock()
+
+
+def get_lock(name: str) -> threading.Lock:
+    """Return a re-usable lock identified by ``name``.
+
+    The same lock object is returned for identical names. Locks are
+    created on first use and stored in a process-wide registry.
+    """
+
+    with _REGISTRY_LOCK:
+        lock = _locks.get(name)
+        if lock is None:
+            lock = threading.Lock()
+            _locks[name] = lock
+    return lock
+
+
+__all__ = ["get_lock"]

tnfr/logging_utils.py

@@ -0,0 +1,116 @@
+"""Logging utilities for TNFR.
+
+Centralises creation of module-specific loggers so that all TNFR
+modules share a consistent configuration.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Any, Hashable, Mapping
+
+__all__ = ("_configure_root", "get_logger", "WarnOnce", "warn_once")
+
+_LOGGING_CONFIGURED = False
+
+
+def _configure_root() -> None:
+    """Ensure the root logger has handlers and a default format."""
+
+    global _LOGGING_CONFIGURED
+    if _LOGGING_CONFIGURED:
+        return
+
+    root = logging.getLogger()
+    if not root.handlers:
+        kwargs = {"format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"}
+        if root.level == logging.NOTSET:
+            kwargs["level"] = logging.INFO
+        logging.basicConfig(**kwargs)
+
+    _LOGGING_CONFIGURED = True
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return a module-specific logger."""
+    _configure_root()
+    return logging.getLogger(name)
+
+
+class WarnOnce:
+    """Log a warning only once for each unique key.
+
+    ``WarnOnce`` tracks seen keys in a bounded :class:`set`. When ``maxsize`` is
+    reached an arbitrary key is evicted to keep memory usage stable; ordered
+    eviction is intentionally avoided to keep the implementation lightweight.
+    Instances are callable and accept either a mapping of keys to values or a
+    single key/value pair. Passing ``maxsize <= 0`` disables caching and logs on
+    every invocation.
+    """
+
+    def __init__(self, logger: logging.Logger, msg: str, *, maxsize: int = 1024) -> None:
+        self._logger = logger
+        self._msg = msg
+        self._maxsize = maxsize
+        self._seen: set[Hashable] = set()
+        self._lock = threading.Lock()
+
+    def _mark_seen(self, key: Hashable) -> bool:
+        """Return ``True`` when ``key`` has not been seen before."""
+
+        if self._maxsize <= 0:
+            # Caching disabled – always log.
+            return True
+        if key in self._seen:
+            return False
+        if len(self._seen) >= self._maxsize:
+            # ``set.pop()`` removes an arbitrary element which is acceptable for
+            # this lightweight cache.
+            self._seen.pop()
+        self._seen.add(key)
+        return True
+
+    def __call__(
+        self,
+        data: Mapping[Hashable, Any] | Hashable,
+        value: Any | None = None,
+    ) -> None:
+        """Log new keys found in ``data``.
+
+        ``data`` may be a mapping of keys to payloads or a single key. When
+        called with a single key ``value`` customises the payload passed to the
+        logging message; the key itself is used when ``value`` is omitted.
+        """
+
+        if isinstance(data, Mapping):
+            new_items: dict[Hashable, Any] = {}
+            with self._lock:
+                for key, item_value in data.items():
+                    if self._mark_seen(key):
+                        new_items[key] = item_value
+            if new_items:
+                self._logger.warning(self._msg, new_items)
+            return
+
+        key = data
+        payload = value if value is not None else data
+        with self._lock:
+            should_log = self._mark_seen(key)
+        if should_log:
+            self._logger.warning(self._msg, payload)
+
+    def clear(self) -> None:
+        """Reset tracked keys."""
+        with self._lock:
+            self._seen.clear()
+
+
+def warn_once(
+    logger: logging.Logger,
+    msg: str,
+    *,
+    maxsize: int = 1024,
+) -> WarnOnce:
+    """Return a :class:`WarnOnce` logger."""
+    return WarnOnce(logger, msg, maxsize=maxsize)

tnfr/metrics/__init__.py

@@ -0,0 +1,41 @@
+"""Registerable metrics."""
+
+from __future__ import annotations
+
+from .core import register_metrics_callbacks
+from .reporting import (
+    Tg_global,
+    Tg_by_node,
+    latency_series,
+    glyphogram_series,
+    glyph_top,
+    build_metrics_summary,
+)
+from .coherence import (
+    coherence_matrix,
+    local_phase_sync,
+    local_phase_sync_weighted,
+    register_coherence_callbacks,
+)
+from .diagnosis import (
+    register_diagnosis_callbacks,
+    dissonance_events,
+)
+from .export import export_metrics
+
+__all__ = (
+    "register_metrics_callbacks",
+    "Tg_global",
+    "Tg_by_node",
+    "latency_series",
+    "glyphogram_series",
+    "glyph_top",
+    "build_metrics_summary",
+    "coherence_matrix",
+    "local_phase_sync",
+    "local_phase_sync_weighted",
+    "register_coherence_callbacks",
+    "register_diagnosis_callbacks",
+    "dissonance_events",
+    "export_metrics",
+)