regscope 0.1.0__tar.gz

regscope-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,179 @@
+# 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/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "regscope"
+version = "0.1.0"
+description = "Observed behavioral diffing for Python functions"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "RegScope contributors" }]
+dependencies = []
+keywords = ["profiling", "regression-testing", "performance", "observability"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+]
+
+[project.urls]
+Homepage = "https://github.com/AdeelMalik22/regscope"
+Repository = "https://github.com/AdeelMalik22/regscope"
+Issues = "https://github.com/AdeelMalik22/regscope/issues"
+
+[project.scripts]
+regscope = "regscope.cli:main"
+
+[project.entry-points.pytest11]
+regscope = "regscope.pytest_plugin"
+
+[project.optional-dependencies]
+dev = ["build", "pytest"]
+db = ["SQLAlchemy>=1.4"]
+http = ["requests>=2.28"]
+redis = ["redis>=4.0"]
+integration = ["SQLAlchemy>=1.4", "requests>=2.28", "redis>=4.0"]
+
+[tool.setuptools.packages.find]
+include = ["regscope*"]
+
+[tool.setuptools.package-data]
+regscope = ["py.typed"]
+
+[tool.pytest.ini_options]
+addopts = ["-ra"]
+testpaths = ["tests"]

regscope-0.1.0/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-0.1.0/regscope/__main__.py

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

regscope-0.1.0/regscope/api/__init__.py

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

regscope-0.1.0/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-0.1.0/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")