pycache-skip 0.1.0__py3-none-any.whl

cache_skip/__init__.py

@@ -0,0 +1,4 @@
+from cache_skip.decorator import cache_skip
+from cache_skip.dirmaker import Dirmaker
+
+__all__ = ["cache_skip", "Dirmaker"]

cache_skip/decorator.py

@@ -0,0 +1,186 @@
+import inspect
+import shutil
+from collections.abc import Callable
+from functools import wraps
+from pathlib import Path
+
+import xxhash
+from loguru import logger
+
+from . import deps as _deps
+from .scanner import scan_inputs
+from .state import FileRecord, InputState, read_state, write_state
+
+
+def _collect_input_paths(bound: inspect.BoundArguments) -> list[Path]:
+    paths = []
+    for name, value in bound.arguments.items():
+        if name == "_output":
+            continue
+        if isinstance(value, Path):
+            paths.append(value)
+    return paths
+
+
+def _compute_args_hash(bound: inspect.BoundArguments) -> str:
+    non_path_args: dict[str, str] = {}
+    for name, value in bound.arguments.items():
+        if name == "_output":
+            continue
+        if isinstance(value, Path):
+            continue
+        non_path_args[name] = repr(value)
+    combined = "|".join(f"{k}={v}" for k, v in sorted(non_path_args.items()))
+    return xxhash.xxh128(combined.encode()).hexdigest()
+
+
+def _compute_file_hash(path: Path) -> str:
+    return xxhash.xxh128(path.read_bytes()).hexdigest()
+
+
+def _do_rerun(
+    fn: Callable,
+    args: tuple,
+    kwargs: dict,
+    input_paths: list[Path],
+    args_hash: str,
+    dep_hash: str,
+    output: Path,
+) -> object:
+    shutil.rmtree(output, ignore_errors=True)
+    output.mkdir(parents=True, exist_ok=True)
+    result = fn(*args, **kwargs)
+    state = scan_inputs(input_paths)
+    state.args_hash = args_hash
+    state.dep_hash = dep_hash
+    write_state(state, output / ".input_state.json")
+    return result
+
+
+def cache_skip(
+    _fn: Callable | None = None,
+    *,
+    track_dependencies: bool = True,
+) -> Callable:
+    def decorator(fn: Callable) -> Callable:
+        @wraps(fn)
+        def wrapper(*args, **kwargs):
+            # Step 0 — extract _output
+            output = kwargs.get("_output")
+            assert (
+                output is not None
+            ), f"{fn.__qualname__}() missing required keyword argument: '_output'"
+            output = Path(output)
+
+            # Step 1 — collect input Paths
+            sig = inspect.signature(fn)
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+            input_paths = _collect_input_paths(bound)
+
+            # Step 2 — compute args_hash
+            args_hash = _compute_args_hash(bound)
+
+            # Step 3 — compute dep_hash
+            if track_dependencies:
+                dep_hash = _deps.compute_dep_hash(fn)
+            else:
+                dep_hash = ""
+
+            # Step 4 — output absent → fresh run
+            if not output.exists():
+                output.mkdir(parents=True, exist_ok=True)
+                result = fn(*args, **kwargs)
+                state = scan_inputs(input_paths)
+                state.args_hash = args_hash
+                state.dep_hash = dep_hash
+                write_state(state, output / ".input_state.json")
+                logger.info(
+                    "cache_skip: ran {} — output did not exist", fn.__qualname__
+                )
+                return result
+
+            # Step 5 — output present → compare state
+            state_path = output / ".input_state.json"
+            if not state_path.exists():
+                logger.info("cache_skip: rerunning {} — no state file", fn.__qualname__)
+                return _do_rerun(
+                    fn, args, kwargs, input_paths, args_hash, dep_hash, output
+                )
+
+            stored = read_state(state_path)
+
+            if stored.args_hash != args_hash:
+                logger.info("cache_skip: rerunning {} — args changed", fn.__qualname__)
+                return _do_rerun(
+                    fn, args, kwargs, input_paths, args_hash, dep_hash, output
+                )
+
+            if stored.dep_hash != dep_hash:
+                logger.info(
+                    "cache_skip: rerunning {} — dep_hash changed", fn.__qualname__
+                )
+                return _do_rerun(
+                    fn, args, kwargs, input_paths, args_hash, dep_hash, output
+                )
+
+            current = scan_inputs(input_paths)
+
+            if set(current.files) != set(stored.files):
+                logger.info(
+                    "cache_skip: rerunning {} — file set changed", fn.__qualname__
+                )
+                return _do_rerun(
+                    fn, args, kwargs, input_paths, args_hash, dep_hash, output
+                )
+
+            changed = False
+            updated_files: dict[str, FileRecord] = {}
+
+            for path_str, current_rec in current.files.items():
+                stored_rec = stored.files.get(path_str)
+                if stored_rec is None:
+                    changed = True
+                    break
+
+                if (
+                    current_rec.mtime == stored_rec.mtime
+                    and current_rec.size == stored_rec.size
+                    and current_rec.inode == stored_rec.inode
+                ):
+                    updated_files[path_str] = stored_rec
+                    continue
+
+                actual_hash = _compute_file_hash(Path(path_str))
+                if actual_hash == stored_rec.hash:
+                    updated_files[path_str] = FileRecord(
+                        path=path_str,
+                        mtime=current_rec.mtime,
+                        inode=current_rec.inode,
+                        size=current_rec.size,
+                        hash=actual_hash,
+                    )
+                else:
+                    changed = True
+                    break
+
+            if changed:
+                logger.info(
+                    "cache_skip: rerunning {} — file content changed", fn.__qualname__
+                )
+                return _do_rerun(
+                    fn, args, kwargs, input_paths, args_hash, dep_hash, output
+                )
+
+            if updated_files != stored.files:
+                stored.files = updated_files
+                write_state(stored, state_path)
+
+            logger.info("cache_skip: skipping {} — inputs unchanged", fn.__qualname__)
+            return output
+
+        return wrapper
+
+    if _fn is not None:
+        return decorator(_fn)
+    return decorator

