regscope 0.1.0__py3-none-any.whl

regscope/__init__.py

@@ -0,0 +1,6 @@
+"""RegScope: observed behavioral profiles for Python functions."""
+
+from .api import TrackConfig, track
+
+__all__ = ["TrackConfig", "__version__", "track"]
+__version__ = "0.1.0.dev1"

regscope/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

regscope/api/__init__.py

@@ -0,0 +1,6 @@
+"""Public RegScope APIs."""
+
+from .decorators import track
+from .config import TrackConfig
+
+__all__ = ["TrackConfig", "track"]

regscope/api/collectors.py

@@ -0,0 +1,50 @@
+"""Optional collector lifecycle for tracked executions."""
+
+from __future__ import annotations
+
+from contextlib import ExitStack, contextmanager
+from typing import Any, Dict, Iterator
+
+from ..collectors import HTTPCollector, MemoryCollector, RedisCollector, SQLAlchemyCollector
+from .config import TrackConfig
+
+
+@contextmanager
+def active_collectors(config: TrackConfig, metrics: Dict[str, int]) -> Iterator[None]:
+    """Attach configured collectors and publish their metrics on exit."""
+    with ExitStack() as stack:
+        if config.sqlalchemy_engine is not None:
+            collector = SQLAlchemyCollector()
+            collector.attach(config.sqlalchemy_engine)
+            stack.callback(collector.detach)
+            metrics["db_queries"] = 0
+            stack.callback(lambda: metrics.update(db_queries=collector.query_count))
+
+        if config.collect_http:
+            collector = HTTPCollector()
+            collector.attach()
+            stack.callback(collector.detach)
+            metrics["http_requests"] = 0
+            stack.callback(lambda: metrics.update(http_requests=collector.request_count))
+
+        if config.collect_redis:
+            collector = RedisCollector()
+            collector.attach()
+            stack.callback(collector.detach)
+            metrics["redis_commands"] = 0
+            stack.callback(lambda: metrics.update(redis_commands=collector.command_count))
+
+        memory = None
+        if config.collect_memory:
+            memory = MemoryCollector()
+            stack.callback(
+                lambda: metrics.update(
+                    memory_current_delta=memory.last_profile.current_delta,
+                    memory_peak=memory.last_profile.peak,
+                )
+                if memory.last_profile is not None
+                else None
+            )
+            stack.enter_context(memory.measure())
+
+        yield

regscope/api/config.py

@@ -0,0 +1,27 @@
+"""Validated public configuration for tracked functions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from os import PathLike
+from typing import Any, Union
+
+
+@dataclass(frozen=True)
+class TrackConfig:
+    """Configuration shared by a tracked function's collectors and storage."""
+
+    baseline_dir: Union[PathLike[str], str] = ".regscope"
+    history_dir: Union[PathLike[str], str] = ".regscope"
+    max_runs: int = 5
+    warmup_runs: int = 0
+    sqlalchemy_engine: Any = None
+    collect_http: bool = False
+    collect_redis: bool = False
+    collect_memory: bool = False
+
+    def __post_init__(self) -> None:
+        if self.max_runs < 1:
+            raise ValueError("max_runs must be at least 1")
+        if self.warmup_runs < 0:
+            raise ValueError("warmup_runs must not be negative")

regscope/api/decorators.py

