cachescope 0.1.0a1__tar.gz

cachescope-0.1.0a1/.github/tests/test_release_artifacts.py

@@ -0,0 +1,116 @@
+"""Reject stale, altered or mismatched distributions before promotion."""
+
+import importlib.util
+import io
+import json
+from pathlib import Path
+import tarfile
+import zipfile
+from urllib.error import HTTPError
+
+import pytest
+
+SCRIPT = Path(__file__).resolve().parents[1] / "scripts/release_artifacts.py"
+spec = importlib.util.spec_from_file_location("release_artifacts", SCRIPT)
+release = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(release)
+VERSION = "0.1.0a1"
+
+
+def artifacts(directory):
+    dist = directory / "dist"
+    dist.mkdir()
+    metadata = f"Metadata-Version: 2.4\nName: cachescope\nVersion: {VERSION}\n".encode()
+    wheel = dist / f"cachescope-{VERSION}-py3-none-any.whl"
+    with zipfile.ZipFile(wheel, "w") as archive:
+        archive.writestr(f"cachescope-{VERSION}.dist-info/METADATA", metadata)
+    with tarfile.open(dist / f"cachescope-{VERSION}.tar.gz", "w:gz") as archive:
+        member = tarfile.TarInfo(f"cachescope-{VERSION}/PKG-INFO")
+        member.size = len(metadata)
+        archive.addfile(member, io.BytesIO(metadata))
+    return release.make_manifest(directory, VERSION)
+
+
+def test_matching_release_is_accepted(tmp_path):
+    manifest = artifacts(tmp_path)
+    release.verify_local(tmp_path, manifest)
+    payload = {
+        "info": {"name": "cachescope", "version": VERSION},
+        "urls": [{"filename": name, "digests": {"sha256": digest}} for name, digest in manifest["files"].items()],
+    }
+    release.verify_index(manifest, payload)
+
+
+def test_stale_version_is_rejected(tmp_path):
+    artifacts(tmp_path)
+    with pytest.raises(ValueError, match="name/version"):
+        release.make_manifest(tmp_path, "0.1.0a2")
+
+
+def test_extra_old_distribution_is_rejected(tmp_path):
+    artifacts(tmp_path)
+    (tmp_path / "dist/old.whl").write_bytes(b"old")
+    with pytest.raises(ValueError, match="exactly one"):
+        release.make_manifest(tmp_path, VERSION)
+
+
+def test_artifact_modified_after_testing_is_rejected(tmp_path):
+    manifest = artifacts(tmp_path)
+    wheel = next((tmp_path / "dist").glob("*.whl"))
+    with wheel.open("ab") as stream:
+        stream.write(b"modified after test")
+    with pytest.raises(ValueError, match="changed"):
+        release.verify_local(tmp_path, manifest)
+
+
+def test_index_cannot_substitute_different_artifacts(tmp_path):
+    manifest = artifacts(tmp_path)
+    payload = {"info": {"name": "cachescope", "version": VERSION}, "urls": []}
+    with pytest.raises(ValueError, match="Published artifacts"):
+        release.verify_index(manifest, payload)
+
+
+def test_index_cannot_substitute_another_version(tmp_path):
+    manifest = artifacts(tmp_path)
+    payload = {"info": {"name": "cachescope", "version": "0.1.0a2"}, "urls": []}
+    with pytest.raises(ValueError, match="different project/version"):
+        release.verify_index(manifest, payload)
+
+
+def test_index_propagation_is_retried_without_installing_other_versions(tmp_path, monkeypatch):
+    manifest = artifacts(tmp_path)
+    payload = {
+        "info": {"name": "cachescope", "version": VERSION},
+        "urls": [{"filename": name, "digests": {"sha256": digest}} for name, digest in manifest["files"].items()],
+    }
+    calls, delays = [], []
+
+    def fetch(request, timeout):
+        calls.append(request.full_url)
+        if len(calls) == 1:
+            raise HTTPError(request.full_url, 404, "not propagated", {}, None)
+        return io.StringIO(json.dumps(payload))
+
+    monkeypatch.setattr(release.urllib.request, "urlopen", fetch)
+    monkeypatch.setattr(release.time, "sleep", delays.append)
+    release.wait_for_index(manifest, "https://test.pypi.org", attempts=2)
+    assert calls == [f"https://test.pypi.org/pypi/cachescope/{VERSION}/json"] * 2
+    assert delays == [5]
+
+
+def test_mismatched_published_hashes_fail_without_retrying(tmp_path, monkeypatch):
+    manifest = artifacts(tmp_path)
+    payload = {
+        "info": {"name": "cachescope", "version": VERSION},
+        "urls": [{"filename": name, "digests": {"sha256": "0" * 64}} for name in manifest["files"]],
+    }
+    calls = []
+
+    def fetch(request, timeout):
+        calls.append(request.full_url)
+        return io.StringIO(json.dumps(payload))
+
+    monkeypatch.setattr(release.urllib.request, "urlopen", fetch)
+    with pytest.raises(ValueError, match="Published artifacts"):
+        release.wait_for_index(manifest, "https://test.pypi.org")
+    assert len(calls) == 1