cache_skip/deps.py

@@ -0,0 +1,156 @@
+import ast
+import inspect
+from collections.abc import Callable
+from pathlib import Path
+
+import xxhash
+
+
+def compute_dep_hash(
+    func: Callable,
+    dep_roots: list[Path] | None = None,
+    dep_files: list[Path] | None = None,
+) -> str:
+    if dep_files is not None:
+        return _hash_files(dep_files)
+
+    mod = inspect.getmodule(func)
+    assert mod is not None, f"Cannot determine module for {func}"
+    assert (
+        hasattr(mod, "__file__") and mod.__file__ is not None
+    ), f"Module {mod.__name__} has no __file__"
+
+    if dep_roots is None:
+        dep_roots = _auto_detect_roots(mod)
+
+    dep_roots_resolved = [Path(r).resolve() for r in dep_roots]
+    start_file = Path(mod.__file__).resolve()
+
+    visited: set[Path] = set()
+    _walk_imports(start_file, dep_roots_resolved, visited, is_entry=True)
+
+    return _hash_files(list(visited))
+
+
+def _auto_detect_roots(mod) -> list[Path]:
+    mod_file = Path(mod.__file__).resolve()
+    parts = mod.__name__.split(".")
+    pkg_dir = mod_file.parent
+    for _ in range(len(parts) - 1):
+        pkg_dir = pkg_dir.parent
+    return [pkg_dir]
+
+
+def _hash_files(paths: list[Path]) -> str:
+    file_hashes: list[tuple[str, str]] = []
+    for src_path in sorted(paths, key=lambda p: str(p.resolve())):
+        resolved = src_path.resolve()
+        content_hash = xxhash.xxh128(resolved.read_bytes()).hexdigest()
+        file_hashes.append((str(resolved), content_hash))
+    combined = "\n".join(f"{p}:{h}" for p, h in file_hashes)
+    return xxhash.xxh128(combined.encode()).hexdigest()
+
+
+def _walk_imports(
+    source_file: Path,
+    dep_roots: list[Path],
+    visited: set[Path],
+    *,
+    is_entry: bool = False,
+) -> None:
+    source_file = source_file.resolve()
+    if source_file in visited:
+        return
+    if not source_file.is_file() or source_file.suffix != ".py":
+        return
+    if not is_entry and not any(_is_under(source_file, root) for root in dep_roots):
+        return
+
+    visited.add(source_file)
+
+    try:
+        tree = ast.parse(source_file.read_bytes(), filename=str(source_file))
+    except SyntaxError:
+        return
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                resolved = _resolve_module(alias.name, source_file, dep_roots)
+                if resolved:
+                    _walk_imports(resolved, dep_roots, visited)
+        elif isinstance(node, ast.ImportFrom):
+            if node.module is None:
+                continue
+            module_name = node.module
+            if node.level > 0:
+                module_name = _resolve_relative(
+                    module_name, node.level, source_file, dep_roots
+                )
+                if module_name is None:
+                    continue
+            resolved = _resolve_module(module_name, source_file, dep_roots)
+            if resolved:
+                _walk_imports(resolved, dep_roots, visited)
+
+
+def _resolve_module(
+    module_name: str,
+    from_file: Path,
+    dep_roots: list[Path],
+) -> Path | None:
+    parts = module_name.split(".")
+    for root in dep_roots:
+        pkg_path = root / "/".join(parts) / "__init__.py"
+        if pkg_path.is_file():
+            return pkg_path.resolve()
+        mod_path = (
+            root / "/".join(parts[:-1]) / (parts[-1] + ".py")
+            if len(parts) > 1
+            else root / (parts[0] + ".py")
+        )
+        if mod_path.is_file():
+            return mod_path.resolve()
+        for i in range(len(parts), 0, -1):
+            sub = parts[:i]
+            pkg_init = root / "/".join(sub) / "__init__.py"
+            if pkg_init.is_file():
+                return pkg_init.resolve()
+            mod_file = (
+                root / "/".join(sub[:-1]) / (sub[-1] + ".py")
+                if len(sub) > 1
+                else root / (sub[0] + ".py")
+            )
+            if mod_file.is_file():
+                return mod_file.resolve()
+    return None
+
+
+def _resolve_relative(
+    module_name: str,
+    level: int,
+    from_file: Path,
+    dep_roots: list[Path],
+) -> str | None:
+    pkg_dir = from_file.parent
+    for _ in range(level - 1):
+        pkg_dir = pkg_dir.parent
+    for root in dep_roots:
+        if _is_under(pkg_dir, root):
+            try:
+                rel = pkg_dir.relative_to(root)
+                prefix = ".".join(rel.parts)
+                if prefix and module_name:
+                    return f"{prefix}.{module_name}"
+                return prefix or module_name
+            except ValueError:
+                continue
+    return None
+
+
+def _is_under(path: Path, root: Path) -> bool:
+    try:
+        path.relative_to(root)
+        return True
+    except ValueError:
+        return False

