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

tnfr/cache.pyi

@@ -0,0 +1,232 @@
+import logging
+import threading
+from collections.abc import Callable, Iterable, Iterator, Mapping, MutableMapping
+from dataclasses import dataclass
+from typing import Any, ClassVar, Generic, Hashable, TypeVar
+
+from cachetools import LRUCache
+
+from .types import TimingContext
+
+__all__ = [
+    "CacheManager",
+    "CacheCapacityConfig",
+    "CacheStatistics",
+    "InstrumentedLRUCache",
+    "ManagedLRUCache",
+    "prune_lock_mapping",
+]
+
+K = TypeVar("K", bound=Hashable)
+V = TypeVar("V")
+
+
+@dataclass(frozen=True)
+class CacheCapacityConfig:
+    default_capacity: int | None
+    overrides: dict[str, int | None]
+
+
+@dataclass(frozen=True)
+class CacheStatistics:
+    hits: int = ...
+    misses: int = ...
+    evictions: int = ...
+    total_time: float = ...
+    timings: int = ...
+
+    def merge(self, other: CacheStatistics) -> CacheStatistics: ...
+
+
+class CacheManager:
+    _MISSING: ClassVar[object]
+
+    def __init__(
+        self,
+        storage: MutableMapping[str, Any] | None = ...,
+        *,
+        default_capacity: int | None = ...,
+        overrides: Mapping[str, int | None] | None = ...,
+    ) -> None: ...
+
+    @staticmethod
+    def _normalise_capacity(value: int | None) -> int | None: ...
+
+    def register(
+        self,
+        name: str,
+        factory: Callable[[], Any],
+        *,
+        lock_factory: Callable[[], threading.Lock | threading.RLock] | None = ...,
+        reset: Callable[[Any], Any] | None = ...,
+        create: bool = ...,
+    ) -> None: ...
+
+    def configure(
+        self,
+        *,
+        default_capacity: int | None | object = ...,
+        overrides: Mapping[str, int | None] | None = ...,
+        replace_overrides: bool = ...,
+    ) -> None: ...
+
+    def configure_from_mapping(self, config: Mapping[str, Any]) -> None: ...
+
+    def export_config(self) -> CacheCapacityConfig: ...
+
+    def get_capacity(
+        self,
+        name: str,
+        *,
+        requested: int | None = ...,
+        fallback: int | None = ...,
+        use_default: bool = ...,
+    ) -> int | None: ...
+
+    def has_override(self, name: str) -> bool: ...
+
+    def get_lock(self, name: str) -> threading.Lock | threading.RLock: ...
+
+    def names(self) -> Iterator[str]: ...
+
+    def get(self, name: str, *, create: bool = ...) -> Any: ...
+
+    def peek(self, name: str) -> Any: ...
+
+    def store(self, name: str, value: Any) -> None: ...
+
+    def update(
+        self,
+        name: str,
+        updater: Callable[[Any], Any],
+        *,
+        create: bool = ...,
+    ) -> Any: ...
+
+    def clear(self, name: str | None = ...) -> None: ...
+
+    def increment_hit(
+        self,
+        name: str,
+        *,
+        amount: int = ...,
+        duration: float | None = ...,
+    ) -> None: ...
+
+    def increment_miss(
+        self,
+        name: str,
+        *,
+        amount: int = ...,
+        duration: float | None = ...,
+    ) -> None: ...
+
+    def increment_eviction(self, name: str, *, amount: int = ...) -> None: ...
+
+    def record_timing(self, name: str, duration: float) -> None: ...
+
+    def timer(self, name: str) -> TimingContext: ...
+
+    def get_metrics(self, name: str) -> CacheStatistics: ...
+
+    def iter_metrics(self) -> Iterator[tuple[str, CacheStatistics]]: ...
+
+    def aggregate_metrics(self) -> CacheStatistics: ...
+
+    def register_metrics_publisher(
+        self, publisher: Callable[[str, CacheStatistics], None]
+    ) -> None: ...
+
+    def publish_metrics(
+        self,
+        *,
+        publisher: Callable[[str, CacheStatistics], None] | None = ...,
+    ) -> None: ...
+
+    def log_metrics(
+        self, logger: logging.Logger, *, level: int = ...
+    ) -> None: ...
+
+
+class InstrumentedLRUCache(MutableMapping[K, V], Generic[K, V]):
+    _MISSING: ClassVar[object]
+
+    def __init__(
+        self,
+        maxsize: int,
+        *,
+        manager: CacheManager | None = ...,
+        metrics_key: str | None = ...,
+        telemetry_callbacks: Iterable[Callable[[K, V], None]]
+        | Callable[[K, V], None]
+        | None = ...,
+        eviction_callbacks: Iterable[Callable[[K, V], None]]
+        | Callable[[K, V], None]
+        | None = ...,
+        locks: MutableMapping[K, Any] | None = ...,
+        getsizeof: Callable[[V], int] | None = ...,
+        count_overwrite_hit: bool = ...,
+    ) -> None: ...
+
+    @property
+    def telemetry_callbacks(self) -> tuple[Callable[[K, V], None], ...]: ...
+
+    @property
+    def eviction_callbacks(self) -> tuple[Callable[[K, V], None], ...]: ...
+
+    def set_telemetry_callbacks(
+        self,
+        callbacks: Iterable[Callable[[K, V], None]]
+        | Callable[[K, V], None]
+        | None,
+        *,
+        append: bool = ...,
+    ) -> None: ...
+
+    def set_eviction_callbacks(
+        self,
+        callbacks: Iterable[Callable[[K, V], None]]
+        | Callable[[K, V], None]
+        | None,
+        *,
+        append: bool = ...,
+    ) -> None: ...
+
+    def pop(self, key: K, default: Any = ...) -> V: ...
+
+    def popitem(self) -> tuple[K, V]: ...
+
+    def clear(self) -> None: ...
+
+    @property
+    def maxsize(self) -> int: ...
+
+    @property
+    def currsize(self) -> int: ...
+
+    def get(self, key: K, default: V | None = ...) -> V | None: ...
+
+
+class ManagedLRUCache(LRUCache[K, V], Generic[K, V]):
+    def __init__(
+        self,
+        maxsize: int,
+        *,
+        manager: CacheManager | None = ...,
+        metrics_key: str | None = ...,
+        eviction_callbacks: Iterable[Callable[[K, V], None]]
+        | Callable[[K, V], None]
+        | None = ...,
+        telemetry_callbacks: Iterable[Callable[[K, V], None]]
+        | Callable[[K, V], None]
+        | None = ...,
+        locks: MutableMapping[K, Any] | None = ...,
+    ) -> None: ...
+
+    def popitem(self) -> tuple[K, V]: ...
+
+
+def prune_lock_mapping(
+    cache: Mapping[K, Any] | MutableMapping[K, Any] | None,
+    locks: MutableMapping[K, Any] | None,
+) -> None: ...

