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

tnfr/graph_utils.py

@@ -1,84 +0,0 @@
-"""Utilities for graph-level bookkeeping.
-
-This module centralises helpers that operate on the metadata stored inside
-graph objects.  Besides flagging ΔNFR preparation caches it also exposes
-lightweight adapters to obtain the canonical ``graph`` mapping and to read
-validated configuration dictionaries.
-"""
-
-from __future__ import annotations
-
-import warnings
-from types import MappingProxyType
-from typing import Any, Mapping
-
-__all__ = (
-    "get_graph",
-    "get_graph_mapping",
-    "mark_dnfr_prep_dirty",
-    "supports_add_edge",
-)
-
-
-def get_graph(obj: Any) -> Any:
-    """Return ``obj.graph`` when present or ``obj`` otherwise."""
-    return getattr(obj, "graph", obj)
-
-
-def get_graph_mapping(
-    G: Any, key: str, warn_msg: str
-) -> Mapping[str, Any] | None:
-    """Return an immutable view of ``G``'s stored mapping for ``key``.
-
-    The helper normalises access to ``G.graph[key]`` by returning
-    ``None`` when the key is missing or holds a non-mapping value.  When a
-    mapping is found it is wrapped in :class:`types.MappingProxyType` to guard
-    against accidental mutation.  ``warn_msg`` is emitted via
-    :func:`warnings.warn` when the stored value is not a mapping.
-    """
-    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: Any) -> None:
-    """Flag ΔNFR preparation data as stale.
-
-    Parameters
-    ----------
-    G : Any
-        Graph-like object whose ``graph`` attribute will receive the
-        ``"_dnfr_prep_dirty"`` flag.
-
-    Returns
-    -------
-    None
-        This function mutates ``G`` in place.
-    """
-    graph = get_graph(G)
-    graph["_dnfr_prep_dirty"] = True
-
-
-def supports_add_edge(graph: Any) -> bool:
-    """Return ``True`` if ``graph`` exposes an ``add_edge`` method.
-
-    Parameters
-    ----------
-    graph : Any
-        Object representing a graph.
-
-    Returns
-    -------
-    bool
-        ``True`` when ``graph`` implements ``add_edge``; ``False`` otherwise.
-    """
-    return hasattr(graph, "add_edge")

tnfr/helpers/__init__.py

@@ -1,71 +0,0 @@
-"""Curated high-level helpers exposed by :mod:`tnfr.helpers`.
-
-The module is intentionally small and surfaces utilities that are stable for
-external use, covering data preparation, glyph history management, and graph
-cache invalidation.
-"""
-
-from __future__ import annotations
-
-from ..cache import (
-    EdgeCacheManager,
-    cached_node_list,
-    cached_nodes_and_A,
-    edge_version_cache,
-    edge_version_update,
-    ensure_node_index_map,
-    ensure_node_offset_map,
-    increment_edge_version,
-    node_set_checksum,
-    stable_json,
-)
-from ..graph_utils import get_graph, get_graph_mapping, mark_dnfr_prep_dirty
-from .numeric import (
-    angle_diff,
-    clamp,
-    clamp01,
-    kahan_sum_nd,
-)
-
-
-def __getattr__(name: str):
-    if name in _GLYPH_HISTORY_EXPORTS:
-        from .. import glyph_history as _glyph_history
-
-        value = getattr(_glyph_history, name)
-        globals()[name] = value
-        return value
-    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
-
-__all__ = (
-    "EdgeCacheManager",
-    "angle_diff",
-    "cached_node_list",
-    "cached_nodes_and_A",
-    "clamp",
-    "clamp01",
-    "edge_version_cache",
-    "edge_version_update",
-    "ensure_node_index_map",
-    "ensure_node_offset_map",
-    "get_graph",
-    "get_graph_mapping",
-    "increment_edge_version",
-    "kahan_sum_nd",
-    "mark_dnfr_prep_dirty",
-    "node_set_checksum",
-    "stable_json",
-    "count_glyphs",
-    "ensure_history",
-    "last_glyph",
-    "push_glyph",
-    "recent_glyph",
-)
-
-_GLYPH_HISTORY_EXPORTS = (
-    "count_glyphs",
-    "ensure_history",
-    "last_glyph",
-    "push_glyph",
-    "recent_glyph",
-)

