pycasher 0.1.0__py3-none-any.whl

casher/__init__.py

@@ -0,0 +1,5 @@
+# casher — Python function result caching with side-effect capture
+
+from casher.decorator import cached
+
+__all__ = ["cached"]

casher/_runner.py

@@ -0,0 +1,70 @@
+"""Subprocess entry point for casher.
+
+Invoked as: python -m casher._runner <work_dir>
+
+Protocol:
+  - Reads args.pkl from work_dir (dict with module, function, args, kwargs)
+  - Imports the module, gets the function (unwraps @cached if needed)
+  - Executes the function
+  - Writes result.pkl, status.json, and exception.pkl (on failure) to work_dir
+"""
+
+import importlib
+import json
+import pickle
+import sys
+from pathlib import Path
+
+
+def _unwrap_cached(fn):
+    """If fn is wrapped by @cached, return the raw function."""
+    return getattr(fn, "__wrapped__", fn)
+
+
+def _resolve_function(module_name: str, qualname: str):
+    """Import module and resolve the function by qualname."""
+    mod = importlib.import_module(module_name)
+    obj = mod
+    for attr in qualname.split("."):
+        obj = getattr(obj, attr)
+    return _unwrap_cached(obj)
+
+
+def run(work_dir: Path) -> None:
+    work_dir = Path(work_dir)
+
+    # Read args
+    with open(work_dir / "args.pkl", "rb") as f:
+        payload = pickle.load(f)  # noqa: S301
+
+    module_name = payload["module"]
+    func_name = payload["function"]
+    args = payload["args"]
+    kwargs = payload["kwargs"]
+
+    try:
+        fn = _resolve_function(module_name, func_name)
+        result = fn(*args, **kwargs)
+
+        # Serialize result
+        with open(work_dir / "result.pkl", "wb") as f:
+            pickle.dump(result, f)
+
+        (work_dir / "status.json").write_text(json.dumps({"success": True}))
+
+    except Exception as exc:
+        (work_dir / "status.json").write_text(json.dumps({"success": False}))
+        try:
+            with open(work_dir / "exception.pkl", "wb") as f:
+                pickle.dump(exc, f)
+        except Exception:
+            # Fallback for unpicklable exceptions
+            with open(work_dir / "exception.pkl", "wb") as f:
+                pickle.dump(RuntimeError(repr(exc)), f)
+
+
+if __name__ == "__main__":
+    assert (
+        len(sys.argv) == 2
+    ), f"Usage: python -m casher._runner <work_dir>, got {sys.argv}"
+    run(Path(sys.argv[1]))

casher/acache.py