tnfr/callback_utils.py

@@ -17,14 +17,13 @@ from collections.abc import Callable, Mapping, Iterable
 
 import traceback
 import threading
-from .logging_utils import get_logger
+from .utils import get_logger, is_non_string_sequence
 from .constants import DEFAULTS
 from .locking import get_lock
 
 from .trace import CallbackSpec
-from .collections_utils import is_non_string_sequence
 
-import networkx as nx  # type: ignore[import-untyped]
+import networkx as nx
 
 __all__ = (
     "CallbackEvent",
@@ -246,8 +245,6 @@ def _validate_registry(
     return cbs
 
 
-
-
 def _normalize_callbacks(entries: Any) -> dict[str, CallbackSpec]:
     """Return ``entries`` normalised into a callback mapping."""
     if isinstance(entries, Mapping):
@@ -328,7 +325,6 @@ def _normalize_callback_entry(entry: Any) -> "CallbackSpec | None":
         return None
 
 
-
 def _reconcile_callback(
     event: str,
     existing_map: dict[str, CallbackSpec],
@@ -383,6 +379,3 @@ def _reconcile_callback(
 # ---------------------------------------------------------------------------
 
 callback_manager = CallbackManager()
-
-
-

tnfr/callback_utils.pyi

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import threading
+import traceback
+from collections import defaultdict, deque
+from collections.abc import Callable, Iterable, Mapping
+from enum import Enum
+from typing import Any, TypedDict
+
+import networkx as nx
+
+from .constants import DEFAULTS
+from .locking import get_lock
+from .trace import CallbackSpec
+from .utils import get_logger, is_non_string_sequence
+
+__all__ = (
+    "CallbackEvent",
+    "CallbackManager",
+    "callback_manager",
+    "CallbackError",
+)
+
+logger: Any
+
+
+class CallbackEvent(str, Enum):
+    BEFORE_STEP = "before_step"
+    AFTER_STEP = "after_step"
+    ON_REMESH = "on_remesh"
+
+
+Callback = Callable[[nx.Graph, dict[str, Any]], None]
+CallbackRegistry = dict[str, dict[str, CallbackSpec]]
+
+
+class CallbackError(TypedDict):
+    event: str
+    step: int | None
+    error: str
+    traceback: str
+    fn: str
+    name: str | None
+
+
+class CallbackManager:
+    def __init__(self) -> None: ...
+
+    def get_callback_error_limit(self) -> int: ...
+
+    def set_callback_error_limit(self, limit: int) -> int: ...
+
+    def register_callback(
+        self,
+        G: nx.Graph,
+        event: CallbackEvent | str,
+        func: Callback,
+        *,
+        name: str | None = ...,
+    ) -> Callback: ...
+
+    def invoke_callbacks(
+        self,
+        G: nx.Graph,
+        event: CallbackEvent | str,
+        ctx: dict[str, Any] | None = ...,
+    ) -> None: ...
+
+    def _record_callback_error(
+        self,
+        G: nx.Graph,
+        event: str,
+        ctx: dict[str, Any],
+        spec: CallbackSpec,
+        err: Exception,
+    ) -> None: ...
+
+    def _ensure_callbacks_nolock(self, G: nx.Graph) -> CallbackRegistry: ...
+
+    def _ensure_callbacks(self, G: nx.Graph) -> CallbackRegistry: ...
+
+
+callback_manager: CallbackManager
+
+
+def _func_id(fn: Callable[..., Any]) -> str: ...
+
+def _validate_registry(G: nx.Graph, cbs: Any, dirty: set[str]) -> CallbackRegistry: ...
+
+def _normalize_callbacks(entries: Any) -> dict[str, CallbackSpec]: ...
+
+def _normalize_event(event: CallbackEvent | str) -> str: ...
+
+def _is_known_event(event: str) -> bool: ...
+
+def _ensure_known_event(event: str) -> None: ...
+
+def _normalize_callback_entry(entry: Any) -> CallbackSpec | None: ...
+
+def _reconcile_callback(
+    event: str,
+    existing_map: dict[str, CallbackSpec],
+    spec: CallbackSpec,
+    strict: bool,
+) -> str: ...

tnfr/cli/__init__.py

@@ -22,8 +22,8 @@ from .execution import (
     run_program,
     resolve_program,
 )
-from ..logging_utils import get_logger
 from .. import __version__
+from ..utils import _configure_root, get_logger
 
 logger = get_logger(__name__)
 
@@ -43,21 +43,35 @@ __all__ = (
 
 
 def main(argv: Optional[list[str]] = None) -> int:
-    logging.basicConfig(
-        level=logging.INFO, format="%(message)s", stream=sys.stdout, force=True
-    )
+    _configure_root()
+
+    root = logging.getLogger()
+    root.setLevel(logging.INFO)
+
+    formatter = logging.Formatter("%(message)s")
+    for handler in list(root.handlers):
+        root.removeHandler(handler)
+
+    handler = logging.StreamHandler(stream=sys.stdout)
+    handler.setLevel(logging.INFO)
+    handler.setFormatter(formatter)
+    root.addHandler(handler)
 
     p = argparse.ArgumentParser(
         prog="tnfr",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog=(
-            "Ejemplo: tnfr sequence --sequence-file secuencia.json\n"
-            "secuencia.json:\n"
+            "Example: tnfr sequence --sequence-file sequence.json\n"
+            "sequence.json:\n"
             '[\n  {"WAIT": 1},\n  {"TARGET": "A"}\n]'
         ),
     )
     p.add_argument(
-        "--version", action="store_true", help="muestra versión y sale"
+        "--version",
+        action="store_true",
+        help=(
+            "show the actual version and exit (reads pyproject.toml in development)"
+        ),
     )
     sub = p.add_subparsers(dest="cmd")
 

tnfr/cli/__init__.pyi

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import argparse
+from typing import Optional
+
+from ..types import ProgramTokens, TNFRGraph
+
+__all__: tuple[str, ...]
+
+
+def main(argv: Optional[list[str]] = None) -> int: ...
+
+
+def add_common_args(parser: argparse.ArgumentParser) -> None: ...
+
+
+def add_grammar_args(parser: argparse.ArgumentParser) -> None: ...
+
+
+def add_grammar_selector_args(parser: argparse.ArgumentParser) -> None: ...
+
+
+def add_history_export_args(parser: argparse.ArgumentParser) -> None: ...
+
+
+def add_canon_toggle(parser: argparse.ArgumentParser) -> None: ...
+
+
+def build_basic_graph(args: argparse.Namespace) -> TNFRGraph: ...
+
+
+def apply_cli_config(G: TNFRGraph, args: argparse.Namespace) -> None: ...
+
+
+def register_callbacks_and_observer(G: TNFRGraph) -> None: ...
+
+
+def resolve_program(
+    args: argparse.Namespace, default: Optional[ProgramTokens] = None
+) -> Optional[ProgramTokens]: ...
+
+
+def run_program(
+    G: Optional[TNFRGraph],
+    program: Optional[ProgramTokens],
+    args: argparse.Namespace,
+) -> TNFRGraph: ...

tnfr/cli/arguments.py

@@ -1,13 +1,23 @@
 from __future__ import annotations
 
 import argparse
-from typing import Any
+from typing import Any, Iterable
 
+from ..config.presets import PREFERRED_PRESET_NAMES
 from ..gamma import GAMMA_REGISTRY
+from ..telemetry.verbosity import TELEMETRY_VERBOSITY_LEVELS
+from ..types import ArgSpec
 from .utils import spec
 
 
-GRAMMAR_ARG_SPECS = (
+_PRESET_HELP = "Available presets: {}.".format(
+    ", ".join(PREFERRED_PRESET_NAMES),
+)
+
+TELEMETRY_VERBOSITY_CHOICES = TELEMETRY_VERBOSITY_LEVELS
+
+
+GRAMMAR_ARG_SPECS: tuple[ArgSpec, ...] = (
     spec("--grammar.enabled", action=argparse.BooleanOptionalAction),
     spec("--grammar.zhir_requires_oz_window", type=int),
     spec("--grammar.zhir_dnfr_min", type=float),
@@ -19,25 +29,35 @@ GRAMMAR_ARG_SPECS = (
 )
 
 
-# Especificaciones para opciones relacionadas con el histórico
-HISTORY_ARG_SPECS = (
+# History export/save specifications
+HISTORY_ARG_SPECS: tuple[ArgSpec, ...] = (
     spec("--save-history", type=str),
     spec("--export-history-base", type=str),
     spec("--export-format", choices=["csv", "json"], default="json"),
 )
 
 
-# Argumentos comunes a los subcomandos
-COMMON_ARG_SPECS = (
+# Arguments shared by CLI subcommands
+COMMON_ARG_SPECS: tuple[ArgSpec, ...] = (
     spec("--nodes", type=int, default=24),
     spec("--topology", choices=["ring", "complete", "erdos"], default="ring"),
     spec("--seed", type=int, default=1),
     spec(
         "--p",
         type=float,
-        help="Probabilidad de arista si topology=erdos",
+        help="Edge probability when topology=erdos",
+    ),
+    spec("--observer", action="store_true", help="Attach standard observer"),
+    spec(
+        "--trace-verbosity",
+        choices=TELEMETRY_VERBOSITY_CHOICES,
+        help="Select the trace capture preset",
+    ),
+    spec(
+        "--metrics-verbosity",
+        choices=TELEMETRY_VERBOSITY_CHOICES,
+        help="Select the metrics capture preset",
     ),
-    spec("--observer", action="store_true", help="Adjunta observador estándar"),
     spec("--config", type=str),
     spec("--dt", type=float),
     spec("--integrator", choices=["euler", "rk4"]),
@@ -48,7 +68,9 @@ COMMON_ARG_SPECS = (
 )
 
 
-def add_arg_specs(parser: argparse._ActionsContainer, specs) -> None:
+def add_arg_specs(
+    parser: argparse._ActionsContainer, specs: Iterable[ArgSpec]
+) -> None:
     """Register arguments from ``specs`` on ``parser``."""
     for opt, kwargs in specs:
         parser.add_argument(opt, **kwargs)
@@ -94,7 +116,7 @@ def add_canon_toggle(parser: argparse.ArgumentParser) -> None:
         dest="grammar_canon",
         action="store_false",
         default=True,
-        help="Desactiva gramática canónica",
+        help="Disable canonical grammar",
     )
 
 
@@ -105,7 +127,7 @@ def _add_run_parser(sub: argparse._SubParsersAction) -> None:
     p_run = sub.add_parser(
         "run",
         help=(
-            "Correr escenario libre o preset y opcionalmente exportar history"
+            "Run a free scenario or preset and optionally export history"
         ),
     )
     add_common_args(p_run)
@@ -113,7 +135,7 @@ def _add_run_parser(sub: argparse._SubParsersAction) -> None:
     add_canon_toggle(p_run)
     add_grammar_selector_args(p_run)
     add_history_export_args(p_run)
-    p_run.add_argument("--preset", type=str, default=None)
+    p_run.add_argument("--preset", type=str, default=None, help=_PRESET_HELP)
     p_run.add_argument("--sequence-file", type=str, default=None)
     p_run.add_argument("--summary", action="store_true")
     p_run.add_argument(
@@ -121,8 +143,8 @@ def _add_run_parser(sub: argparse._SubParsersAction) -> None:
         type=int,
         default=DEFAULT_SUMMARY_SERIES_LIMIT,
         help=(
-            "Número máximo de muestras por serie en el resumen (<=0 para"
-            " desactivar el recorte)"
+            "Maximum number of samples per series in the summary (<=0 to"
+            " disable trimming)"
         ),
     )
     p_run.set_defaults(func=cmd_run)
@@ -134,10 +156,10 @@ def _add_sequence_parser(sub: argparse._SubParsersAction) -> None:
 
     p_seq = sub.add_parser(
         "sequence",
-        help="Ejecutar una secuencia (preset o YAML/JSON)",
+        help="Execute a sequence (preset or YAML/JSON)",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog=(
-            "Ejemplo de secuencia JSON:\n"
+            "JSON sequence example:\n"
             "[\n"
             '  "A",\n'
             '  {"WAIT": 1},\n'
@@ -146,7 +168,7 @@ def _add_sequence_parser(sub: argparse._SubParsersAction) -> None:
         ),
     )
     add_common_args(p_seq)
-    p_seq.add_argument("--preset", type=str, default=None)
+    p_seq.add_argument("--preset", type=str, default=None, help=_PRESET_HELP)
     p_seq.add_argument("--sequence-file", type=str, default=None)
     add_history_export_args(p_seq)
     add_grammar_args(p_seq)
@@ -158,7 +180,7 @@ def _add_metrics_parser(sub: argparse._SubParsersAction) -> None:
     from .execution import cmd_metrics
 
     p_met = sub.add_parser(
-        "metrics", help="Correr breve y volcar métricas clave"
+        "metrics", help="Run briefly and export key metrics"
     )
     add_common_args(p_met)
     p_met.add_argument("--steps", type=int, default=None)
@@ -170,8 +192,8 @@ def _add_metrics_parser(sub: argparse._SubParsersAction) -> None:
         type=int,
         default=None,
         help=(
-            "Número máximo de muestras por serie en el resumen (<=0 para"
-            " desactivar el recorte)"
+            "Maximum number of samples per series in the summary (<=0 to"
+            " disable trimming)"
         ),
     )
     p_met.set_defaults(func=cmd_metrics)

tnfr/cli/arguments.pyi

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import argparse
+from typing import Any, Iterable
+
+from ..gamma import GAMMA_REGISTRY
+from ..types import ArgSpec
+from .utils import spec
+
+GRAMMAR_ARG_SPECS: tuple[ArgSpec, ...]
+HISTORY_ARG_SPECS: tuple[ArgSpec, ...]
+COMMON_ARG_SPECS: tuple[ArgSpec, ...]
+
+
+def add_arg_specs(parser: argparse._ActionsContainer, specs: Iterable[ArgSpec]) -> None: ...
+
+def _args_to_dict(args: argparse.Namespace, prefix: str) -> dict[str, Any]: ...
+
+def add_common_args(parser: argparse.ArgumentParser) -> None: ...
+
+def add_grammar_args(parser: argparse.ArgumentParser) -> None: ...
+
+def add_grammar_selector_args(parser: argparse.ArgumentParser) -> None: ...
+
+def add_history_export_args(parser: argparse.ArgumentParser) -> None: ...
+
+def add_canon_toggle(parser: argparse.ArgumentParser) -> None: ...
+
+def _add_run_parser(sub: argparse._SubParsersAction) -> None: ...
+
+def _add_sequence_parser(sub: argparse._SubParsersAction) -> None: ...
+
+def _add_metrics_parser(sub: argparse._SubParsersAction) -> None: ...