cache_skip/dirmaker.py

@@ -0,0 +1,32 @@
+"""Dirmaker — manages output paths under a pipeline staging root."""
+
+import shutil
+from pathlib import Path
+
+from loguru import logger
+
+
+class Dirmaker:
+    """Allocates named output directories under a staging root.
+
+    Each pipeline step requests a named output directory via new_output_dir().
+    The Dirmaker creates it and returns the path. Steps write all their
+    outputs there — never to input directories.
+    """
+
+    def __init__(self, base: Path):
+        self.root = Path(base)
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def new_output_dir(self, name: str) -> Path:
+        """Allocate a named output directory. Deletes existing output if present."""
+        out = self.root / name
+        if out.exists():
+            logger.info(f"Removing existing output dir: {out}")
+            shutil.rmtree(out)
+        out.mkdir(parents=True, exist_ok=True)
+        return out
+
+    def path_for(self, name: str) -> Path:
+        """Resolve output path for a step (no side effects)."""
+        return self.root / name

cache_skip/scanner.py

@@ -0,0 +1,38 @@
+import os
+from pathlib import Path
+
+import xxhash
+
+from .state import FileRecord, InputState
+
+
+def _hash_file(path: Path) -> str:
+    return xxhash.xxh128(path.read_bytes()).hexdigest()
+
+
+def _make_record(p: Path) -> FileRecord:
+    stat = os.stat(p)
+    return FileRecord(
+        path=str(p),
+        mtime=stat.st_mtime_ns / 1e9,
+        inode=stat.st_ino,
+        size=stat.st_size,
+        hash=_hash_file(p),
+    )
+
+
+def scan_inputs(input_paths: list[Path]) -> InputState:
+    files: dict[str, FileRecord] = {}
+    for path in input_paths:
+        assert path.exists(), f"Input path does not exist: {path}"
+        if path.is_file():
+            p = path.resolve()
+            files[str(p)] = _make_record(p)
+        elif path.is_dir():
+            for root, _, filenames in os.walk(path):
+                for fn in filenames:
+                    if fn == ".input_state.json":
+                        continue
+                    p = Path(root, fn).resolve()
+                    files[str(p)] = _make_record(p)
+    return InputState(version=1, files=files, args_hash="", dep_hash="")