@@ -0,0 +1,138 @@
+import argparse
+import hashlib
+import shutil
+import sys
+import time
+from pathlib import Path
+
+from loguru import logger
+
+from casher.config import (
+    DEFAULT_CACHE_DIR,
+    DEFAULT_MAX_CACHE_BYTES,
+    HASH_ALGORITHM,
+    OUTPUT_FILES_DIR,
+)
+from casher.hasher import compute_file_hash
+from casher.store import CacheEntry, find_cached, store_result
+from casher.strace import is_strace_available, run_with_strace
+
+
+def _compute_command_partial_key(cmd: list[str]) -> str:
+    h = hashlib.new(HASH_ALGORITHM)
+    h.update(" ".join(cmd).encode())
+    return h.hexdigest()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Cache results of arbitrary CLI programs using strace.",
+        usage="acache [--cache-dir DIR] [--max-cache-bytes N] -- command...",
+    )
+    parser.add_argument("--cache-dir", type=Path, default=None)
+    parser.add_argument("--max-cache-bytes", type=int, default=None)
+
+    # Split on -- to separate acache args from the command
+    argv = sys.argv[1:]
+    if "--" in argv:
+        split_idx = argv.index("--")
+        acache_args = argv[:split_idx]
+        cmd = argv[split_idx + 1 :]
+    else:
+        acache_args = []
+        cmd = argv
+
+    if not cmd:
+        raise SystemExit("No command provided. Usage: acache [options] -- command...")
+
+    args = parser.parse_args(acache_args)
+    cache_dir = args.cache_dir or DEFAULT_CACHE_DIR
+    max_bytes = (
+        args.max_cache_bytes
+        if args.max_cache_bytes is not None
+        else DEFAULT_MAX_CACHE_BYTES
+    )
+
+    logger.info("acache: cmd={} | cache_dir={}", " ".join(cmd), cache_dir)
+
+    if not is_strace_available():
+        raise SystemExit(
+            "strace is required for acache. "
+            "Install it (e.g., 'sudo pacman -S strace') or use the Python decorator API."
+        )
+
+    partial_key = _compute_command_partial_key(cmd)
+
+    # Phase 1: cache lookup
+    cached_result = find_cached(cache_dir, partial_key)
+    if cached_result is not None:
+        entry, entry_dir = cached_result
+        logger.info("acache cache HIT: key={}…", partial_key[:12])
+
+        # Replay stdout/stderr
+        if entry.stdout:
+            sys.stdout.write(entry.stdout)
+        if entry.stderr:
+            sys.stderr.write(entry.stderr)
+
+        # Restore output files
+        output_dir = entry_dir / OUTPUT_FILES_DIR
+        for rel_path in entry.output_files:
+            safe_path = rel_path.lstrip("/")
+            cached_path = output_dir / safe_path
+            if not cached_path.exists():
+                continue
+            target = Path(rel_path)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(str(cached_path), str(target))
+
+        sys.exit(int(entry.return_value))
+
+    # Phase 2: trace and store
+    logger.info("acache cache MISS: key={}… | tracing with strace", partial_key[:12])
+    strace_result = run_with_strace(cmd)
+
+    # Classify files
+    read_files = [p for p in strace_result.read_files if p.is_file()]
+    write_files = [p for p in strace_result.write_files if p.is_file()]
+
+    # Compute file hash from read files
+    if read_files:
+        file_hash = compute_file_hash(read_files)
+    else:
+        file_hash = "none"
+
+    # Build input_files dict
+    input_files_dict: dict[str, str] = {}
+    for p in read_files:
+        input_files_dict[str(p)] = compute_file_hash([p])
+
+    # Build output_files dict
+    output_files_dict: dict[str, Path] = {}
+    for p in write_files:
+        output_files_dict[str(p)] = p
+
+    entry = CacheEntry(
+        return_value=strace_result.returncode,
+        stdout=strace_result.stdout,
+        stderr=strace_result.stderr,
+        output_files=output_files_dict,
+        input_files=input_files_dict,
+        created_at=time.time(),
+        func_module="acache",
+        func_name=" ".join(cmd),
+    )
+
+    store_result(cache_dir, partial_key, file_hash, entry, max_bytes=max_bytes)
+
+    # Output stdout/stderr
+    if strace_result.stdout:
+        sys.stdout.write(strace_result.stdout)
+    if strace_result.stderr:
+        sys.stderr.write(strace_result.stderr)
+
+    sys.exit(strace_result.returncode)
+
+
+if __name__ == "__main__":
+    main()

casher/audit_hook.py

@@ -0,0 +1,65 @@
+import contextvars
+import sys
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+
+
+_active_tracker: contextvars.ContextVar["FileIOTracker | None"] = (
+    contextvars.ContextVar("casher_file_tracker", default=None)
+)
+_hook_installed = False
+
+_READ_MODES = {"r", "rb", "rt"}
+_WRITE_MODES = {"w", "wb", "wt", "a", "ab", "at", "x", "xb", "xt"}
+
+
+class FileIOTracker:
+    def __init__(self) -> None:
+        self.read_files: list[Path] = []
+        self.write_files: list[Path] = []
+        self._seen_read: set[str] = set()
+        self._seen_write: set[str] = set()
+
+    def record(self, path: str, mode: str) -> None:
+        if mode in _WRITE_MODES:
+            if path not in self._seen_write:
+                self._seen_write.add(path)
+                self.write_files.append(Path(path))
+        elif mode in _READ_MODES:
+            if path not in self._seen_read:
+                self._seen_read.add(path)
+                self.read_files.append(Path(path))
+
+
+def _audit_hook(event: str, args: tuple) -> None:
+    if event != "open":
+        return
+    tracker = _active_tracker.get()
+    if tracker is None:
+        return
+    # args for "open" event: (path, mode, flags)
+    path = args[0]
+    mode = args[1]
+    if not isinstance(path, str) or not isinstance(mode, str):
+        return
+    tracker.record(path, mode)
+
+
+def _ensure_hook_installed() -> None:
+    global _hook_installed
+    if _hook_installed:
+        return
+    sys.addaudithook(_audit_hook)
+    _hook_installed = True
+
+
+@contextmanager
+def track_file_io() -> Generator[FileIOTracker, None, None]:
+    _ensure_hook_installed()
+    tracker = FileIOTracker()
+    token = _active_tracker.set(tracker)
+    try:
+        yield tracker
+    finally:
+        _active_tracker.reset(token)

