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
View source
1 Class

Classes

FileFingerprint dataclass
Fast file change detection using mtime + size, with optional hash verification. Performance Optimi…
4

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

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) Thread Safety: Immutable after creation. Thread-safe for read operations.

Methods 4

matches_stat
Fast path check: does mtime + size match?
1 bool 
def matches_stat(self, stat_result: os.stat_result) -> bool

Fast path check: does mtime + size match?

Parameters 1
stat_result os.stat_result

Result from Path.stat()
Returns

bool —

True if mtime and size both match (definitely unchanged)

to_dict
Serialize to JSON-compatible dict.
0 dict[str, Any] 
def to_dict(self) -> dict[str, Any]

Serialize to JSON-compatible dict.

Returns

dict[str, Any]

from_dict classmethod
Deserialize from JSON dict.
1 FileFingerprint 
def from_dict(cls, data: dict[str, Any]) -> FileFingerprint

Deserialize from JSON dict.

Parameters 1
data dict[str, Any]
Returns

FileFingerprint

from_path classmethod
Create fingerprint from file path.
2 FileFingerprint 
def from_path(cls, file_path: Path, compute_hash: bool = True) -> FileFingerprint

Create fingerprint from file path.

Parameters 2
file_path Path

Path to file
compute_hash bool

Whether to compute SHA256 hash (slower but more reliable)
Returns

FileFingerprint —

FileFingerprint with mtime, size, and optionally hash