cachescope-0.1.0a1/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+scratch/

cachescope-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dulkar Saman V N
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cachescope-0.1.0a1/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.5
+Name: cachescope
+Version: 0.1.0a1
+Summary: Find which Python functions repeat slow work, and how big a cache they need.
+Project-URL: Homepage, https://github.com/dulkarsamanvn/cachescope
+Project-URL: Issues, https://github.com/dulkarsamanvn/cachescope/issues
+Author: Dulkar Saman V N
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cache,caching,lru_cache,performance,profiler
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cachescope
+
+Find which Python functions repeat slow work.
+
+Install the alpha release from PyPI:
+
+```console
+python -m pip install --pre cachescope
+```
+
+Or install from this checkout and run a script:
+
+```console
+python -m pip install .
+cachescope run app.py [script arguments]
+python -m cachescope run --root . scripts/app.py [script arguments]
+```
+
+`--root` selects the directory whose functions are eligible for analysis. It
+defaults to the script's directory and does not change Python's import paths.
+Place this option before the script name; options after the script are passed
+to the script. Use `cachescope --help` for the command syntax.
+
+The report sorts functions by observed repeated work:
+
+- **CANDIDATE**: repeated successful calls were slow enough to investigate,
+  their comparable results were stable, and the checks found no known risk.
+- **MAYBE**: evidence is incomplete or caching needs a human check, such as
+  unknown/mutable results, factory-created functions, captured state, detected
+  effects, or observation limits.
+- **UNSAFE**: comparable calls with the same observed input returned different
+  results, without ambiguous closure context.
+- **SKIP**: too few useful repeats or too little repeated work was observed.
+
+“Repeat work” is the measured time of repeated successful evaluations, not a
+promise of elapsed time saved. Times exclude work inside the profiling callback
+and recursive overlap, but interpreter profiling overhead remains. Function
+times include callees, so rows are not additive. Recursion receives no independent
+cache savings estimate. Call-heavy programs can slow down substantially.
+
+Size estimates model normalized argument values. Python has already bound
+defaults and positional/keyword arguments when these values are observed.
+Consequently, `f()`, `f(1)`, and `f(n=1)` can look identical here while occupying
+different real cache entries. Estimates assume consistent call spelling; verify
+the decorated function with `cache_info()` on a representative workload.
+The report does not prescribe an `@lru_cache` decorator. Observed numeric-type
+key collisions block size advice, and `typed=True` does not distinguish types
+inside tuple arguments.
+
+Only the thread that starts the tracer is observed. Generator, coroutine, and
+async-generator functions are skipped. Comparisons support exact built-in int,
+float, bool, str, bytes, None, list, tuple, and dict values, preserving dictionary
+order. Custom objects, including most method `self` arguments, are unknown.
+Mutable return values require review because caching would share them. Failed
+and unfinished calls are excluded from cache-hit and repeated-work estimates.
+
+Observation is bounded: values have depth, item, and byte budgets; each function
+retains at most 4,096 distinct inputs and 100,000 sequence entries. Retention is
+budgeted at approximately 4 MiB per function and 32 MiB across records, with a
+function-count limit as well. These are accounting budgets, not a process RSS
+limit; active snapshots and interpreter overhead also use memory. Reaching a
+retention limit is reported. Truncated sequences receive no size/hit-rate estimate.
+
+Source checks recognize common risky calls, import aliases, direct helper calls,
+external-variable reads, and argument mutations. They are a heuristic: dynamic
+dispatch, imported helper implementations, and changes in external state can
+escape detection. A CANDIDATE is evidence from one run, not a proof of purity.
+
+For programmatic use, `Tracer` supports a context manager and restores a prior
+Python profile hook when stopped. That prior hook is suspended during tracing.
+Nested tracers and incompatible native hooks are rejected; independent
+`sys.monitoring` tools can coexist. Start and stop a tracer in the same thread.
+
+To develop and check distributions:
+
+```console
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m build
+python -m twine check dist/*
+```
+
+CI runs the suite on Python 3.9 through 3.14 on Linux and Windows, and checks
+the built wheel and source distribution. The Linux Python 3.9 job uses Ubuntu
+22.04, which has a supported `setup-python` binary for that version.
+
+Maintainers: see the [release guide](https://github.com/dulkarsamanvn/cachescope/blob/main/RELEASING.md)
+for the TestPyPI rehearsal and Trusted Publishing setup.

cachescope-0.1.0a1/README.md

@@ -0,0 +1,88 @@
+# cachescope
+
+Find which Python functions repeat slow work.
+
+Install the alpha release from PyPI:
+
+```console
+python -m pip install --pre cachescope
+```
+
+Or install from this checkout and run a script:
+
+```console
+python -m pip install .
+cachescope run app.py [script arguments]
+python -m cachescope run --root . scripts/app.py [script arguments]
+```
+
+`--root` selects the directory whose functions are eligible for analysis. It
+defaults to the script's directory and does not change Python's import paths.
+Place this option before the script name; options after the script are passed
+to the script. Use `cachescope --help` for the command syntax.
+
+The report sorts functions by observed repeated work:
+
+- **CANDIDATE**: repeated successful calls were slow enough to investigate,
+  their comparable results were stable, and the checks found no known risk.
+- **MAYBE**: evidence is incomplete or caching needs a human check, such as
+  unknown/mutable results, factory-created functions, captured state, detected
+  effects, or observation limits.
+- **UNSAFE**: comparable calls with the same observed input returned different
+  results, without ambiguous closure context.
+- **SKIP**: too few useful repeats or too little repeated work was observed.
+
+“Repeat work” is the measured time of repeated successful evaluations, not a
+promise of elapsed time saved. Times exclude work inside the profiling callback
+and recursive overlap, but interpreter profiling overhead remains. Function
+times include callees, so rows are not additive. Recursion receives no independent
+cache savings estimate. Call-heavy programs can slow down substantially.
+
+Size estimates model normalized argument values. Python has already bound
+defaults and positional/keyword arguments when these values are observed.
+Consequently, `f()`, `f(1)`, and `f(n=1)` can look identical here while occupying
+different real cache entries. Estimates assume consistent call spelling; verify
+the decorated function with `cache_info()` on a representative workload.
+The report does not prescribe an `@lru_cache` decorator. Observed numeric-type
+key collisions block size advice, and `typed=True` does not distinguish types
+inside tuple arguments.
+
+Only the thread that starts the tracer is observed. Generator, coroutine, and
+async-generator functions are skipped. Comparisons support exact built-in int,
+float, bool, str, bytes, None, list, tuple, and dict values, preserving dictionary
+order. Custom objects, including most method `self` arguments, are unknown.
+Mutable return values require review because caching would share them. Failed
+and unfinished calls are excluded from cache-hit and repeated-work estimates.
+
+Observation is bounded: values have depth, item, and byte budgets; each function
+retains at most 4,096 distinct inputs and 100,000 sequence entries. Retention is
+budgeted at approximately 4 MiB per function and 32 MiB across records, with a
+function-count limit as well. These are accounting budgets, not a process RSS
+limit; active snapshots and interpreter overhead also use memory. Reaching a
+retention limit is reported. Truncated sequences receive no size/hit-rate estimate.
+
+Source checks recognize common risky calls, import aliases, direct helper calls,
+external-variable reads, and argument mutations. They are a heuristic: dynamic
+dispatch, imported helper implementations, and changes in external state can
+escape detection. A CANDIDATE is evidence from one run, not a proof of purity.
+
+For programmatic use, `Tracer` supports a context manager and restores a prior
+Python profile hook when stopped. That prior hook is suspended during tracing.
+Nested tracers and incompatible native hooks are rejected; independent
+`sys.monitoring` tools can coexist. Start and stop a tracer in the same thread.
+
+To develop and check distributions:
+
+```console
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m build
+python -m twine check dist/*
+```
+
+CI runs the suite on Python 3.9 through 3.14 on Linux and Windows, and checks
+the built wheel and source distribution. The Linux Python 3.9 job uses Ubuntu
+22.04, which has a supported `setup-python` binary for that version.
+
+Maintainers: see the [release guide](https://github.com/dulkarsamanvn/cachescope/blob/main/RELEASING.md)
+for the TestPyPI rehearsal and Trusted Publishing setup.

cachescope-0.1.0a1/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cachescope"
+version = "0.1.0a1"
+description = "Find which Python functions repeat slow work, and how big a cache they need."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Dulkar Saman V N" }]
+keywords = ["cache", "caching", "lru_cache", "performance", "profiler"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Debuggers",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "build", "twine"]
+
+[project.scripts]
+cachescope = "cachescope.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/dulkarsamanvn/cachescope"
+Issues = "https://github.com/dulkarsamanvn/cachescope/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cachescope"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/cachescope", "tests", "README.md", "LICENSE", "pyproject.toml"]

cachescope-0.1.0a1/src/cachescope/__init__.py

@@ -0,0 +1 @@
+"""cachescope: find which Python functions repeat slow work."""

cachescope-0.1.0a1/src/cachescope/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

cachescope-0.1.0a1/src/cachescope/cli.py

@@ -0,0 +1,74 @@
+"""The command line: cachescope run script.py"""
+
+import os
+import runpy
+import sys
+import traceback
+
+from .tracer import Tracer
+
+USAGE = "usage: cachescope run [--root DIRECTORY] script.py [script arguments]"
+
+
+def main(argv=None):
+    args = sys.argv[1:] if argv is None else list(argv)
+
+    if args in (["--help"], ["-h"], ["run", "--help"]):
+        print(USAGE)
+        return 0
+    if not args or args[0] != "run":
+        print(USAGE, file=sys.stderr)
+        return 2
+
+    remaining, root = args[1:], None
+    if remaining[:1] == ["--root"]:
+        if len(remaining) < 3:
+            print(USAGE, file=sys.stderr)
+            return 2
+        root, remaining = remaining[1], remaining[2:]
+        if not os.path.isdir(root):
+            print(f"cachescope: cannot find root directory: {root}", file=sys.stderr)
+            return 2
+    if remaining[:1] == ["--"]:
+        remaining = remaining[1:]
+    if not remaining:
+        print(USAGE, file=sys.stderr)
+        return 2
+    script, script_args = remaining[0], remaining[1:]
+
+    if not os.path.isfile(script):
+        print(f"cachescope: cannot find script: {script}", file=sys.stderr)
+        return 2
+
+    script_path = os.path.abspath(script)
+    script_folder = os.path.dirname(script_path)
+
+    tracer = Tracer(root=root or script_folder)
+    exit_code = 0
+    previous_argv, previous_path = sys.argv, sys.path
+    previous_path_values = previous_path[:]
+
+    try:
+        # Make the script believe it was started normally, then restore the host.
+        sys.argv = [script, *script_args]
+        sys.path = [script_folder, *previous_path_values]
+        tracer.start()
+        runpy.run_path(script_path, run_name="__main__")
+    except SystemExit as exc:  # the script called exit() or sys.exit()
+        code = exc.code
+        exit_code = code if isinstance(code, int) else (0 if code is None else 1)
+        if code is not None and not isinstance(code, int):
+            print(code, file=sys.stderr)
+    except Exception:  # the script crashed: show the error, but still give the report
+        traceback.print_exc()
+        exit_code = 1
+    finally:
+        try:
+            tracer.stop()
+        finally:
+            sys.argv, sys.path = previous_argv, previous_path
+            previous_path[:] = previous_path_values
+
+    print()
+    tracer.report()
+    return exit_code

cachescope-0.1.0a1/src/cachescope/fingerprint.py

@@ -0,0 +1,94 @@
+"""Turn values into labels so we can tell if two calls are the same."""
+
+import sys
+
+
+class _Unknown:
+    """A marker that means: we are not sure about this value."""
+
+    def __repr__(self):
+        return "UNKNOWN"
+
+
+UNKNOWN = _Unknown()
+
+
+def immutable_label(label):
+    """Whether a known fingerprint describes a value safe to share by value."""
+    kind, value = label
+    if kind == "tuple":
+        return all(immutable_label(part) for part in value)
+    return kind not in ("list", "dict")
+
+# The simple kinds of values we trust.
+SAFE_TYPES = (int, float, str, bytes, bool, type(None))
+TYPE_NAMES = {kind: kind.__name__ for kind in (*SAFE_TYPES, list, tuple)}
+
+# How many levels of "list inside a list inside..." we are willing to look into.
+MAX_DEPTH = 4
+MAX_ITEMS = 1024
+MAX_VALUE_BYTES = 64 * 1024
+
+
+def fingerprint(value, depth=0):
+    """Best-effort observation: a changing container must not break its caller."""
+    try:
+        return _fingerprint(value, depth, [MAX_ITEMS, MAX_VALUE_BYTES])
+    except Exception:
+        return UNKNOWN
+
+
+def _fingerprint(value, depth, budget):
+    t = type(value)
+    budget[0] -= 1
+    budget[1] -= 64
+    if t is str:
+        budget[1] -= len(value) * 4
+    elif t is bytes:
+        budget[1] -= len(value)
+    elif t is int:
+        budget[1] -= value.bit_length() // 8
+    if budget[0] < 0 or budget[1] < 0:
+        return UNKNOWN
+
+    if t in SAFE_TYPES:
+        return (TYPE_NAMES[t], value)
+
+    # Too deep (or a value that contains itself): give up instead of crashing.
+    if depth >= MAX_DEPTH:
+        return UNKNOWN
+
+    if t is list or t is tuple:
+        parts = []
+        for item in value:
+            item_label = _fingerprint(item, depth + 1, budget)
+            if item_label is UNKNOWN:
+                return UNKNOWN
+            parts.append(item_label)
+        return (TYPE_NAMES[t], tuple(parts))
+
+    if t is dict:
+        pairs = []
+        for key, val in value.items():
+            key_label = _fingerprint(key, depth + 1, budget)
+            val_label = _fingerprint(val, depth + 1, budget)
+            if key_label is UNKNOWN or val_label is UNKNOWN:
+                return UNKNOWN
+            pairs.append((key_label, val_label))
+        return ("dict", tuple(pairs))
+
+    return UNKNOWN
+
+
+def fingerprint_size(label):
+    """Conservative retention estimate for an already bounded, known label."""
+    pending, seen, size = [label], set(), 0
+    while pending:
+        value = pending.pop()
+        if id(value) in seen:
+            continue
+        seen.add(id(value))
+        size += sys.getsizeof(value)
+        if type(value) is tuple:
+            pending.extend(value)
+    return size