Padrão de Cache de Arquivo por Hash de Conteúdo

Armazene em cache os resultados de processamento de arquivos caros (análise de PDF, extração de texto, análise de imagem) usando hashes de conteúdo SHA-256 como chaves de cache. Diferente do cache baseado em caminho, essa abordagem sobrevive a movimentações/renomeações de arquivos e invalida automaticamente quando o conteúdo muda.

Quando Ativar

• Construindo pipelines de processamento de arquivos (PDF, imagens, extração de texto)
• O custo de processamento é alto e os mesmos arquivos são processados repetidamente
• Precisa de uma opção de linha de comando --cache/--no-cache
• Quer adicionar cache a funções puras existentes sem modificá-las

Padrão Central

1. Chave de Cache Baseada em Hash de Conteúdo

Use o conteúdo do arquivo (não o caminho) como chave de cache:

import hashlib
from 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()

Por que hash de conteúdo? Renomear/mover arquivo = cache hit. Mudança de conteúdo = invalidação automática. Nenhum arquivo de índice necessário.

2. Dataclass Congelada para Entrada de Cache

from dataclasses import dataclass

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

3. Armazenamento de Cache Baseado em Arquivo

Cada entrada de cache é armazenada como {hash}.json — busca O(1) por hash, nenhum arquivo de índice é necessário.

import json
from 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

4. Wrapper de Camada de Serviço (SRP)

Mantenha a função de processamento pura. Adicione o cache como uma camada de serviço separada.

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

Principais Decisões de Design

Melhores Práticas

• Hasheie o conteúdo, não os caminhos — caminhos mudam, identidade do conteúdo não
• Divida arquivos grandes em pedaços ao hashear — evite carregar arquivos inteiros na memória
• Mantenha as funções de processamento puras — elas não devem saber nada sobre cache
• Registre cache hit/miss com hashes truncados para depuração
• Lide com corrupção graciosamente — trate entradas de cache inválidas como misses, nunca trave

Antí-Padrões a Evitar

# RUIM: Cache baseado em caminho (quebra em movimentação/renomeação de arquivo)
cache = {"/path/to/file.pdf": result}


…