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

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)

tnfr/presets.py

@@ -1,60 +0,0 @@
-"""Predefined configurations."""
-
-from __future__ import annotations
-from .execution import (
-    CANONICAL_PRESET_NAME,
-    CANONICAL_PROGRAM_TOKENS,
-    block,
-    seq,
-    wait,
-)
-from .types import Glyph
-
-__all__ = ("get_preset",)
-
-
-_PRESETS = {
-    "arranque_resonante": seq(
-        Glyph.AL,
-        Glyph.EN,
-        Glyph.IL,
-        Glyph.RA,
-        Glyph.VAL,
-        Glyph.UM,
-        wait(3),
-        Glyph.SHA,
-    ),
-    "mutacion_contenida": seq(
-        Glyph.AL,
-        Glyph.EN,
-        block(Glyph.OZ, Glyph.ZHIR, Glyph.IL, repeat=2),
-        Glyph.RA,
-        Glyph.SHA,
-    ),
-    "exploracion_acople": seq(
-        Glyph.AL,
-        Glyph.EN,
-        Glyph.IL,
-        Glyph.VAL,
-        Glyph.UM,
-        block(Glyph.OZ, Glyph.NAV, Glyph.IL, repeat=1),
-        Glyph.RA,
-        Glyph.SHA,
-    ),
-    CANONICAL_PRESET_NAME: list(CANONICAL_PROGRAM_TOKENS),
-    # Topologías fractales: expansión/contracción modular
-    "fractal_expand": seq(
-        block(Glyph.THOL, Glyph.VAL, Glyph.UM, repeat=2, close=Glyph.NUL),
-        Glyph.RA,
-    ),
-    "fractal_contract": seq(
-        block(Glyph.THOL, Glyph.NUL, Glyph.UM, repeat=2, close=Glyph.SHA),
-        Glyph.RA,
-    ),
-}
-
-
-def get_preset(name: str):
-    if name not in _PRESETS:
-        raise KeyError(f"Preset no encontrado: {name}")
-    return _PRESETS[name]

tnfr/validators.py

@@ -1,84 +0,0 @@
-"""Validation utilities."""
-
-from __future__ import annotations
-
-import numbers
-import sys
-
-from .constants import get_aliases, get_param
-from .alias import get_attr
-from .sense import sigma_vector_from_graph
-from .helpers.numeric import within_range
-from .constants_glyphs import GLYPHS_CANONICAL_SET
-
-ALIAS_EPI = get_aliases("EPI")
-ALIAS_VF = get_aliases("VF")
-
-__all__ = ("validate_window", "run_validators")
-
-
-def validate_window(window: int, *, positive: bool = False) -> int:
-    """Validate ``window`` as an ``int`` and return it.
-
-    Non-integer values raise :class:`TypeError`. When ``positive`` is ``True``
-    the value must be strictly greater than zero; otherwise it may be zero.
-    Negative values always raise :class:`ValueError`.
-    """
-
-    if isinstance(window, bool) or not isinstance(window, numbers.Integral):
-        raise TypeError("'window' must be an integer")
-    if window < 0 or (positive and window == 0):
-        kind = "positive" if positive else "non-negative"
-        raise ValueError(f"'window'={window} must be {kind}")
-    return int(window)
-
-
-def _require_attr(data, alias, node, name):
-    """Return attribute value or raise if missing."""
-    val = get_attr(data, alias, None)
-    if val is None:
-        raise ValueError(f"Missing {name} attribute in node {node}")
-    return val
-
-
-def _validate_sigma(G) -> None:
-    sv = sigma_vector_from_graph(G)
-    if sv.get("mag", 0.0) > 1.0 + sys.float_info.epsilon:
-        raise ValueError("σ norm exceeds 1")
-
-
-def _check_epi_vf(epi, vf, epi_min, epi_max, vf_min, vf_max, n):
-    _check_range(epi, epi_min, epi_max, "EPI", n)
-    _check_range(vf, vf_min, vf_max, "VF", n)
-
-
-def _out_of_range_msg(name, node, val):
-    return f"{name} out of range in node {node}: {val}"
-
-
-def _check_range(val, lower, upper, name, node, tol: float = 1e-9):
-    if not within_range(val, lower, upper, tol):
-        raise ValueError(_out_of_range_msg(name, node, val))
-
-
-def _check_glyph(g, n):
-    if g and g not in GLYPHS_CANONICAL_SET:
-        raise KeyError(f"Invalid glyph {g} in node {n}")
-
-
-def run_validators(G) -> None:
-    """Run all invariant validators on ``G`` with a single node pass."""
-    from .glyph_history import last_glyph
-
-    epi_min = float(get_param(G, "EPI_MIN"))
-    epi_max = float(get_param(G, "EPI_MAX"))
-    vf_min = float(get_param(G, "VF_MIN"))
-    vf_max = float(get_param(G, "VF_MAX"))
-
-    for n, data in G.nodes(data=True):
-        epi = _require_attr(data, ALIAS_EPI, n, "EPI")
-        vf = _require_attr(data, ALIAS_VF, n, "VF")
-        _check_epi_vf(epi, vf, epi_min, epi_max, vf_min, vf_max, n)
-        _check_glyph(last_glyph(data), n)
-
-    _validate_sigma(G)

tnfr/value_utils.py

@@ -1,59 +0,0 @@
-"""Conversion helpers with logging for value normalisation.
-
-Wraps conversion callables to standardise error handling and logging.
-"""
-
-from __future__ import annotations
-
-from typing import Any, Callable, TypeVar
-import logging
-from .logging_utils import get_logger
-
-T = TypeVar("T")
-
-logger = get_logger(__name__)
-
-__all__ = ("convert_value",)
-
-
-def convert_value(
-    value: Any,
-    conv: Callable[[Any], T],
-    *,
-    strict: bool = False,
-    key: str | None = None,
-    log_level: int | None = None,
-) -> tuple[bool, T | None]:
-    """Attempt to convert a value and report failures.
-
-    Parameters
-    ----------
-    value : Any
-        Input value to convert.
-    conv : Callable[[Any], T]
-        Callable performing the conversion.
-    strict : bool, optional
-        Raise exceptions directly instead of logging them. Defaults to ``False``.
-    key : str, optional
-        Name associated with the value for logging context.
-    log_level : int, optional
-        Logging level used when reporting failures. Defaults to
-        ``logging.DEBUG``.
-
-    Returns
-    -------
-    tuple[bool, T | None]
-        ``(True, result)`` on success or ``(False, None)`` when conversion
-        fails.
-    """
-    try:
-        return True, conv(value)
-    except (ValueError, TypeError) as exc:
-        if strict:
-            raise
-        level = log_level if log_level is not None else logging.DEBUG
-        if key is not None:
-            logger.log(level, "Could not convert value for %r: %s", key, exc)
-        else:
-            logger.log(level, "Could not convert value: %s", exc)
-        return False, None