cache_skip/state.py

@@ -0,0 +1,36 @@
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+@dataclass
+class FileRecord:
+    path: str
+    mtime: float
+    inode: int
+    size: int
+    hash: str
+
+
+@dataclass
+class InputState:
+    version: int
+    files: dict[str, FileRecord]
+    args_hash: str
+    dep_hash: str
+
+
+def write_state(state: InputState, path: Path) -> None:
+    path.write_text(json.dumps(asdict(state), indent=2))
+
+
+def read_state(path: Path) -> InputState:
+    data = json.loads(path.read_text())
+    assert data["version"] == 1, f"Unknown state version: {data['version']}"
+    files = {k: FileRecord(**v) for k, v in data["files"].items()}
+    return InputState(
+        version=data["version"],
+        files=files,
+        args_hash=data["args_hash"],
+        dep_hash=data["dep_hash"],
+    )

cache_skip/tests/test_decorator.py

@@ -0,0 +1,228 @@
+import os
+import shutil
+from datetime import date
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from cache_skip.decorator import cache_skip
+from cache_skip.state import read_state
+
+
+@pytest.fixture
+def inp(tmp_path):
+    d = tmp_path / "input"
+    d.mkdir()
+    (d / "data.txt").write_bytes(b"hello")
+    return d
+
+
+def test_first_call_creates_output_and_state(tmp_path, inp):
+    output = tmp_path / "output"
+    calls = []
+
+    @cache_skip(track_dependencies=False)
+    def step(i: Path, _output: Path):
+        calls.append(1)
+
+    step(inp, _output=output)
+    assert len(calls) == 1
+    assert output.exists()
+    assert (output / ".input_state.json").exists()
+
+
+def test_second_call_no_changes_skips(tmp_path, inp):
+    output = tmp_path / "output"
+    calls = []
+
+    @cache_skip(track_dependencies=False)
+    def step(i: Path, _output: Path):
+        calls.append(1)
+
+    step(inp, _output=output)
+    result = step(inp, _output=output)
+    assert len(calls) == 1
+    assert result == output
+
+
+def test_second_call_input_changed_reruns(tmp_path, inp):
+    output = tmp_path / "output"
+    calls = []
+
+    @cache_skip(track_dependencies=False)
+    def step(i: Path, _output: Path):
+        calls.append(1)
+
+    step(inp, _output=output)
+    (inp / "data.txt").write_bytes(b"changed content")
+    step(inp, _output=output)
+    assert len(calls) == 2
+
+
+def test_metadata_drift_same_content_no_rerun(tmp_path, inp):
+    output = tmp_path / "output"
+    calls = []
+
+    @cache_skip(track_dependencies=False)
+    def step(i: Path, _output: Path):
+        calls.append(1)
+
+    step(inp, _output=output)
+
+    data_file = inp / "data.txt"
+    stat = os.stat(data_file)
+    os.utime(data_file, (stat.st_atime + 2.0, stat.st_mtime + 2.0))
+
+    result = step(inp, _output=output)
+    assert len(calls) == 1
+    assert result == output
+
+
+def test_args_changed_reruns(tmp_path, inp):
+    output = tmp_path / "output"
+    calls = []
+
+    @cache_skip(track_dependencies=False)
+    def step(i: Path, scale: int, _output: Path):
+        calls.append(1)
+
+    step(inp, 1, _output=output)
+    step(inp, 2, _output=output)
+    assert len(calls) == 2
+
+
+def test_dep_hash_changed_reruns(tmp_path, inp):
+    output = tmp_path / "output"
+    calls = []
+
+    @cache_skip
+    def step(i: Path, _output: Path):
+        calls.append(1)
+
+    with patch("cache_skip.deps.compute_dep_hash", return_value="hash_a" + "0" * 26):
+        step(inp, _output=output)
+    with patch("cache_skip.deps.compute_dep_hash", return_value="hash_b" + "0" * 26):
+        step(inp, _output=output)
+    assert len(calls) == 2
+
+
+def test_output_exists_no_state_file_reruns(tmp_path, inp):
+    output = tmp_path / "output"
+    output.mkdir()
+    calls = []
+
+    @cache_skip(track_dependencies=False)
+    def step(i: Path, _output: Path):
+        calls.append(1)
+
+    step(inp, _output=output)
+    assert len(calls) == 1
+
+
+def test_output_deleted_externally_runs_fresh(tmp_path, inp):
+    output = tmp_path / "output"
+    calls = []
+
+    @cache_skip(track_dependencies=False)
+    def step(i: Path, _output: Path):
+        calls.append(1)
+
+    step(inp, _output=output)
+    shutil.rmtree(output)
+    step(inp, _output=output)
+    assert len(calls) == 2
+
+
+def test_input_file_deleted_reruns(tmp_path, inp):
+    output = tmp_path / "output"
+    calls = []
+
+    @cache_skip(track_dependencies=False)
+    def step(i: Path, _output: Path):
+        calls.append(1)
+
+    step(inp, _output=output)
+    (inp / "data.txt").unlink()
+    step(inp, _output=output)
+    assert len(calls) == 2
+
+
+def test_missing_output_kwarg_raises(tmp_path, inp):
+    @cache_skip(track_dependencies=False)
+    def step(i: Path, _output: Path):
+        pass
+
+    with pytest.raises(AssertionError, match="_output"):
+        step(inp)
+
+
+def test_track_dependencies_false_does_not_call_compute_dep_hash(tmp_path, inp):
+    output = tmp_path / "output"
+
+    with patch("cache_skip.deps.compute_dep_hash") as mock_dep:
+
+        @cache_skip(track_dependencies=False)
+        def step(i: Path, _output: Path):
+            pass
+
+        step(inp, _output=output)
+        mock_dep.assert_not_called()
+
+
+def test_both_decorator_forms_work(tmp_path, inp):
+    output1 = tmp_path / "output1"
+    output2 = tmp_path / "output2"
+
+    @cache_skip
+    def step_a(i: Path, _output: Path):
+        pass
+
+    @cache_skip(track_dependencies=False)
+    def step_b(i: Path, _output: Path):
+        pass
+
+    with patch("cache_skip.deps.compute_dep_hash", return_value="x" * 32):
+        step_a(inp, _output=output1)
+    step_b(inp, _output=output2)
+    assert output1.exists()
+    assert output2.exists()
+
+
+def test_non_path_args_change_triggers_rerun(tmp_path, inp):
+    output = tmp_path / "output"
+    calls = []
+
+    @cache_skip(track_dependencies=False)
+    def step(i: Path, schedule_date: date, _output: Path):
+        calls.append(1)
+
+    step(inp, date(2025, 1, 1), _output=output)
+    step(inp, date(2025, 1, 2), _output=output)
+    assert len(calls) == 2
+
+
+def test_optional_path_none_not_in_input_paths(tmp_path, inp):
+    output = tmp_path / "output"
+    calls = []
+
+    @cache_skip(track_dependencies=False)
+    def step(i: Path, extra: Path | None, _output: Path):
+        calls.append(1)
+
+    step(inp, None, _output=output)
+    result = step(inp, None, _output=output)
+    assert len(calls) == 1
+    assert result == output
+
+
+def test_state_dep_hash_empty_when_disabled(tmp_path, inp):
+    output = tmp_path / "output"
+
+    @cache_skip(track_dependencies=False)
+    def step(i: Path, _output: Path):
+        pass
+
+    step(inp, _output=output)
+    state = read_state(output / ".input_state.json")
+    assert state.dep_hash == ""