tnfr/import_utils.py

@@ -1,228 +0,0 @@
-"""Helpers for optional imports and cached access to heavy modules.
-
-This module centralises caching for optional dependencies. It exposes
-:func:`cached_import`, backed by a small :func:`functools.lru_cache`, alongside a
-light-weight registry that tracks failed imports and warnings. Use
-:func:`prune_failed_imports` or ``cached_import.cache_clear`` to reset state when
-new packages become available at runtime.
-"""
-
-from __future__ import annotations
-
-import importlib
-import warnings
-from collections import OrderedDict
-from dataclasses import dataclass, field
-from functools import lru_cache
-from typing import Any, Callable, Literal
-import threading
-
-from .logging_utils import get_logger
-
-__all__ = (
-    "cached_import",
-    "get_numpy",
-    "get_nodonx",
-    "prune_failed_imports",
-    "IMPORT_LOG",
-)
-
-
-logger = get_logger(__name__)
-
-
-def _emit(message: str, mode: Literal["warn", "log", "both"]) -> None:
-    """Emit ``message`` via :mod:`warnings`, logger or both."""
-
-    if mode in ("warn", "both"):
-        warnings.warn(message, RuntimeWarning, stacklevel=2)
-    if mode in ("log", "both"):
-        logger.warning(message)
-
-
-EMIT_MAP: dict[str, Callable[[str], None]] = {
-    "warn": lambda msg: _emit(msg, "warn"),
-    "log": lambda msg: _emit(msg, "log"),
-    "both": lambda msg: _emit(msg, "both"),
-}
-
-
-def _format_failure_message(module: str, attr: str | None, err: Exception) -> str:
-    """Return a standardised failure message."""
-
-    return (
-        f"Failed to import module '{module}': {err}"
-        if isinstance(err, ImportError)
-        else f"Module '{module}' has no attribute '{attr}': {err}"
-    )
-
-
-_FAILED_IMPORT_LIMIT = 128
-_DEFAULT_CACHE_SIZE = 128
-
-
-@dataclass(slots=True)
-class ImportRegistry:
-    """Process-wide registry tracking failed imports and emitted warnings."""
-
-    limit: int = _FAILED_IMPORT_LIMIT
-    failed: OrderedDict[str, None] = field(default_factory=OrderedDict)
-    warned: set[str] = field(default_factory=set)
-    lock: threading.Lock = field(default_factory=threading.Lock)
-
-    def _insert(self, key: str) -> None:
-        self.failed[key] = None
-        self.failed.move_to_end(key)
-        while len(self.failed) > self.limit:
-            self.failed.popitem(last=False)
-
-    def record_failure(self, key: str, *, module: str | None = None) -> None:
-        """Record ``key`` and, optionally, ``module`` as failed imports."""
-
-        with self.lock:
-            self._insert(key)
-            if module and module != key:
-                self._insert(module)
-
-    def discard(self, key: str) -> None:
-        """Remove ``key`` from the registry and clear its warning state."""
-
-        with self.lock:
-            self.failed.pop(key, None)
-            self.warned.discard(key)
-
-    def mark_warning(self, module: str) -> bool:
-        """Mark ``module`` as warned and return ``True`` if it was new."""
-
-        with self.lock:
-            if module in self.warned:
-                return False
-            self.warned.add(module)
-            return True
-
-    def clear(self) -> None:
-        """Remove all failure records and warning markers."""
-
-        with self.lock:
-            self.failed.clear()
-            self.warned.clear()
-
-    def __contains__(self, key: str) -> bool:  # pragma: no cover - trivial
-        with self.lock:
-            return key in self.failed
-
-
-_IMPORT_STATE = ImportRegistry()
-# Public alias to ease direct introspection in tests and diagnostics.
-IMPORT_LOG = _IMPORT_STATE
-
-
-@lru_cache(maxsize=_DEFAULT_CACHE_SIZE)
-def _import_cached(module_name: str, attr: str | None) -> tuple[bool, Any]:
-    """Import ``module_name`` (and optional ``attr``) capturing failures."""
-
-    try:
-        module = importlib.import_module(module_name)
-        obj = getattr(module, attr) if attr else module
-    except (ImportError, AttributeError) as exc:
-        return False, exc
-    return True, obj
-
-
-def _warn_failure(
-    module: str,
-    attr: str | None,
-    err: Exception,
-    *,
-    emit: Literal["warn", "log", "both"] = "warn",
-) -> None:
-    """Emit a warning about a failed import."""
-
-    msg = _format_failure_message(module, attr, err)
-    if _IMPORT_STATE.mark_warning(module):
-        EMIT_MAP[emit](msg)
-    else:
-        logger.debug(msg)
-
-
-def cached_import(
-    module_name: str,
-    attr: str | None = None,
-    *,
-    fallback: Any | None = None,
-    emit: Literal["warn", "log", "both"] = "warn",
-) -> Any | None:
-    """Import ``module_name`` (and optional ``attr``) with caching and fallback.
-
-    Parameters
-    ----------
-    module_name:
-        Module to import.
-    attr:
-        Optional attribute to fetch from the module.
-    fallback:
-        Value returned when the import fails.
-    emit:
-        Destination for warnings emitted on failure (``"warn"``/``"log"``/``"both"``).
-    """
-
-    key = module_name if attr is None else f"{module_name}.{attr}"
-    success, result = _import_cached(module_name, attr)
-    if success:
-        _IMPORT_STATE.discard(key)
-        if attr is not None:
-            _IMPORT_STATE.discard(module_name)
-        return result
-    exc = result
-    include_module = isinstance(exc, ImportError)
-    _warn_failure(module_name, attr, exc, emit=emit)
-    _IMPORT_STATE.record_failure(key, module=module_name if include_module else None)
-    return fallback
-
-
-def _clear_default_cache() -> None:
-    global _NP_MISSING_LOGGED
-
-    _import_cached.cache_clear()
-    _NP_MISSING_LOGGED = False
-
-
-cached_import.cache_clear = _clear_default_cache  # type: ignore[attr-defined]
-
-
-_NP_MISSING_LOGGED = False
-
-
-def get_numpy() -> Any | None:
-    """Return the cached :mod:`numpy` module when available.
-
-    Import attempts are delegated to :func:`cached_import`, which already caches
-    successes and failures. A lightweight flag suppresses duplicate debug logs
-    when :mod:`numpy` is unavailable so callers can repeatedly probe without
-    spamming the logger.
-    """
-
-    global _NP_MISSING_LOGGED
-
-    np = cached_import("numpy")
-    if np is None:
-        if not _NP_MISSING_LOGGED:
-            logger.debug("Failed to import numpy; continuing in non-vectorised mode")
-            _NP_MISSING_LOGGED = True
-        return None
-
-    if _NP_MISSING_LOGGED:
-        _NP_MISSING_LOGGED = False
-    return np
-
-
-def get_nodonx() -> type | None:
-    """Return :class:`tnfr.node.NodoNX` using import caching."""
-
-    return cached_import("tnfr.node", "NodoNX")
-
-
-def prune_failed_imports() -> None:
-    """Clear the registry of recorded import failures and warnings."""
-
-    _IMPORT_STATE.clear()

tnfr/json_utils.py

@@ -1,162 +0,0 @@
-"""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/logging_utils.py

@@ -1,116 +0,0 @@
-"""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)