@@ -0,0 +1,227 @@
+"""Decorators for collecting observed function behavior."""
+
+from __future__ import annotations
+
+import time
+from contextvars import ContextVar
+from inspect import iscoroutinefunction
+from functools import wraps
+from os import PathLike
+from typing import Any, Callable, Optional, TypeVar, Union, cast
+from threading import Lock
+
+from ..collectors.call_graph import collect_async_call_graph, collect_call_graph
+from ..core.comparison import ComparisonResult, compare
+from ..models import BehaviorProfile
+from ..storage import BaselineStore
+from ..trends import HistoryStore
+from .config import TrackConfig
+from .collectors import active_collectors
+
+
+T = TypeVar("T")
+Function = Callable[..., T]
+
+
+def track(
+    function: Optional[Function[T]] = None,
+    *,
+    baseline_dir: Union[PathLike[str], str] = ".regscope",
+    history_dir: Union[PathLike[str], str] = ".regscope",
+    max_runs: int = 5,
+    warmup_runs: int = 0,
+    sqlalchemy_engine: Any = None,
+    collect_http: bool = False,
+    collect_redis: bool = False,
+    collect_memory: bool = False,
+) -> Any:
+    """Decorate a function with runtime collection and baseline persistence."""
+    config = TrackConfig(
+        baseline_dir=baseline_dir,
+        history_dir=history_dir,
+        max_runs=max_runs,
+        warmup_runs=warmup_runs,
+        sqlalchemy_engine=sqlalchemy_engine,
+        collect_http=collect_http,
+        collect_redis=collect_redis,
+        collect_memory=collect_memory,
+    )
+    if function is None:
+        return lambda wrapped: track(
+            wrapped,
+            baseline_dir=config.baseline_dir,
+            history_dir=config.history_dir,
+            max_runs=config.max_runs,
+            warmup_runs=config.warmup_runs,
+            sqlalchemy_engine=config.sqlalchemy_engine,
+            collect_http=config.collect_http,
+            collect_redis=config.collect_redis,
+            collect_memory=config.collect_memory,
+        )
+
+    if iscoroutinefunction(function):
+        return _track_async(function, config)
+
+    store = BaselineStore(config.baseline_dir, max_runs=config.max_runs)
+    history = HistoryStore(config.history_dir)
+    current_profile: ContextVar[Optional[BehaviorProfile]] = ContextVar(
+        "regscope_current_profile", default=None
+    )
+    current_comparison: ContextVar[Any] = ContextVar(
+        "regscope_current_comparison", default=None
+    )
+    warmups_remaining = config.warmup_runs
+    warmup_lock = Lock()
+
+    def consume_warmup() -> bool:
+        nonlocal warmups_remaining
+        with warmup_lock:
+            if warmups_remaining == 0:
+                return False
+            warmups_remaining -= 1
+            return True
+
+    @wraps(function)
+    def wrapper(*args: Any, **kwargs: Any) -> T:
+        started = time.perf_counter_ns()
+        exception_count = 0
+        failure: Optional[BaseException] = None
+        graph = {}
+        metrics = {}
+        try:
+            try:
+                with active_collectors(config, metrics):
+                    try:
+                        result, graph = collect_call_graph(function, *args, **kwargs)
+                        return result
+                    except BaseException as error:
+                        failure = error
+                        raise
+            except BaseException as error:
+                if failure is None:
+                    failure = error
+                    raise
+                if failure is not None and error is not failure:
+                    raise failure from error
+                raise
+        except BaseException as error:
+            exception_count = 1
+            failure = error
+            raise
+        finally:
+            try:
+                wrapper.last_profile = BehaviorProfile(
+                    function=f"{function.__module__}.{function.__qualname__}",
+                    duration_ns=time.perf_counter_ns() - started,
+                    exceptions=exception_count,
+                    call_graph=graph,
+                    metrics=metrics,
+                )
+                current_profile.set(wrapper.last_profile)
+                if consume_warmup():
+                    wrapper.last_comparison = ComparisonResult(
+                        function=wrapper.last_profile.function,
+                        metrics=[],
+                        status="warmup",
+                    )
+                else:
+                    wrapper.last_comparison = compare(
+                        wrapper.last_profile, store.load(wrapper.last_profile.function)
+                    )
+                current_comparison.set(wrapper.last_comparison)
+                if wrapper.last_comparison.status != "warmup":
+                    store.append(wrapper.last_profile)
+                    history.record(wrapper.last_profile)
+            except BaseException:
+                if failure is None:
+                    raise
+
+    wrapper.last_profile = None  # type: ignore[attr-defined]
+    wrapper.last_comparison = None  # type: ignore[attr-defined]
+    wrapper.get_current_profile = current_profile.get  # type: ignore[attr-defined]
+    wrapper.get_current_comparison = current_comparison.get  # type: ignore[attr-defined]
+    return cast(Function[T], wrapper)
+
+
+def _track_async(
+    function: Function[T], config: TrackConfig
+) -> Any:
+    store = BaselineStore(config.baseline_dir, max_runs=config.max_runs)
+    history = HistoryStore(config.history_dir)
+    current_profile: ContextVar[Optional[BehaviorProfile]] = ContextVar(
+        "regscope_current_profile", default=None
+    )
+    current_comparison: ContextVar[Any] = ContextVar(
+        "regscope_current_comparison", default=None
+    )
+    warmups_remaining = config.warmup_runs
+    warmup_lock = Lock()
+
+    def consume_warmup() -> bool:
+        nonlocal warmups_remaining
+        with warmup_lock:
+            if warmups_remaining == 0:
+                return False
+            warmups_remaining -= 1
+            return True
+
+    @wraps(function)
+    async def wrapper(*args: Any, **kwargs: Any) -> T:
+        started = time.perf_counter_ns()
+        exception_count = 0
+        failure: Optional[BaseException] = None
+        graph = {}
+        metrics = {}
+        try:
+            try:
+                with active_collectors(config, metrics):
+                    try:
+                        result, graph = await collect_async_call_graph(function, *args, **kwargs)
+                        return result
+                    except BaseException as error:
+                        failure = error
+                        raise
+            except BaseException as error:
+                if failure is None:
+                    failure = error
+                    raise
+                if failure is not None and error is not failure:
+                    raise failure from error
+                raise
+        except BaseException as error:
+            exception_count = 1
+            failure = error
+            raise
+        finally:
+            try:
+                wrapper.last_profile = BehaviorProfile(
+                    function=f"{function.__module__}.{function.__qualname__}",
+                    duration_ns=time.perf_counter_ns() - started,
+                    exceptions=exception_count,
+                    call_graph=graph,
+                    metrics=metrics,
+                )
+                current_profile.set(wrapper.last_profile)
+                if consume_warmup():
+                    wrapper.last_comparison = ComparisonResult(
+                        function=wrapper.last_profile.function,
+                        metrics=[],
+                        status="warmup",
+                    )
+                else:
+                    wrapper.last_comparison = compare(
+                        wrapper.last_profile, store.load(wrapper.last_profile.function)
+                    )
+                current_comparison.set(wrapper.last_comparison)
+                if wrapper.last_comparison.status != "warmup":
+                    store.append(wrapper.last_profile)
+                    history.record(wrapper.last_profile)
+            except BaseException:
+                if failure is None:
+                    raise
+
+    wrapper.last_profile = None  # type: ignore[attr-defined]
+    wrapper.last_comparison = None  # type: ignore[attr-defined]
+    wrapper.get_current_profile = current_profile.get  # type: ignore[attr-defined]
+    wrapper.get_current_comparison = current_comparison.get  # type: ignore[attr-defined]
+    return cast(Function[T], wrapper)