cache_skip/tests/test_deps.py

@@ -0,0 +1,75 @@
+from pathlib import Path
+
+import pytest
+
+from cache_skip import deps
+
+
+def test_hash_files_returns_hex_string(tmp_path):
+    f = tmp_path / "sample.py"
+    f.write_text("x = 1\n")
+    result = deps._hash_files([f])
+    assert isinstance(result, str)
+    assert len(result) == 32
+
+
+def test_same_files_same_hash(tmp_path):
+    f = tmp_path / "sample.py"
+    f.write_text("x = 1\n")
+    h1 = deps._hash_files([f])
+    h2 = deps._hash_files([f])
+    assert h1 == h2
+
+
+def test_changed_file_different_hash(tmp_path):
+    f = tmp_path / "sample.py"
+    f.write_text("x = 1\n")
+    h1 = deps._hash_files([f])
+    f.write_text("x = 99\n")
+    h2 = deps._hash_files([f])
+    assert h1 != h2
+
+
+def test_compute_dep_hash_returns_hex_string(tmp_path):
+    f = tmp_path / "sample.py"
+    f.write_text("x = 42\n")
+    result = deps.compute_dep_hash(lambda: None, dep_files=[f])
+    assert isinstance(result, str)
+    assert len(result) == 32
+
+
+def test_compute_dep_hash_deterministic(tmp_path):
+    f = tmp_path / "sample.py"
+    f.write_text("x = 42\n")
+    h1 = deps.compute_dep_hash(lambda: None, dep_files=[f])
+    h2 = deps.compute_dep_hash(lambda: None, dep_files=[f])
+    assert h1 == h2
+
+
+def test_compute_dep_hash_changes_with_file(tmp_path):
+    f = tmp_path / "sample.py"
+    f.write_text("x = 42\n")
+    h1 = deps.compute_dep_hash(lambda: None, dep_files=[f])
+    f.write_text("x = 99\n")
+    h2 = deps.compute_dep_hash(lambda: None, dep_files=[f])
+    assert h1 != h2
+
+
+def test_track_dependencies_false_dep_hash_is_empty(tmp_path):
+    from pathlib import Path
+
+    from cache_skip.decorator import cache_skip
+    from cache_skip.state import read_state
+
+    inp = tmp_path / "inp"
+    inp.mkdir()
+    (inp / "data.txt").write_bytes(b"x")
+    output = tmp_path / "output"
+
+    @cache_skip(track_dependencies=False)
+    def step(i: Path, _output: Path):
+        pass
+
+    step(inp, _output=output)
+    state = read_state(output / ".input_state.json")
+    assert state.dep_hash == ""