casher/auto_cli.py

@@ -0,0 +1,52 @@
+import argparse
+import inspect
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+
+_TYPE_MAP = {
+    str: str,
+    int: int,
+    float: float,
+    Path: Path,
+}
+
+
+def run(func: Callable) -> None:
+    """Generate CLI from function signature and run it."""
+    sig = inspect.signature(func)
+    parser = argparse.ArgumentParser(description=func.__doc__ or "")
+
+    for name, param in sig.parameters.items():
+        annotation = (
+            param.annotation if param.annotation != inspect.Parameter.empty else str
+        )
+
+        if param.default is inspect.Parameter.empty:
+            # Positional argument
+            parser.add_argument(name, type=_TYPE_MAP.get(annotation, str))
+        else:
+            cli_name = f"--{name.replace('_', '-')}"
+            if annotation is bool:
+                if param.default is False:
+                    parser.add_argument(cli_name, action="store_true", dest=name)
+                else:
+                    parser.add_argument(cli_name, action="store_false", dest=name)
+            else:
+                parser.add_argument(
+                    cli_name,
+                    type=_TYPE_MAP.get(annotation, str),
+                    default=param.default,
+                    dest=name,
+                )
+
+    args = parser.parse_args()
+    result = func(**vars(args))
+    if result is None:
+        return
+    module = type(result).__module__
+    if module.startswith("polars") or module.startswith("pandas"):
+        sys.stdout.write(result.to_csv())
+    else:
+        print(result)

casher/capture.py

@@ -0,0 +1,29 @@
+import shutil
+import sys
+from pathlib import Path
+
+from casher.config import OUTPUT_FILES_DIR
+from casher.store import CacheEntry
+
+
+def replay_side_effects(entry: CacheEntry, entry_dir: Path) -> None:
+    """Replay cached side effects:
+    - print stdout to sys.stdout
+    - print stderr to sys.stderr
+    - restore output files from cache to their original paths
+    """
+    if entry.stdout:
+        sys.stdout.write(entry.stdout)
+
+    if entry.stderr:
+        sys.stderr.write(entry.stderr)
+
+    output_dir = entry_dir / OUTPUT_FILES_DIR
+    for rel_path in entry.output_files:
+        safe_path = rel_path.lstrip("/")
+        cached_path = output_dir / safe_path
+        if not cached_path.exists():
+            continue
+        target = Path(rel_path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(str(cached_path), str(target))

casher/config.py

@@ -0,0 +1,42 @@
+import os
+import sys
+from pathlib import Path
+
+# Environment variable names
+CACHE_DIR_ENV_VAR = "CASHER_CACHE_DIR"
+MAX_CACHE_BYTES_ENV_VAR = "CASHER_MAX_CACHE_BYTES"
+
+# Defaults
+_DEFAULT_CACHE_DIR_PATH = Path("~/.cache/casher").expanduser()
+_DEFAULT_MAX_CACHE_BYTES = 32 * 1024 * 1024 * 1024  # 32 GB
+
+DEFAULT_CACHE_DIR = Path(os.environ.get(CACHE_DIR_ENV_VAR, str(_DEFAULT_CACHE_DIR_PATH)))
+DEFAULT_MAX_CACHE_BYTES = int(os.environ.get(MAX_CACHE_BYTES_ENV_VAR, str(_DEFAULT_MAX_CACHE_BYTES)))
+
+HASH_ALGORITHM = "sha256"
+META_FILENAME = "meta.json"
+RESULT_FILENAME = "result.pkl"
+STDOUT_FILENAME = "stdout.txt"
+STDERR_FILENAME = "stderr.txt"
+OUTPUT_FILES_DIR = "output_files"
+
+# Platform support — caching only works on Linux (strace, audit hooks)
+PLATFORM_SUPPORTED = sys.platform == "linux"
+
+# strace filtering: paths matching these prefixes are NOT considered user file I/O
+STRACE_IGNORE_PREFIXES = (
+    "/dev/",
+    "/proc/",
+    "/sys/",
+    "/tmp/casher-",
+    "/usr/lib/",
+    "/lib/",
+    "/usr/local/lib/",
+    "/usr/share/",
+    "/etc/",
+)
+STRACE_IGNORE_SUFFIXES = (".pyc", ".pyo", ".so", ".dll", ".pth")
+STRACE_IGNORE_CONTAINS = ("__pycache__", "site-packages", "/python3.")
+
+# Dependency tracking: paths to consider as "own code"
+DEFAULT_DEP_ROOTS: list[Path] = []