regscope/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Command-line interface for RegScope."""
+
+from .main import main
+
+__all__ = ["main"]

regscope/cli/main.py

@@ -0,0 +1,80 @@
+"""Argparse-based RegScope command line interface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import asdict
+from pathlib import Path
+from typing import List, Optional, Sequence
+
+from ..core.comparison import DEFAULT_THRESHOLD, compare
+from ..models import Baseline, BehaviorProfile
+from .trend import report
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="regscope")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    compare_parser = subparsers.add_parser("compare", help="compare a profile to a baseline")
+    compare_parser.add_argument("--baseline", required=True, type=Path)
+    compare_parser.add_argument("--current", required=True, type=Path)
+    compare_parser.add_argument("--threshold", type=float, default=DEFAULT_THRESHOLD)
+    compare_parser.add_argument("--duration-threshold", type=float)
+    compare_parser.add_argument("--call-count-threshold", type=float)
+    compare_parser.add_argument("--exceptions-threshold", type=float)
+    compare_parser.add_argument("--json", action="store_true", dest="json_output")
+    trend_parser = subparsers.add_parser("trend", help="report historical behavior trends")
+    trend_parser.add_argument("--directory", type=Path, default=Path(".regscope"))
+    trend_parser.add_argument("--function", required=True)
+    trend_parser.add_argument("--json", action="store_true", dest="json_output")
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command == "compare":
+        thresholds = {
+            name: value
+            for name, value in {
+                "duration_ns": args.duration_threshold,
+                "call_count": args.call_count_threshold,
+                "exceptions": args.exceptions_threshold,
+            }.items()
+            if value is not None
+        }
+        return _compare(args.baseline, args.current, args.threshold, thresholds, args.json_output)
+    if args.command == "trend":
+        return report(args.directory, args.function, args.json_output)
+    return 2
+
+
+def _compare(baseline_path: Path, current_path: Path, threshold: float, thresholds, json_output: bool) -> int:
+    baseline = Baseline.from_json(baseline_path.read_text(encoding="utf-8"))
+    current = BehaviorProfile.from_json(current_path.read_text(encoding="utf-8"))
+    result = compare(current, baseline, threshold=threshold, thresholds=thresholds)
+
+    if json_output:
+        output = asdict(result)
+        output["regression"] = result.regression
+        output["risk"] = result.risk
+        print(json.dumps(output, sort_keys=True))
+        return 1 if result.regression else 0
+
+    print("RegScope Comparison")
+    print()
+    print(result.function)
+    print(f"  Status: {result.status}")
+    print(f"  Risk: {result.risk}")
+    for metric in result.metrics:
+        marker = " REGRESSION" if metric.regression else ""
+        print(
+            f"  {metric.metric}: {metric.baseline_median:g} -> "
+            f"{metric.current:g} ({metric.change_ratio:+.1%}){marker}"
+        )
+    print()
+    if result.regression:
+        print("Result: behavioral regression detected")
+        return 1
+    print("Result: no behavioral regression detected")
+    return 0

