pycasher 0.1.0__tar.gz

pycasher-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+*.egg
+.pytest_cache/
+.ruff_cache/
+tmp_test_data/

pycasher-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 casher contributors
+
+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.

pycasher-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: pycasher
+Version: 0.1.0
+Summary: Cache function results and side effects (stdout, stderr, file writes) with automatic file I/O discovery via strace or audit hooks
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: loguru
+Provides-Extra: pandas
+Requires-Dist: pandas; extra == 'pandas'
+Requires-Dist: pyarrow; extra == 'pandas'
+Provides-Extra: polars
+Requires-Dist: polars; extra == 'polars'
+Description-Content-Type: text/markdown
+
+# pycasher
+
+Cache Python function results **and their side effects** — stdout, stderr, and filesystem writes — with automatic invalidation.
+
+```bash
+pip install pycasher
+```
+
+## What makes it different
+
+Most caching libraries cache return values. casher also captures and replays:
+
+- **stdout/stderr** printed during execution
+- **Files written** by the function (restored from cache on hit)
+- **Files read** by the function (used as cache keys — change an input file, cache auto-invalidates)
+
+No manual file declarations needed. casher discovers file I/O automatically via `strace` (subprocess mode) or Python audit hooks (in-process mode).
+
+## Usage
+
+```python
+from casher import cached
+
+@cached
+def train(data_path: str, output_path: str, lr: float = 0.01) -> dict:
+    df = read_csv(data_path)
+    model = fit(df, lr=lr)
+    save(model, output_path)
+    return {"accuracy": model.score}
+
+# First call — runs function, traces file I/O, caches everything
+result = train("train.csv", "model.pkl")
+
+# Second call — instant replay from cache (model.pkl restored too)
+result = train("train.csv", "model.pkl")
+
+# Change train.csv — casher detects it, re-runs automatically
+```
+
+Cache any shell command without code changes:
+
+```bash
+acache -- python train.py --data train.csv
+```
+
+## Key features
+
+- **Automatic file tracking**: strace (kernel-level, catches C extensions) or audit hooks (zero overhead, Python-only)
+- **Dependency invalidation**: changes to imported `.py` files invalidate the cache
+- **LRU eviction**: configurable via `max_cache_bytes` or `CASHER_MAX_CACHE_BYTES` env var (default 32 GB)
+- **DataFrame support**: polars and pandas DataFrames serialized via Arrow IPC
+- **Environment-aware**: include env vars in cache key with `env_vars=["MY_VAR"]`
+- **Structured logging**: loguru INFO for every call — cache dir, hit/miss, mode, eviction
+
+## Configuration
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `CASHER_CACHE_DIR` | `~/.cache/casher` | Cache storage directory |
+| `CASHER_MAX_CACHE_BYTES` | `34359738368` (32 GB) | Max cache size before LRU eviction |
+
+## Platform support
+
+Full caching on **Linux** only (requires strace for subprocess mode, fcntl for locking). On macOS and Windows the decorator is a transparent pass-through — functions execute normally, caching is skipped with a one-time warning.
+
+## Documentation
+
+See [documentation/](documentation/) for detailed docs:
+
+- [Introduction](documentation/00-Introduction.md) — architecture, limitations, in-process vs subprocess comparison
+- [Quick Start](documentation/10-Quick-Start.md) — installation, decorator options, CLI usage
+- [API Reference](documentation/20-API-Reference.md) — full API surface
+
+## License
+
+MIT

pycasher-0.1.0/README.md

