regscope 0.1.0__py3-none-any.whl

regscope/trends/history.py

@@ -0,0 +1,137 @@
+"""Append-only historical trend records for observed profiles."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from statistics import median
+from typing import List, Optional, Union
+
+from ..models import BehaviorProfile, SCHEMA_VERSION
+from ..errors import MalformedRecordError
+
+
+@dataclass(frozen=True)
+class TrendPoint:
+    function: str
+    recorded_at: str
+    duration_ns: int
+    call_count: int
+    exceptions: int
+    fingerprint: str
+    schema_version: int = 1
+
+    @classmethod
+    def from_profile(
+        cls, profile: BehaviorProfile, recorded_at: Optional[str] = None
+    ) -> "TrendPoint":
+        timestamp = recorded_at or datetime.now(timezone.utc).isoformat()
+        return cls(
+            function=profile.function,
+            recorded_at=timestamp,
+            duration_ns=profile.duration_ns,
+            call_count=profile.call_count,
+            exceptions=profile.exceptions,
+            fingerprint=profile.fingerprint(),
+        )
+
+    def to_json(self) -> str:
+        return json.dumps(self.__dict__, sort_keys=True, separators=(",", ":"))
+
+    @classmethod
+    def from_json(cls, value: str) -> "TrendPoint":
+        data = json.loads(value)
+        data.setdefault("schema_version", 1)
+        if data["schema_version"] > SCHEMA_VERSION:
+            raise ValueError(f"unsupported history schema version {data['schema_version']}")
+        return cls(**data)
+
+
+@dataclass(frozen=True)
+class TrendSummary:
+    function: str
+    samples: int
+    duration_min_ns: int
+    duration_median_ns: int
+    duration_max_ns: int
+    duration_first_ns: int
+    duration_latest_ns: int
+    duration_delta_ns: int
+    duration_change_ratio: float
+    exception_samples: int
+    exception_rate: float
+
+
+class HistoryStore:
+    """Store append-only trend points in one JSONL file per function."""
+
+    def __init__(self, directory: Union[str, Path], max_points: Optional[int] = None) -> None:
+        if max_points is not None and max_points < 1:
+            raise ValueError("max_points must be at least 1")
+        self.directory = Path(directory)
+        self.max_points = max_points
+
+    def path_for(self, function: str) -> Path:
+        digest = hashlib.sha256(function.encode("utf-8")).hexdigest()[:16]
+        return self.directory / f"{digest}.jsonl"
+
+    def record(self, profile: BehaviorProfile, recorded_at: Optional[str] = None) -> TrendPoint:
+        self.directory.mkdir(parents=True, exist_ok=True)
+        point = TrendPoint.from_profile(profile, recorded_at=recorded_at)
+        points = self.load(profile.function)
+        points.append(point)
+        if self.max_points is not None:
+            points = points[-self.max_points :]
+        temporary = self.path_for(profile.function).with_suffix(".tmp")
+        temporary.write_text(
+            "".join(item.to_json() + "\n" for item in points), encoding="utf-8"
+        )
+        temporary.replace(self.path_for(profile.function))
+        return point
+
+    def load(self, function: str) -> List[TrendPoint]:
+        path = self.path_for(function)
+        if not path.exists():
+            return []
+        try:
+            return [
+                TrendPoint.from_json(line)
+                for line in path.read_text(encoding="utf-8").splitlines()
+                if line.strip()
+            ]
+        except (OSError, TypeError, ValueError, KeyError) as error:
+            raise MalformedRecordError(
+                f"invalid history record at {path}: {error}"
+            ) from error
+
+    def summarize(self, function: str) -> TrendSummary:
+        points = self.load(function)
+        if not points:
+            raise ValueError("no historical samples for function")
+        durations = [point.duration_ns for point in points]
+        first_duration = durations[0]
+        latest_duration = durations[-1]
+        change_ratio = (
+            0.0
+            if first_duration == 0 and latest_duration == 0
+            else float("inf")
+            if first_duration == 0
+            else (latest_duration - first_duration) / first_duration
+        )
+        exception_samples = sum(point.exceptions for point in points)
+        return TrendSummary(
+            function=function,
+            samples=len(points),
+            duration_min_ns=min(durations),
+            duration_median_ns=int(median(durations)),
+            duration_max_ns=max(durations),
+            duration_first_ns=first_duration,
+            duration_latest_ns=latest_duration,
+            duration_delta_ns=latest_duration - first_duration,
+            duration_change_ratio=change_ratio,
+            exception_samples=exception_samples,
+            exception_rate=exception_samples / len(points),
+        )

regscope-0.1.0.dist-info/METADATA

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: regscope
+Version: 0.1.0
+Summary: Observed behavioral diffing for Python functions
+Author: RegScope contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AdeelMalik22/regscope
+Project-URL: Repository, https://github.com/AdeelMalik22/regscope
+Project-URL: Issues, https://github.com/AdeelMalik22/regscope/issues
+Keywords: profiling,regression-testing,performance,observability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Provides-Extra: db
+Requires-Dist: SQLAlchemy>=1.4; extra == "db"
+Provides-Extra: http
+Requires-Dist: requests>=2.28; extra == "http"
+Provides-Extra: redis
+Requires-Dist: redis>=4.0; extra == "redis"
+Provides-Extra: integration
+Requires-Dist: SQLAlchemy>=1.4; extra == "integration"
+Requires-Dist: requests>=2.28; extra == "integration"
+Requires-Dist: redis>=4.0; extra == "integration"
+
+# RegScope
+
+RegScope is a behavioral diffing library for Python functions. It records what
+a function did during a controlled test run so behavior can be compared across
+code versions.
+
+RegScope does not prove that two functions are mathematically equivalent. It
+reports differences in behavior observed during the runs that were recorded.
+
+## In plain language
+
+RegScope is like a before-and-after checkup for a Python function. You place
+`@track` above a function, run your normal tests, and RegScope quietly records
+useful facts about that run: how long the function took, whether it failed,
+which Python functions it called, and—when configured—how many database,
+HTTP, or Redis operations it made.
+
+When the function runs again after a code change, RegScope compares the new
+checkup with earlier runs. It can warn you that a function became slower,
+started raising errors, made more database queries, or used more memory. In
+CI, that warning can fail the build so a performance or behavior regression is
+noticed before the change is released.
+
+It does not change what your function returns, and it does not decide whether
+two implementations are mathematically identical. It compares what happened
+during the test cases you actually ran. It also does not save function
+arguments, return values, SQL text, URLs, request bodies, Redis keys, or Redis
+values.
+
+## Current status
+
+The early v0.1 core supports:
+
+- Synchronous and asynchronous `@track` decoration
+- Execution duration measurement
+- Exception counting while preserving the original exception
+- Flat call-graph counts using `sys.setprofile()`
+- Structured JSON behavior profiles
+- N-run JSON baselines with atomic file replacement
+- Configurable baseline storage through `baseline_dir`
+- Zero required runtime dependencies
+
+## Quick start
+
+```python
+from regscope import track
+
+
+@track
+def calculate_total(values: list[int]) -> int:
+    return sum(values)
+
+
+total = calculate_total([1, 2, 3])
+profile = calculate_total.last_profile
+print(total)
+print(profile.duration_ns)
+```
+
+Use `warmup_runs=N` to execute and report the first N calls without adding
+them to the baseline or historical trend. This is useful when the first call
+opens connections, imports modules, or initializes caches:
+
+```python
+@track(baseline_dir=".regscope", warmup_runs=1)
+def load_dashboard() -> int:
+    return 42
+```
+
+The decorator supports both `@track` and `@track(...)`. Async functions are
+supported transparently:
+
+```python
+from regscope import track
+
+
+@track
+async def fetch_value() -> int:
+    return 42
+```
+
+After a call, `function.get_current_profile()` and
+`function.get_current_comparison()` return values stored in the current
+`contextvars` context. These accessors are task-safe for concurrent async
+invocations. The legacy `function.last_profile` and
+`function.last_comparison` attributes remain available as compatibility
+snapshots, but can be overwritten by another concurrent invocation.
+
+Each tracked function writes a bounded JSON baseline to the configured
+directory. The default directory is `.regscope`. Profiles contain structured
+metrics and call counts; they do not capture function arguments or sensitive
+external data.
+
+## CI regression checks
+
+The repository workflow keeps trusted baselines outside Git. A push to
+`master` runs `tests/ci_targets`, records the baseline in `.regscope`, and
+uploads it as the `regscope-baseline-master` artifact. Pull-request jobs
+download the latest successful artifact from `master` and compare the same
+targets against it. A comparison that exceeds the configured threshold fails
+the job.
+
+Baseline artifacts are retained for 30 days. The workflow includes hidden
+files when uploading because `.regscope` is a dot-directory. The baseline
+publisher is restricted to trusted `master` pushes; pull requests cannot
+replace the trusted artifact, including pull requests from forks.
+
+To reproduce the comparison locally, first generate a trusted baseline and
+then run the targets without the update flag:
+
+```bash
+REGSCOPE_CI_BASELINE=1 REGSCOPE_TRUSTED_BASELINE=1 \
+  .venv/bin/python -m pytest tests/ci_targets \
+  --regscope-baseline-dir .regscope --regscope-update-baseline
+
+REGSCOPE_CI_BASELINE=1 .venv/bin/python -m pytest tests/ci_targets \
+  --regscope-baseline-dir .regscope
+```
+
+If no artifact has been published yet, the pull-request job reports that the
+trusted baseline is unavailable and the comparison target fails rather than
+silently treating the missing baseline as a pass.
+
+## Limitations
+
+- `sys.setprofile()` has one active profiler per current thread. RegScope
+  restores the profiler observed at entry, and independent threads have
+  independent collection contexts. RegScope does not arbitrate nested owners
+  in one thread or an external profiler that replaces its hook during an
+  execution. Run tracked profiling in an isolated test context when coverage,
+  a debugger, or another profiler must remain active.
+- HTTP and Redis collectors temporarily replace process-global library hooks.
+  They restore the hook that was present when attached, are thread-safe for
+  counting calls, and leave a newer hook installed by another tool untouched.
+  Only one RegScope collector may own each library hook at a time; a
+  conflicting attachment fails clearly instead of stacking wrappers.
+- Profiles describe observed executions, not all possible behavior.
+- The CI artifact workflow is validated on trusted `master` runs; a real
+  pull-request event is still required to exercise GitHub's fork permissions
+  and artifact-download path end to end.
+
+## Development
+
+Install development dependencies and run the tests:
+
+```bash
+.venv/bin/python -m pip install ".[dev]"
+.venv/bin/python -m pytest
+```
+
+The implementation roadmap is in [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md).
+Release history is in [CHANGELOG.md](CHANGELOG.md), with the release policy in
+[VERSIONING.md](VERSIONING.md).
+Performance and threshold guidance is in [docs/performance.md](docs/performance.md).
+
+## Privacy and measurements
+
+Profiles contain aggregate timing, call, exception, collector, and memory
+metrics. RegScope does not capture function arguments, return values, SQL
+text, bound parameters, URLs, headers, request bodies, Redis keys, or Redis
+values. The SHA-256 fingerprint is derived from the structured profile and is
+not a substitute for the profile itself.
+
+The core call profiler adds measurable overhead, especially for functions with
+large call graphs. Run the local benchmark with:
+
+```bash
+.venv/bin/python -m benchmarks.overhead
+```
+
+Benchmark results depend on the machine and Python version. Use them to tune
+thresholds for a project rather than treating the sample output as universal.
+
+## Schema stability
+
+Structured profiles, baselines, and historical trend points currently use
+schema version `1`. Older records that omit a schema field are read as version
+1. Records from a newer unsupported schema are rejected explicitly so they
+cannot be silently misinterpreted.

regscope-0.1.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+regscope/__init__.py,sha256=yTEyGGXnVqKFz3ayzr9JMXaHPKUNc6Is2ktDM3Pth78,182
+regscope/__main__.py,sha256=PSQ4rpL0dG6f-qH4N7H-gD9igQkdHzH4yVZDcW8lfZo,80
+regscope/errors.py,sha256=QPc5aPyH6Ol3zyMuw4uUkPmoK61Yc-p-zsXt1_7xk7k,256
+regscope/models.py,sha256=D6auI1c2x84cAFDkVjEY-rgwgnBV-kQX5rq07GzrKKw,3817
+regscope/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+regscope/pytest_plugin.py,sha256=PKo4HS4VCtr6fxOVu4zcffi76V7yS65E1wULqtKcSew,2828
+regscope/api/__init__.py,sha256=J_YBGRQots7HJefLK9fluSWIQ7iTm981MKq8SVqEhqs,127
+regscope/api/collectors.py,sha256=URtYDr7nBPwlR9yAyiOCT1WdfnfatwDvpC2D4mruiME,1874
+regscope/api/config.py,sha256=4t08tMDqnZvUA7acfsorv3rZVc9NAK-a9_2b2ftkTR0,828
+regscope/api/decorators.py,sha256=wi0YrDHEQajqy2qUKn4YsGYKlu_q5dxdA-bubk-c7cw,8483
+regscope/cli/__init__.py,sha256=wB9zjByokbjGKlUiJlvjfxD4EExlt4fPUbmgcvF9Shk,87
+regscope/cli/main.py,sha256=NnFi0MUmuHmt0GEMPfhWYFVOH8eSILVR2EwONWsK9Lk,3307
+regscope/cli/trend.py,sha256=9RGoWP8LORwk2pm2XBR_fN4izrBPWgoO8Hq7fDcEmEQ,835
+regscope/collectors/__init__.py,sha256=l6dtxGUTWpXLOCM_5HKf1a7AZkhrpNV2oVPMMR35d8Q,336
+regscope/collectors/call_graph.py,sha256=DZYT9oXDeHVqnogAM8l0wlQhygO52DAU8C0sDWpKiwQ,3225
+regscope/collectors/http.py,sha256=fHLeV3aLycmpvI2MaJ7BhtkePGKftl-jRbuTJOyPWtQ,2608
+regscope/collectors/memory.py,sha256=AKVu8gtBl2cTDwEd5Nz_h-usZGDMHMUlr1S8--afaZs,1183
+regscope/collectors/redis.py,sha256=SspuaeP-nUjDEi6ViWQOBGtP5837-qFqDwI_6r0zoas,2579
+regscope/collectors/sqlalchemy.py,sha256=lKWC6SdIA5nLNamXq4PzkAhypD9ErxBRjrjfoQdVhx8,1811
+regscope/core/__init__.py,sha256=Y85Zqm_sVCvOk-hFcNIUvpiEou12Q5PBkKyfCnTjWx8,48
+regscope/core/comparison.py,sha256=HnCefJIdY1TQjgRMYIoRU_v6BmAOJDOMwdRoXE6QFKM,3234
+regscope/core/runtime.py,sha256=zBLv8zM58TNpjUKySFcFG4YrbiWml--V2zm2rgWWZD8,1495
+regscope/storage/__init__.py,sha256=xI7bMZh2vC-tDarYzXhLsG2yGShW1omDLO7a-z8geBk,127
+regscope/storage/json_store.py,sha256=g1QoSlxyltvcC5W0ttEtxUoFPY0FT7rKX_-LsDC9LZ8,3969
+regscope/trends/__init__.py,sha256=3POzv_DpGyB8bzFftIYb5jPKZPSmthy6hjqkWxyVY5o,174
+regscope/trends/history.py,sha256=sRXnTYGmLTt095XQrtaSfZSrbntkl9D2oWD6Z2s260s,4797
+regscope-0.1.0.dist-info/METADATA,sha256=kbxyBZ4fqTHj8_CMp9nu8urnfI-3TEDARLMDjULQdaU,8416
+regscope-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+regscope-0.1.0.dist-info/entry_points.txt,sha256=V9KbhoDNLgfrZ_oEjPFJWK2QWH9kCqcGDjB-mcMZ0SE,93
+regscope-0.1.0.dist-info/top_level.txt,sha256=5IbDjUFWa_h70lGCByl23GIS1C5Y1CExkqWsKtIDZxo,9
+regscope-0.1.0.dist-info/RECORD,,

regscope-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

regscope-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+regscope = regscope.cli:main
+
+[pytest11]
+regscope = regscope.pytest_plugin

regscope-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+regscope