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

tnfr/cache.pyi

@@ -1,232 +1,16 @@
-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
+"""Compatibility stub removed; import from :mod:`tnfr.utils.cache` instead."""
 
-from cachetools import LRUCache
+from __future__ import annotations
 
-from .types import TimingContext
+from typing import NoReturn
 
-__all__ = [
-    "CacheManager",
-    "CacheCapacityConfig",
-    "CacheStatistics",
-    "InstrumentedLRUCache",
-    "ManagedLRUCache",
-    "prune_lock_mapping",
-]
+__all__ = ()
 
-K = TypeVar("K", bound=Hashable)
-V = TypeVar("V")
 
+def __getattr__(name: str) -> NoReturn:
+    """Indicate that :mod:`tnfr.cache` no longer exports cache helpers."""
 
-@dataclass(frozen=True)
-class CacheCapacityConfig:
-    default_capacity: int | None
-    overrides: dict[str, int | None]
 
+def __dir__() -> tuple[str, ...]:
+    """Return an empty set of exports to mirror the removed shim."""
 
-@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

@@ -9,21 +9,20 @@ modify shared state.
 
 from __future__ import annotations
 
-
-from typing import Any, TypedDict
-from enum import Enum
+import threading
+import traceback
 from collections import defaultdict, deque
-from collections.abc import Callable, Mapping, Iterable
+from collections.abc import Callable, Iterable, Mapping
+from enum import Enum
+from typing import Any
+
+import networkx as nx
 
-import traceback
-import threading
-from .utils import get_logger, is_non_string_sequence
 from .constants import DEFAULTS
 from .locking import get_lock
-
 from .trace import CallbackSpec