@@ -0,0 +1,76 @@
+# pycasher
+
+Cache Python function results **and their side effects** — stdout, stderr, and filesystem writes — with automatic invalidation.
+
+```bash
+pip install pycasher
+```
+
+## What makes it different
+
+Most caching libraries cache return values. casher also captures and replays:
+
+- **stdout/stderr** printed during execution
+- **Files written** by the function (restored from cache on hit)
+- **Files read** by the function (used as cache keys — change an input file, cache auto-invalidates)
+
+No manual file declarations needed. casher discovers file I/O automatically via `strace` (subprocess mode) or Python audit hooks (in-process mode).
+
+## Usage
+
+```python
+from casher import cached
+
+@cached
+def train(data_path: str, output_path: str, lr: float = 0.01) -> dict:
+    df = read_csv(data_path)
+    model = fit(df, lr=lr)
+    save(model, output_path)
+    return {"accuracy": model.score}
+
+# First call — runs function, traces file I/O, caches everything
+result = train("train.csv", "model.pkl")
+
+# Second call — instant replay from cache (model.pkl restored too)
+result = train("train.csv", "model.pkl")
+
+# Change train.csv — casher detects it, re-runs automatically
+```
+
+Cache any shell command without code changes:
+
+```bash
+acache -- python train.py --data train.csv
+```
+
+## Key features
+
+- **Automatic file tracking**: strace (kernel-level, catches C extensions) or audit hooks (zero overhead, Python-only)
+- **Dependency invalidation**: changes to imported `.py` files invalidate the cache
+- **LRU eviction**: configurable via `max_cache_bytes` or `CASHER_MAX_CACHE_BYTES` env var (default 32 GB)
+- **DataFrame support**: polars and pandas DataFrames serialized via Arrow IPC
+- **Environment-aware**: include env vars in cache key with `env_vars=["MY_VAR"]`
+- **Structured logging**: loguru INFO for every call — cache dir, hit/miss, mode, eviction
+
+## Configuration
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `CASHER_CACHE_DIR` | `~/.cache/casher` | Cache storage directory |
+| `CASHER_MAX_CACHE_BYTES` | `34359738368` (32 GB) | Max cache size before LRU eviction |
+
+## Platform support
+
+Full caching on **Linux** only (requires strace for subprocess mode, fcntl for locking). On macOS and Windows the decorator is a transparent pass-through — functions execute normally, caching is skipped with a one-time warning.
+
+## Documentation
+
+See [documentation/](documentation/) for detailed docs:
+
+- [Introduction](documentation/00-Introduction.md) — architecture, limitations, in-process vs subprocess comparison
+- [Quick Start](documentation/10-Quick-Start.md) — installation, decorator options, CLI usage
+- [API Reference](documentation/20-API-Reference.md) — full API surface
+
+## License
+
+MIT

pycasher-0.1.0/documentation/00-Introduction.md

@@ -0,0 +1,75 @@
+# casher — Function Result Cache with Side-Effect Capture
+
+`casher` caches Python function results **and** their side effects
+(stdout, stderr, filesystem writes). It automatically discovers file I/O
+via `strace` (subprocess mode) or `sys.addaudithook` (in-process mode),
+so cache invalidation happens without explicit file declarations.
+
+Install from PyPI: `pip install pycasher`
+
+## What it provides
+
+- A `@cached` decorator that transparently caches any Python function.
+- Automatic file I/O tracking — reads become cache keys, writes are
+  restored on cache hit.
+- Two-phase cache lookup: partial key (function + args) → full key
+  (partial + input file hashes).
+- Dependency tracking — changes to imported modules invalidate the cache.
+- LRU eviction with configurable `max_cache_bytes` (default 32 GB).
+- `acache` CLI tool for caching arbitrary shell commands.
+- `auto_cli` helper to generate argparse CLIs from decorated functions.
+- Polars and pandas DataFrame serialization via Arrow IPC.
+- Structured logging via loguru at INFO level.
+
+## Configuration via environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CASHER_CACHE_DIR` | `~/.cache/casher` | Cache storage directory |
+| `CASHER_MAX_CACHE_BYTES` | `34359738368` (32 GB) | Max total cache size before LRU eviction |
+
+These are used when no explicit value is passed to the `@cached` decorator
+or the `acache` CLI.
+
+## Cross-platform behavior
+
+casher's full feature set (strace-based file tracking, `fcntl` locking)
+requires Linux. On **macOS** and **Windows**, caching is automatically
+disabled with a `logger.warning`. The decorated function still runs
+normally — it just never caches.
+
+## In-process vs. subprocess mode
+
+| Aspect | `subprocess=True` (default) | `subprocess=False` |
+|--------|----------------------------|---------------------|
+| File tracking | strace — kernel-level, catches all I/O including from C extensions and child processes | `sys.addaudithook` — Python-level, catches only `open()` calls from Python code |
+| Dynamic imports | Fully captured (subprocess loads fresh) | May be missed if imported after function entry |
+| Isolation | Function runs in a separate process — no side effects on caller's globals | Function runs in the same process — shared state, faster startup |
+| Overhead | ~5–15% from strace tracing | Near-zero |
+| Requirements | strace installed, Linux | Python 3.12+, any OS (but caching only active on Linux) |
+| Best for | Data pipelines, scripts with C extensions, shell commands | Pure-Python functions, fast inner loops, environments without strace |
+
+**Why not always use in-process?** The audit hook only intercepts Python's
+built-in `open()`. File I/O from C extensions (numpy, pandas, polars
+native readers), subprocess calls, or `os.read()`/`os.write()` is
+invisible to it. strace intercepts at the kernel level, so nothing escapes.
+
+## Limitations
+
+- **Linux only** for caching. On macOS/Windows the decorator is a
+  transparent pass-through with a one-time warning.
+- **strace in Docker**: requires `--cap-add=SYS_PTRACE` or an equivalent
+  seccomp profile that allows the `ptrace` syscall.
+- **Security**: cache entries use pickle. Never point `cache_dir` at a
+  shared or untrusted directory. Keep cache directories user-writable only.
+- **strace overhead**: ~5–15% for typical data-processing functions.
+  Negligible for functions taking seconds or longer. For sub-millisecond
+  functions, use `subprocess=False`.
+- **No exception caching.** Failed function calls are never cached.
+- **No concurrent write safety** beyond `fcntl.flock`. Do not share
+  cache directories across networked filesystems.
+
+## Runtime dependencies
+
+Only `loguru`. Polars and pandas support is optional — detected at
+runtime via `type(val).__module__`.