cache_skip/tests/test_dirmaker.py

@@ -0,0 +1,34 @@
+from pathlib import Path
+
+from cache_skip.dirmaker import Dirmaker
+
+
+def test_new_output_dir_creates_directory(tmp_path):
+    dm = Dirmaker(tmp_path / "root")
+    out = dm.new_output_dir("step1")
+    assert out.exists()
+    assert out.is_dir()
+    assert out == tmp_path / "root" / "step1"
+
+
+def test_new_output_dir_deletes_and_recreates(tmp_path):
+    dm = Dirmaker(tmp_path / "root")
+    out = dm.new_output_dir("step1")
+    (out / "result.txt").write_text("old")
+    out2 = dm.new_output_dir("step1")
+    assert out2 == out
+    assert not (out / "result.txt").exists()
+    assert out.exists()
+
+
+def test_path_for_no_side_effects(tmp_path):
+    dm = Dirmaker(tmp_path / "root")
+    p = dm.path_for("step1")
+    assert p == tmp_path / "root" / "step1"
+    assert not p.exists()
+
+
+def test_dirmaker_creates_root_on_init(tmp_path):
+    root = tmp_path / "deep" / "root"
+    dm = Dirmaker(root)
+    assert root.exists()

cache_skip/tests/test_scanner.py

