Content Hash Cache Pattern

import hashlibfrom pathlib import Path
_HASH_CHUNK_SIZE = 65536  # 64KB chunks for large files
def compute_file_hash(path: Path) -> str:    """SHA-256 of file contents (chunked for large files)."""    if not path.is_file():        raise FileNotFoundError(f"File not found: {path}")    sha256 = hashlib.sha256()    with open(path, "rb") as f:        while True:            chunk = f.read(_HASH_CHUNK_SIZE)            if not chunk:                break            sha256.update(chunk)    return sha256.hexdigest()

from dataclasses import dataclass
@dataclass(frozen=True, slots=True)class CacheEntry:    file_hash: str    source_path: str    document: ExtractedDocument  # The cached result

import jsonfrom typing import Any
def write_cache(cache_dir: Path, entry: CacheEntry) -> None:    cache_dir.mkdir(parents=True, exist_ok=True)    cache_file = cache_dir / f"{entry.file_hash}.json"    data = serialize_entry(entry)    cache_file.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
def read_cache(cache_dir: Path, file_hash: str) -> CacheEntry | None:    cache_file = cache_dir / f"{file_hash}.json"    if not cache_file.is_file():        return None    try:        raw = cache_file.read_text(encoding="utf-8")        data = json.loads(raw)        return deserialize_entry(data)    except (json.JSONDecodeError, ValueError, KeyError):        return None  # Treat corruption as cache miss

def extract_with_cache(    file_path: Path,    *,    cache_enabled: bool = True,    cache_dir: Path = Path(".cache"),) -> ExtractedDocument:    """Service layer: cache check -> extraction -> cache write."""    if not cache_enabled:        return extract_text(file_path)  # Pure function, no cache knowledge
    file_hash = compute_file_hash(file_path)
    # Check cache    cached = read_cache(cache_dir, file_hash)    if cached is not None:        logger.info("Cache hit: %s (hash=%s)", file_path.name, file_hash[:12])        return cached.document
    # Cache miss -> extract -> store    logger.info("Cache miss: %s (hash=%s)", file_path.name, file_hash[:12])    doc = extract_text(file_path)    entry = CacheEntry(file_hash=file_hash, source_path=str(file_path), document=doc)    write_cache(cache_dir, entry)    return doc

# BAD: Path-based caching (breaks on file move/rename)cache = {"/path/to/file.pdf": result}
# BAD: Adding cache logic inside the processing function (SRP violation)def extract_text(path, *, cache_enabled=False, cache_dir=None):    if cache_enabled:  # Now this function has two responsibilities        ...
# BAD: Using dataclasses.asdict() with nested frozen dataclasses# (can cause issues with complex nested types)data = dataclasses.asdict(entry)  # Use manual serialization instead