pycasher-0.1.0/documentation/10-Quick-Start.md

@@ -0,0 +1,98 @@
+# Quick Start
+
+## Installation
+
+```bash
+pip install pycasher
+# Optional DataFrame support:
+pip install pycasher[polars]
+```
+
+## Decorator usage
+
+```python
+from casher import cached
+
+@cached
+def transform(input_path: str, output_path: str, threshold: float = 0.5) -> int:
+    import polars as pl
+    df = pl.read_csv(input_path)
+    df = df.filter(pl.col("score") > threshold)
+    df.write_parquet(output_path)
+    return len(df)
+
+# First call — runs the function, caches result + side effects
+result = transform("data.csv", "output.parquet", threshold=0.3)
+
+# Second call — cache hit, restores output.parquet from cache
+result = transform("data.csv", "output.parquet", threshold=0.3)
+```
+
+## Decorator options
+
+```python
+@cached(
+    cache_dir="~/.cache/casher",     # default cache location
+    subprocess=True,                  # True=strace (default), False=audit hooks
+    enabled=True,                     # set False to bypass caching
+    dep_roots=None,                   # directories to scan for dependency changes
+    input_files=None,                 # extra files to include in cache key
+    ignore_files=None,                # glob patterns to exclude from tracking
+    env_vars=None,                    # environment variables to include in cache key
+    max_cache_bytes=0,                # 0=unlimited, default 32 GB via env var
+)
+```
+
+## In-process mode
+
+When strace is unavailable or overhead matters, use audit hooks:
+
+```python
+@cached(subprocess=False)
+def process(path: str) -> str:
+    with open(path) as f:
+        return f.read().upper()
+```
+
+File I/O is tracked via `sys.addaudithook`. No subprocess is spawned.
+
+## CLI caching with acache
+
+Cache any shell command:
+
+```bash
+# First run — traces file I/O, caches result
+acache -- python train.py --data train.csv
+
+# Second run — cache hit if train.csv unchanged
+acache -- python train.py --data train.csv
+
+# Custom cache directory
+acache --cache-dir /tmp/mycache -- python train.py --data train.csv
+```
+
+## Auto-CLI from decorated functions
+
+```python
+# transform.py
+from casher import cached
+from casher.auto_cli import run
+
+@cached
+def transform(input_path: str, output_path: str, threshold: float = 0.5) -> int:
+    ...
+
+if __name__ == "__main__":
+    run(transform)
+```
+
+```bash
+python transform.py data.csv output.parquet --threshold 0.3
+```
+
+## Running tests
+
+```bash
+cd casher
+./test.sh
+```

pycasher-0.1.0/documentation/20-API-Reference.md