regscope/cli/trend.py

@@ -0,0 +1,22 @@
+"""Historical trend reporting for RegScope."""
+
+from pathlib import Path
+import json
+from dataclasses import asdict
+
+from ..trends import HistoryStore
+
+
+def report(directory: Path, function: str, json_output: bool = False) -> int:
+    summary = HistoryStore(directory).summarize(function)
+    if json_output:
+        print(json.dumps(asdict(summary), sort_keys=True))
+        return 0
+    print("RegScope Trend")
+    print(function)
+    print(f"  Samples: {summary.samples}")
+    print(f"  Duration: {summary.duration_min_ns} -> {summary.duration_median_ns} -> {summary.duration_max_ns} ns")
+    print(f"  Exception samples: {summary.exception_samples}")
+    print(f"  Duration change: {summary.duration_delta_ns:+d} ns ({summary.duration_change_ratio:+.1%})")
+    print(f"  Exception rate: {summary.exception_rate:.1%}")
+    return 0

regscope/collectors/__init__.py

@@ -0,0 +1,14 @@
+"""Optional and core behavior collectors."""
+
+from .sqlalchemy import SQLAlchemyCollector
+from .http import HTTPCollector
+from .redis import RedisCollector
+from .memory import MemoryCollector, MemoryProfile
+
+__all__ = [
+    "HTTPCollector",
+    "MemoryCollector",
+    "MemoryProfile",
+    "RedisCollector",
+    "SQLAlchemyCollector",
+]

regscope/collectors/call_graph.py

@@ -0,0 +1,93 @@
+"""Call-count collection using Python's process profiler hook."""
+
+from __future__ import annotations
+
+import sys
+from inspect import iscoroutinefunction
+from collections import Counter
+from types import FrameType
+from typing import Any, Callable, Dict, Optional, Tuple, TypeVar
+
+
+T = TypeVar("T")
+ProfileFunction = Callable[[FrameType, str, Any], Optional[Callable[..., Any]]]
+
+
+def collect_call_graph(
+    function: Callable[..., T], *args: Any, **kwargs: Any
+) -> Tuple[T, Dict[str, int]]:
+    """Execute ``function`` while counting Python function-call events.
+
+    Any profiler that was installed before collection is called for each
+    event, and the previous profiler is restored even when execution raises.
+    The returned mapping is flat and keyed by qualified function name.
+    """
+    counts: Counter[str] = Counter()
+    previous = sys.getprofile()
+    local_callbacks: Dict[int, ProfileFunction] = {}
+
+    def profiler(frame: FrameType, event: str, arg: Any) -> None:
+        if previous is not None:
+            if event == "call":
+                callback = previous(frame, event, arg)
+                if callback is not None:
+                    local_callbacks[id(frame)] = callback
+            else:
+                callback = local_callbacks.get(id(frame))
+                if callback is not None:
+                    callback(frame, event, arg)
+        if event == "call":
+            counts[_frame_name(frame)] += 1
+        elif event == "return":
+            local_callbacks.pop(id(frame), None)
+
+    sys.setprofile(profiler)
+    try:
+        result = function(*args, **kwargs)
+    finally:
+        if sys.getprofile() is profiler:
+            sys.setprofile(previous)
+
+    return result, dict(sorted(counts.items()))
+
+
+async def collect_async_call_graph(
+    function: Callable[..., T], *args: Any, **kwargs: Any
+) -> Tuple[T, Dict[str, int]]:
+    """Async equivalent of :func:`collect_call_graph`."""
+    if not iscoroutinefunction(function):
+        raise TypeError("collect_async_call_graph requires an async function")
+
+    counts: Counter[str] = Counter()
+    previous = sys.getprofile()
+    local_callbacks: Dict[int, ProfileFunction] = {}
+
+    def profiler(frame: FrameType, event: str, arg: Any) -> None:
+        if previous is not None:
+            if event == "call":
+                callback = previous(frame, event, arg)
+                if callback is not None:
+                    local_callbacks[id(frame)] = callback
+            else:
+                callback = local_callbacks.get(id(frame))
+                if callback is not None:
+                    callback(frame, event, arg)
+        if event == "call":
+            counts[_frame_name(frame)] += 1
+        elif event == "return":
+            local_callbacks.pop(id(frame), None)
+
+    sys.setprofile(profiler)
+    try:
+        result = await function(*args, **kwargs)
+    finally:
+        if sys.getprofile() is profiler:
+            sys.setprofile(previous)
+
+    return result, dict(sorted(counts.items()))
+
+
+def _frame_name(frame: FrameType) -> str:
+    module = frame.f_globals.get("__name__", "__main__")
+    qualified_name = getattr(frame.f_code, "co_qualname", frame.f_code.co_name)
+    return f"{module}.{qualified_name}"