@@ -0,0 +1,57 @@
+import os
+from pathlib import Path
+
+import pytest
+import xxhash
+
+from cache_skip.scanner import scan_inputs
+
+
+def test_single_file(tmp_path):
+    f = tmp_path / "data.txt"
+    f.write_bytes(b"hello world")
+    state = scan_inputs([f])
+    assert len(state.files) == 1
+    key = str(f.resolve())
+    rec = state.files[key]
+    stat = os.stat(f)
+    assert rec.size == 11
+    assert rec.inode == stat.st_ino
+    assert rec.mtime == pytest.approx(stat.st_mtime_ns / 1e9)
+    assert rec.hash == xxhash.xxh128(b"hello world").hexdigest()
+    assert state.args_hash == ""
+    assert state.dep_hash == ""
+
+
+def test_directory(tmp_path):
+    sub = tmp_path / "sub"
+    sub.mkdir()
+    (sub / "a.txt").write_bytes(b"a")
+    (sub / "b.txt").write_bytes(b"b")
+    state = scan_inputs([sub])
+    assert len(state.files) == 2
+    for key in state.files:
+        assert Path(key).is_absolute()
+
+
+def test_nonexistent(tmp_path):
+    missing = tmp_path / "does_not_exist"
+    with pytest.raises(AssertionError, match="does not exist"):
+        scan_inputs([missing])
+
+
+def test_empty_directory(tmp_path):
+    empty = tmp_path / "empty"
+    empty.mkdir()
+    state = scan_inputs([empty])
+    assert state.files == {}
+
+
+def test_skips_input_state_json(tmp_path):
+    d = tmp_path / "dir"
+    d.mkdir()
+    (d / "data.txt").write_bytes(b"x")
+    (d / ".input_state.json").write_bytes(b"{}")
+    state = scan_inputs([d])
+    assert len(state.files) == 1
+    assert all(".input_state.json" not in k for k in state.files)

cache_skip/tests/test_state.py

@@ -0,0 +1,39 @@
+import json
+from pathlib import Path
+
+import pytest
+
+from cache_skip.state import FileRecord, InputState, read_state, write_state
+
+
+def _make_state() -> InputState:
+    return InputState(
+        version=1,
+        files={
+            "/tmp/foo.txt": FileRecord(
+                path="/tmp/foo.txt",
+                mtime=1716000000.123,
+                inode=98765,
+                size=4096,
+                hash="abcdef1234567890abcdef1234567890",
+            )
+        },
+        args_hash="aabbccdd11223344aabbccdd11223344",
+        dep_hash="eeff00112233445566778899aabbccdd",
+    )
+
+
+def test_round_trip(tmp_path):
+    state = _make_state()
+    path = tmp_path / "state.json"
+    write_state(state, path)
+    loaded = read_state(path)
+    assert loaded == state
+
+
+def test_version_mismatch(tmp_path):
+    path = tmp_path / "state.json"
+    data = {"version": 99, "files": {}, "args_hash": "", "dep_hash": ""}
+    path.write_text(json.dumps(data))
+    with pytest.raises(AssertionError):
+        read_state(path)

pycache_skip-0.1.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: pycache_skip
+Version: 0.1.0
+Summary: Skip pipeline steps when inputs are unchanged — content-aware, with module dependency tracking
+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
+Requires-Dist: xxhash
+Description-Content-Type: text/markdown
+
+# pycache_skip
+
+Skip pipeline steps when their inputs have not changed.
+
+```bash
+uv add pycache_skip
+```
+
+## What it does
+
+`cache_skip` wraps a pipeline step function and skips re-execution when all
+inputs are unchanged. It stores a compact state file (`.input_state.json`)
+alongside each output directory. On subsequent calls it compares the current
+inputs against the stored state and only reruns the function when something
+actually changed.
+
+## Usage
+
+### Basic example (single input directory)
+
+```python
+from pathlib import Path
+from cache_skip import cache_skip, Dirmaker
+
+dm = Dirmaker(Path("/data/pipeline/run-001"))
+
+@cache_skip
+def step_transform(raw: Path, *, _output: Path) -> Path:
+    # heavy transformation ...
+    return _output
+
+# First call — runs the function and records input state.
+step_transform(Path("/data/raw"), _output=dm.path_for("transform"))
+
+# Second call — skips the function, returns the output path immediately.
+step_transform(Path("/data/raw"), _output=dm.path_for("transform"))
+```
+
+### Example with non-Path args
+
+Non-`Path` arguments (dates, strings, ints, etc.) are also part of the cache
+key. Changing them triggers a rerun.
+
+```python
+import datetime as dt
+
+@cache_skip(track_dependencies=False)
+def step_build_config(
+    schedule_date: dt.date,
+    template: Path,
+    *,
+    _output: Path,
+) -> Path:
+    ...
+
+# Changing schedule_date from 2025-01-01 to 2025-01-02 invalidates the cache.
+```
+
+### Dirmaker companion
+
+`Dirmaker` allocates named output directories under a staging root. Use
+`path_for(name)` to resolve the path without side effects (for `@cache_skip`),
+or `new_output_dir(name)` to delete and recreate explicitly.
+
+```python
+dm = Dirmaker(Path("/data/pipeline/run-001"))
+
+# Pass path to decorator — decorator manages deletion on rerun.
+step_transform(raw, _output=dm.path_for("transform"))
+
+# Or manage the directory yourself:
+out = dm.new_output_dir("transform")   # deletes existing, creates fresh
+```
+
+## How invalidation works
+
+Three-tier change detection on every call after the first:
+
+1. **Args hash** — all non-`Path`, non-`_output` arguments are hashed via
+   `repr()`. A change in any scalar argument (date, string, int, …) triggers
+   a rerun immediately.
+
+2. **Dependency hash** — the source files of the decorated function and all
+   modules it imports (static AST analysis) are hashed. Editing the function's
+   source code triggers a rerun. Disable with `track_dependencies=False`.
+
+3. **File content hash** — every file under each input `Path` is compared.
+   Metadata (mtime, inode, size) is checked first as a fast path. If metadata
+   is identical the stored hash is trusted. If metadata drifted but content
+   hash matches, the state file is updated silently without a rerun (handles
+   `rsync` / `cp -p` copies with timestamp noise).
+
+## track_dependencies
+
+```python
+@cache_skip(track_dependencies=False)
+def step(...):
+    ...
+```
+
+Set `track_dependencies=False` to skip module source hashing. Useful when the
+function imports large, rarely-changing libraries and startup cost matters, or
+in tests.
+
+## Comparison with auto_skip
+
+`cache_skip` is a simpler, self-contained alternative to `auto_skip`:
+
+| Feature             | `cache_skip`                 | `auto_skip`          |
+| ------------------- | ---------------------------- | -------------------- |
+| Input detection     | explicit `Path` args         | strace / audit hooks |
+| Non-Path args       | hashed                       | ignored              |
+| Module dep tracking | static AST                   | runtime import list  |
+| External deps       | `xxhash`, `loguru`           | heavier stack        |
+| Output format       | dir with `.input_state.json` | opaque cache store   |