-
-import networkx as nx
+from .utils import get_logger, is_non_string_sequence
+from .types import CallbackError
 
 __all__ = (
     "CallbackEvent",
@@ -41,6 +40,7 @@ class CallbackEvent(str, Enum):
     BEFORE_STEP = "before_step"
     AFTER_STEP = "after_step"
     ON_REMESH = "on_remesh"
+    CACHE_METRICS = "cache_metrics"
 
 
 class CallbackManager:
@@ -130,9 +130,7 @@ class CallbackManager:
             cb_name = name or getattr(func, "__name__", None)
             spec = CallbackSpec(cb_name, func)
             existing_map = cbs[event]
-            strict = bool(
-                G.graph.get("CALLBACKS_STRICT", DEFAULTS["CALLBACKS_STRICT"])
-            )
+            strict = bool(G.graph.get("CALLBACKS_STRICT", DEFAULTS["CALLBACKS_STRICT"]))
             key = _reconcile_callback(event, existing_map, spec, strict)
 
             existing_map[key] = spec
@@ -151,9 +149,7 @@ class CallbackManager:
         event = _normalize_event(event)
         with self._lock:
             cbs = dict(self._ensure_callbacks_nolock(G).get(event, {}))
-            strict = bool(
-                G.graph.get("CALLBACKS_STRICT", DEFAULTS["CALLBACKS_STRICT"])
-            )
+            strict = bool(G.graph.get("CALLBACKS_STRICT", DEFAULTS["CALLBACKS_STRICT"]))
         if ctx is None:
             ctx = {}
         for spec in cbs.values():
@@ -184,17 +180,6 @@ Callback = Callable[["nx.Graph", dict[str, Any]], None]
 CallbackRegistry = dict[str, dict[str, "CallbackSpec"]]
 
 
-class CallbackError(TypedDict):
-    """Metadata for a failed callback invocation."""
-
-    event: str
-    step: int | None
-    error: str
-    traceback: str
-    fn: str
-    name: str | None
-
-
 def _func_id(fn: Callable[..., Any]) -> str:
     """Return a deterministic identifier for ``fn``.
 
@@ -210,9 +195,7 @@ def _func_id(fn: Callable[..., Any]) -> str:
     return f"{module}.{qualname}"
 
 
-def _validate_registry(
-    G: "nx.Graph", cbs: Any, dirty: set[str]
-) -> CallbackRegistry:
+def _validate_registry(G: "nx.Graph", cbs: Any, dirty: set[str]) -> CallbackRegistry:
     """Validate and normalise the callback registry.
 
     ``cbs`` is coerced to a ``defaultdict(dict)`` and any events listed in
@@ -249,7 +232,9 @@ def _normalize_callbacks(entries: Any) -> dict[str, CallbackSpec]:
     """Return ``entries`` normalised into a callback mapping."""
     if isinstance(entries, Mapping):
         entries_iter = entries.values()
-    elif isinstance(entries, Iterable) and not isinstance(entries, (str, bytes, bytearray)):
+    elif isinstance(entries, Iterable) and not isinstance(
+        entries, (str, bytes, bytearray)
+    ):
         entries_iter = entries
     else:
         return {}

tnfr/callback_utils.pyi

@@ -5,13 +5,14 @@ import traceback
 from collections import defaultdict, deque
 from collections.abc import Callable, Iterable, Mapping
 from enum import Enum
-from typing import Any, TypedDict
+from typing import Any
 
 import networkx as nx
 
 from .constants import DEFAULTS
 from .locking import get_lock
 from .trace import CallbackSpec
+from .types import CallbackError
 from .utils import get_logger, is_non_string_sequence
 
 __all__ = (
@@ -23,33 +24,19 @@ __all__ = (
 
 logger: Any
 
-
 class CallbackEvent(str, Enum):
     BEFORE_STEP = "before_step"
     AFTER_STEP = "after_step"
     ON_REMESH = "on_remesh"
-
+    CACHE_METRICS = "cache_metrics"
 
 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,
@@ -58,14 +45,12 @@ class CallbackManager:
         *,
         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,
@@ -74,29 +59,18 @@ class CallbackManager:
         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],

tnfr/cli/__init__.py

@@ -1,3 +1,5 @@
+"""Command-line interface entry points for TNFR."""
+
 from __future__ import annotations
 
 import argparse
@@ -5,25 +7,27 @@ import logging
 import sys
 from typing import Optional
 
+from .. import __version__
+from ..utils import _configure_root, get_logger
 from .arguments import (
+    _add_metrics_parser,
+    _add_profile_parser,
+    _add_profile_pipeline_parser,
+    _add_run_parser,
+    _add_sequence_parser,
+    add_canon_toggle,
     add_common_args,
     add_grammar_args,
     add_grammar_selector_args,
     add_history_export_args,
-    add_canon_toggle,
-    _add_run_parser,
-    _add_sequence_parser,
-    _add_metrics_parser,
 )
 from .execution import (
-    build_basic_graph,
     apply_cli_config,
+    build_basic_graph,
     register_callbacks_and_observer,
-    run_program,
     resolve_program,
+    run_program,
 )
-from .. import __version__
-from ..utils import _configure_root, get_logger
 
 logger = get_logger(__name__)
 
@@ -43,6 +47,8 @@ __all__ = (
 
 
 def main(argv: Optional[list[str]] = None) -> int:
+    """Entry point for the ``tnfr`` CLI returning the exit status."""
+
     _configure_root()
 
     root = logging.getLogger()
@@ -69,15 +75,15 @@ def main(argv: Optional[list[str]] = None) -> int:
     p.add_argument(
         "--version",
         action="store_true",
-        help=(
-            "show the actual version and exit (reads pyproject.toml in development)"
-        ),
+        help=("show the actual version and exit (reads pyproject.toml in development)"),
     )
     sub = p.add_subparsers(dest="cmd")
 
     _add_run_parser(sub)
     _add_sequence_parser(sub)
     _add_metrics_parser(sub)
+    _add_profile_parser(sub)
+    _add_profile_pipeline_parser(sub)
 
     args = p.parse_args(argv)
     if args.version:

tnfr/cli/__init__.pyi

@@ -7,39 +7,18 @@ 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],