regscope/collectors/http.py

@@ -0,0 +1,76 @@
+"""Optional count-only HTTP instrumentation for requests."""
+
+from __future__ import annotations
+
+from functools import wraps
+from threading import Lock
+from typing import Any, Callable, ClassVar, Optional
+
+
+class HTTPCollector:
+    """Count outgoing ``requests`` calls without recording request data.
+
+    The requests hook is process-global while attached. Do not attach multiple
+    HTTP collectors concurrently; use one collector per tracked execution.
+    """
+
+    _active_owner: ClassVar[Optional["HTTPCollector"]] = None
+    _ownership_lock: ClassVar[Lock] = Lock()
+
+    def __init__(self) -> None:
+        self._requests: Optional[Any] = None
+        self._original: Optional[Callable[..., Any]] = None
+        self._wrapped: Optional[Callable[..., Any]] = None
+        self._count = 0
+        self._lock = Lock()
+
+    def attach(self) -> None:
+        try:
+            import requests
+        except ImportError as error:
+            raise RuntimeError(
+                "HTTP tracking requires the 'http' extra: install regscope[http]"
+            ) from error
+        with self._ownership_lock:
+            if self._original is not None:
+                raise RuntimeError("collector is already attached")
+            if type(self)._active_owner is not None:
+                raise RuntimeError("another HTTP collector is already attached")
+
+            original = requests.sessions.Session.request
+
+            @wraps(original)
+            def counted_request(session: Any, *args: Any, **kwargs: Any) -> Any:
+                with self._lock:
+                    self._count += 1
+                return original(session, *args, **kwargs)
+
+            requests.sessions.Session.request = counted_request
+            self._requests = requests
+            self._original = original
+            self._wrapped = counted_request
+            type(self)._active_owner = self
+
+    def detach(self) -> None:
+        if (
+            self._requests is not None
+            and self._original is not None
+            and self._wrapped is not None
+            and self._requests.sessions.Session.request is self._wrapped
+        ):
+            self._requests.sessions.Session.request = self._original
+        with self._ownership_lock:
+            if type(self)._active_owner is self:
+                type(self)._active_owner = None
+        self._requests = None
+        self._original = None
+        self._wrapped = None
+
+    @property
+    def request_count(self) -> int:
+        with self._lock:
+            return self._count
+
+    def reset(self) -> None:
+        with self._lock:
+            self._count = 0

regscope/collectors/memory.py

@@ -0,0 +1,41 @@
+"""Memory measurements using the Python standard library."""
+
+from __future__ import annotations
+
+import tracemalloc
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Iterator, Optional
+
+
+@dataclass(frozen=True)
+class MemoryProfile:
+    """Traced memory values in bytes for one measured region."""
+
+    current_delta: int
+    peak: int
+
+
+class MemoryCollector:
+    """Measure traced current allocation changes and peak memory."""
+
+    def __init__(self) -> None:
+        self.last_profile: Optional[MemoryProfile] = None
+
+    @contextmanager
+    def measure(self) -> Iterator[None]:
+        """Measure allocations made inside the context."""
+        already_tracing = tracemalloc.is_tracing()
+        if not already_tracing:
+            tracemalloc.start()
+        started_current, _ = tracemalloc.get_traced_memory()
+        try:
+            yield
+        finally:
+            current, peak = tracemalloc.get_traced_memory()
+            self.last_profile = MemoryProfile(
+                current_delta=current - started_current,
+                peak=peak,
+            )
+            if not already_tracing:
+                tracemalloc.stop()