Module

cache.build_cache.fingerprint

File fingerprint for fast change detection.

Provides FileFingerprint dataclass for tracking file changes via mtime + size with optional hash verification. Part of the build cache system.

Key Concepts:

  • Fast path: mtime + size comparison (single stat call, no file read)
  • Slow path: SHA256 hash only when mtime/size mismatch detected
  • Handles edge cases: touch/rsync may change mtime but not content

Related Modules:

  • bengal.cache.build_cache: Main BuildCache using FileFingerprint
  • bengal.orchestration.incremental: Incremental build logic

See Also:

  • plan/active/rfc-orchestrator-performance-improvements.md: Performance RFC
1Class

Classes

FileFingerprint 7 ▼
Fast file change detection using mtime + size, with optional hash verification. **Performance Opti…

Fast file change detection using mtime + size, with optional hash verification.

Performance Optimization:

  • mtime + size comparison is O(1) stat call (no file read)
  • Hash computed lazily only when mtime/size mismatch detected
  • Handles edge cases like touch/rsync that change mtime but not content

Thread Safety: Immutable after creation. Thread-safe for read operations.

Attributes

Name Type Description
mtime float

File modification time (seconds since epoch)
size int

File size in bytes
hash str | None

SHA256 hash (computed lazily, may be None for fast path)

Methods

matches_stat 1 bool ▼
Fast path check: does mtime + size match?
def matches_stat(self, stat_result: os.stat_result) -> bool
Parameters
Name Type Description
stat_result —

Result from Path.stat()
Returns
bool True if mtime and size both match (definitely unchanged)
to_dict 0 dict[str, Any] ▼
Serialize to JSON-compatible dict.
def to_dict(self) -> dict[str, Any]
Returns
dict[str, Any]
from_dict 1 FileFingerprint ▼
Deserialize from JSON dict.
classmethod
def from_dict(cls, data: dict[str, Any]) -> FileFingerprint
Parameters
Name Type Description
data —
Returns
FileFingerprint
from_path 2 FileFingerprint ▼
Create fingerprint from file path.
classmethod
def from_path(cls, file_path: Path, compute_hash: bool = True) -> FileFingerprint
Parameters
Name Type Description
file_path —

Path to file
compute_hash —

Whether to compute SHA256 hash (slower but more reliable)

Default:True
Returns
FileFingerprint FileFingerprint with mtime, size, and optionally hash