Skip to content

stat_cache

stat_cache #

What identifies a file without reading it, and remembering its hash for as long as that holds.

Learned = tuple[Path, Stat, ContentHash] #

A file's path, its stat when hashed, and the hash.

Batch #

A hash cache that holds what a walk learns until flush, remembering it in one write.

Source code in capturegraph-lib/capturegraph/scratch/hashing/stat_cache.py
class Batch:
    """A hash cache that holds what a walk learns until ``flush``, remembering it in one write."""

    def __init__(self, cache: HashCache) -> None:
        """Batch the writes to ``cache``."""
        self._cache = cache
        self._learned: dict[Path, tuple[Stat, ContentHash]] = {}

    def lookup(self, path: Path, stat: Stat) -> ContentHash | None:
        """The hash of ``path`` at ``stat`` this walk learned, else ``cache``'s."""
        learned = self._learned.get(path)
        if learned is not None and learned[0] == stat:
            return learned[1]
        return self._cache.lookup(path, stat)

    def store_all(self, learned: list[Learned]) -> None:
        """Hold each ``(path, stat, hash)`` until ``flush``."""
        for path, stat, hash in learned:
            self._learned[path] = (stat, hash)

    def flush(self) -> None:
        """Hand everything held to ``cache`` in one ``store_all``."""
        if self._learned:
            self._cache.store_all([(path, *entry) for path, entry in self._learned.items()])
            self._learned.clear()

__init__(cache) #

Batch the writes to cache.

Source code in capturegraph-lib/capturegraph/scratch/hashing/stat_cache.py
def __init__(self, cache: HashCache) -> None:
    """Batch the writes to ``cache``."""
    self._cache = cache
    self._learned: dict[Path, tuple[Stat, ContentHash]] = {}

flush() #

Hand everything held to cache in one store_all.

Source code in capturegraph-lib/capturegraph/scratch/hashing/stat_cache.py
def flush(self) -> None:
    """Hand everything held to ``cache`` in one ``store_all``."""
    if self._learned:
        self._cache.store_all([(path, *entry) for path, entry in self._learned.items()])
        self._learned.clear()

lookup(path, stat) #

The hash of path at stat this walk learned, else cache's.

Source code in capturegraph-lib/capturegraph/scratch/hashing/stat_cache.py
def lookup(self, path: Path, stat: Stat) -> ContentHash | None:
    """The hash of ``path`` at ``stat`` this walk learned, else ``cache``'s."""
    learned = self._learned.get(path)
    if learned is not None and learned[0] == stat:
        return learned[1]
    return self._cache.lookup(path, stat)

store_all(learned) #

Hold each (path, stat, hash) until flush.

Source code in capturegraph-lib/capturegraph/scratch/hashing/stat_cache.py
def store_all(self, learned: list[Learned]) -> None:
    """Hold each ``(path, stat, hash)`` until ``flush``."""
    for path, stat, hash in learned:
        self._learned[path] = (stat, hash)

HashCache #

Bases: Protocol

Remembers a file's hash for as long as its Stat is unchanged.

Source code in capturegraph-lib/capturegraph/scratch/hashing/stat_cache.py
class HashCache(Protocol):
    """Remembers a file's hash for as long as its ``Stat`` is unchanged."""

    def lookup(self, path: Path, stat: Stat) -> ContentHash | None:
        """The remembered hash of ``path`` at ``stat``, if any."""
        ...

    def store_all(self, learned: list[Learned]) -> None:
        """Remember each ``(path, stat, hash)``: ``path`` at ``stat`` hashes to ``hash``."""
        ...

lookup(path, stat) #

The remembered hash of path at stat, if any.

Source code in capturegraph-lib/capturegraph/scratch/hashing/stat_cache.py
def lookup(self, path: Path, stat: Stat) -> ContentHash | None:
    """The remembered hash of ``path`` at ``stat``, if any."""
    ...

store_all(learned) #

Remember each (path, stat, hash): path at stat hashes to hash.

Source code in capturegraph-lib/capturegraph/scratch/hashing/stat_cache.py
def store_all(self, learned: list[Learned]) -> None:
    """Remember each ``(path, stat, hash)``: ``path`` at ``stat`` hashes to ``hash``."""
    ...

NoCache #

A hash cache that remembers nothing.

Source code in capturegraph-lib/capturegraph/scratch/hashing/stat_cache.py
class NoCache:
    """A hash cache that remembers nothing."""

    def lookup(self, path: Path, stat: Stat) -> ContentHash | None:
        """Always a miss."""
        return None

    def store_all(self, learned: list[Learned]) -> None:
        """Forgets immediately."""

lookup(path, stat) #

Always a miss.

Source code in capturegraph-lib/capturegraph/scratch/hashing/stat_cache.py
def lookup(self, path: Path, stat: Stat) -> ContentHash | None:
    """Always a miss."""
    return None

store_all(learned) #

Forgets immediately.

Source code in capturegraph-lib/capturegraph/scratch/hashing/stat_cache.py
def store_all(self, learned: list[Learned]) -> None:
    """Forgets immediately."""

Stat dataclass #

A file's identity on disk: change any of these and its content may have changed.

Source code in capturegraph-lib/capturegraph/scratch/hashing/stat_cache.py
@dataclass(frozen=True, slots=True)
class Stat:
    """A file's identity on disk: change any of these and its content may have changed."""

    mtime_ns: int
    size: int
    inode: int
    is_dir: bool

    @classmethod
    def of(cls, path: Path) -> Stat:
        """The stat of ``path`` itself (a symlink is not followed)."""
        status = os.lstat(path)
        return cls(status.st_mtime_ns, status.st_size, status.st_ino, os.path.isdir(path))

of(path) classmethod #

The stat of path itself (a symlink is not followed).

Source code in capturegraph-lib/capturegraph/scratch/hashing/stat_cache.py
@classmethod
def of(cls, path: Path) -> Stat:
    """The stat of ``path`` itself (a symlink is not followed)."""
    status = os.lstat(path)
    return cls(status.st_mtime_ns, status.st_size, status.st_ino, os.path.isdir(path))