pycache_skip-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+cache_skip/__init__.py,sha256=ys0DCGkYl4ePzT-uM9RPM_iStHKuUj8npAHRNjKf2jQ,123
+cache_skip/decorator.py,sha256=F6O2RfpRtngQCjB9hsM9ZXB59dlTYl--HMz3VVYtSpo,6207
+cache_skip/deps.py,sha256=jAQpBKPMfjbLHPuWbWYaOd2TRBvsG03PhdJD-NYGXEw,4710
+cache_skip/dirmaker.py,sha256=QnHhOqPs4yOkN3LL-IdpsKrJBAWzQg0gXGBTzrA5fpI,1043
+cache_skip/scanner.py,sha256=9_8y6C5Cmme5_xLJEWS6cKE8NZM8bkZlnI6euPocEoA,1090
+cache_skip/state.py,sha256=pM6T1kVDCrz9Jcojlq1QnFb5bRPyt8LhWA19qOa3uKI,800
+cache_skip/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cache_skip/tests/test_decorator.py,sha256=uNXBpGtapKMsP2Od2Y837svxPP8sdnbB_XG6t7yMEBQ,5674
+cache_skip/tests/test_deps.py,sha256=M5Vf360reYb_bUGQ3NhSRWhXpHtdpMzPnIdJ58svbno,1983
+cache_skip/tests/test_dirmaker.py,sha256=RXB2YXvWnGG54vhGK-P-bT3OJytEswbVe7CiqRtkQd4,918
+cache_skip/tests/test_scanner.py,sha256=VZR8diOCKjJob2jvx-he_7qXM-XMoWaS9IXLqFURO78,1500
+cache_skip/tests/test_state.py,sha256=8Q7lBorHWbxrHW6av1wls9updfqwrhHv9geWcEBih4w,1019
+pycache_skip-0.1.0.dist-info/METADATA,sha256=gvIHtDPlUE2YKncTV6TAFflgdQHsnhMK2tzIMW6L2rc,4280
+pycache_skip-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pycache_skip-0.1.0.dist-info/licenses/LICENSE,sha256=yiKnYC3HrKFysIItc-FrkG5MPsK8qOP1tc2283dEG1k,1080
+pycache_skip-0.1.0.dist-info/RECORD,,

pycache_skip-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pycache_skip-0.1.0.dist-info/licenses/LICENSE

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