@@ -0,0 +1,133 @@
+# API Reference
+
+## `casher.cached`
+
+```python
+from casher import cached
+
+@cached(
+    cache_dir: str | Path = "~/.cache/casher",
+    subprocess: bool = True,
+    enabled: bool = True,
+    dep_roots: list[str] | None = None,
+    input_files: list[str] | None = None,
+    ignore_files: list[str] | None = None,
+    env_vars: list[str] | None = None,
+    max_cache_bytes: int = 0,
+)
+def my_func(...) -> ...:
+    ...
+```
+
+| Parameter         | Description                                                                                            |
+| ----------------- | ------------------------------------------------------------------------------------------------------ |
+| `cache_dir`       | Directory for cache storage. Default: `CASHER_CACHE_DIR` env var, then `~/.cache/casher`. |
+| `subprocess`      | `True`: run in subprocess with strace tracking. `False`: run in-process with audit hooks. |
+| `enabled`         | Set `False` to bypass caching entirely. Also auto-disabled on non-Linux. |
+| `dep_roots`       | Directories to scan for Python dependency changes. `None` = auto-detect from function module location. |
+| `input_files`     | Extra files to include in cache key beyond auto-discovered ones.                                       |
+| `ignore_files`    | Glob patterns for files to exclude from cache key (e.g., `["*.log"]`).                                 |
+| `env_vars`        | Environment variable names to include in cache key.                                                    |
+| `max_cache_bytes` | Maximum total cache size in bytes. Default: `CASHER_MAX_CACHE_BYTES` env var, then 32 GB. `0` = unlimited. |
+
+## Cache key computation
+
+1. **Partial key** = `sha256(module + func_name + canonical_args + dep_hash + env_hash)`
+2. **Full key** = `sha256(partial_key + input_file_hashes)`
+
+Cache directory layout: `<cache_dir>/<partial_key>/<full_key>/meta.json`
+
+## `casher.auto_cli.run`
+
+```python
+from casher.auto_cli import run
+run(func)
+```
+
+Generates an `argparse.ArgumentParser` from the function's signature and
+type annotations, parses `sys.argv`, and calls the function.
+
+| Annotation | argparse type                |
+| ---------- | ---------------------------- |
+| `str`      | `str`                        |
+| `int`      | `int`                        |
+| `float`    | `float`                      |
+| `bool`     | `store_true` / `store_false` |
+| `Path`     | `Path`                       |
+
+## `acache` CLI
+
+```
+acache [--cache-dir DIR] [--max-cache-bytes N] -- command...
+```
+
+Caches arbitrary CLI programs using strace for I/O tracking. Requires
+strace to be installed.
+
+## `casher.store`
+
+```python
+from casher.store import find_cached, store_result, invalidate, clear_cache
+
+# Look up cache entry
+result = find_cached(cache_dir, partial_key)  # -> (CacheEntry, Path) | None
+
+# Store a new entry
+store_result(cache_dir, partial_key, file_hash, entry, max_bytes=0)
+
+# Remove entries for a partial key
+invalidate(cache_dir, partial_key)  # -> bool
+
+# Clear entire cache
+clear_cache(cache_dir)  # -> int (entries removed)
+```
+
+## `casher.store.CacheEntry`
+
+```python
+@dataclasses.dataclass
+class CacheEntry:
+    return_value: object
+    stdout: str
+    stderr: str
+    output_files: dict[str, Path]
+    input_files: dict[str, str]
+    created_at: float
+    func_module: str
+    func_name: str
+```
+
+## `casher.strace`
+
+```python
+from casher.strace import run_with_strace, is_strace_available
+
+available = is_strace_available()  # -> bool
+result = run_with_strace(["python", "script.py"])
+# result.read_files: list[Path]
+# result.write_files: list[Path]
+# result.stdout: str
+# result.stderr: str
+# result.returncode: int
+```
+
+## `casher.audit_hook`
+
+```python
+from casher.audit_hook import track_file_io
+
+with track_file_io() as tracker:
+    with open("data.txt") as f:
+        f.read()
+# tracker.read_files: set[Path]
+# tracker.write_files: set[Path]
+```
+
+## `casher.eviction`
+
+```python
+from casher.eviction import evict_if_needed, get_cache_size
+
+evicted = evict_if_needed(cache_dir, max_bytes)  # -> int
+total = get_cache_size(cache_dir)  # -> int (bytes)
+```

pycasher-0.1.0/documentation/_last-updated_.txt

@@ -0,0 +1 @@
+6ec95a80  # initial casher documentation