Skip to content

salvus.flow.acta.store.stat_cache

salvus.flow.acta.store.stat_cache salvus flow acta store stat_cache

File digests cached by path and filesystem metadata.

Reuse digests when size, timestamps, and inode match. Shared caches require consistent paths and metadata across hosts; host and device IDs are not part of the key. Backend failures warn once and fall back to hashing.

Files with timestamps less than one second old are always rehashed and do not seed the cache. Hashing checks metadata before and after reading. Metadata reuse still assumes the filesystem reports changes reliably and the caller keeps input files stable during a run; it cannot detect writes that restore all metadata or happen within an older timestamp collision.

Functions

default_stat_cache()

def default_stat_cache(
    on_hash: Callable[[str, str], None] | None = None,
) -> StatCacheBase: ...

Build the stat cache a session uses when none was passed.

Use ACTA_STAT_CACHE_URL when set, otherwise the Salvus user data directory. Shared caches require consistent input paths and metadata across hosts.

Parameters
  • on_hash Callable[[str, str], None] | None = None — Forwarded to the backend (see StatCacheBase).
Returns StatCacheBase

resolve_stat_cache_url()

def resolve_stat_cache_url() -> str | None: ...

Resolve the stat cache URL from the environment.

Returns str | None — ACTA_STAT_CACHE_URL when set; an empty string disables caching. None when unset, indicating the default location.

stat_cache_from_url()

def stat_cache_from_url(
    url: str | None, on_hash: Callable[[str, str], None] | None = None
) -> StatCacheBase: ...

Construct a stat cache backend from a URL.

Parameters
  • url str | None — sqlite:///abs/path/to/stat-cache.sqlite for the shared on-disk cache, memory:// for a process-local one, or null:// (equivalently None or an empty string) for no cache at all.
  • on_hash Callable[[str, str], None] | None = None — Forwarded to the backend (see StatCacheBase).
Returns StatCacheBase — A StatCacheBase instance for the requested scheme.

Classes

InMemoryStatCache

class InMemoryStatCache(salvus.flow.acta.store.stat_cache.StatCacheBase):
    def __init__(
        self, on_hash: Callable[[str, str], None] | None = None
    ) -> None: ...

In-memory file-digest cache.

Parameters
  • on_hash Callable[[str, str], None] | None = None — See StatCacheBase.
Attributes
degraded bool

Return whether the backend has been disabled for this run.

Methods
close()
def close(self) -> None: ...

Release backend resources, if any.

Returns None
digest()
def digest(self, path: pathlib.Path | str) -> str: ...

Return the content digest of the file at path.

Reuse a digest on a settled stat match; otherwise hash the file and check its metadata again. Recent files do not seed the cache. Invalid paths raise FileIdentityError; cache failures fall back to hashing.

Parameters
  • path pathlib.Path | str — The file to identify. Made absolute but not resolved (see StatKey).
Returns str — The 64-character lowercase hex digest of the file’s bytes.

NullStatCache

class NullStatCache(salvus.flow.acta.store.stat_cache.StatCacheBase):
    def __init__(
        self, on_hash: Callable[[str, str], None] | None = None
    ) -> None: ...

File-digest cache that always rehashes.

Used for Session(stat_cache=False) or an empty ACTA_STAT_CACHE_URL.

Parameters
  • on_hash Callable[[str, str], None] | None = None — See StatCacheBase.
Attributes
degraded bool

Return whether the backend has been disabled for this run.

Methods
close()
def close(self) -> None: ...

Release backend resources, if any.

Returns None
digest()
def digest(self, path: pathlib.Path | str) -> str: ...

Return the content digest of the file at path.

Reuse a digest on a settled stat match; otherwise hash the file and check its metadata again. Recent files do not seed the cache. Invalid paths raise FileIdentityError; cache failures fall back to hashing.

Parameters
  • path pathlib.Path | str — The file to identify. Made absolute but not resolved (see StatKey).
Returns str — The 64-character lowercase hex digest of the file’s bytes.

SqliteStatCache

class SqliteStatCache(salvus.flow.acta.store.stat_cache.StatCacheBase):
    def __init__(
        self,
        db_path: pathlib.Path | str,
        on_hash: Callable[[str, str], None] | None = None,
        busy_timeout_ms: int = 30000,
    ) -> None: ...

SQLite file-digest cache for local or shared filesystems.

Open connections lazily. Request WAL mode when available; failures fall back to hashing.

Call close() to release the current connection; later use opens a new one. Abandoned caches also close their connections automatically.

Parameters
  • db_path pathlib.Path | str — Path to the SQLite file. Created along with its parent directory on first use.
  • on_hash Callable[[str, str], None] | None = None — See StatCacheBase.
  • busy_timeout_ms int = 30000 — How long SQLite waits on a locked database before giving up (and, here, degrading).
Attributes
degraded bool

Return whether the backend has been disabled for this run.

Methods
close()
def close(self) -> None: ...

Close the SQLite connection, if one is open.

Returns None
digest()
def digest(self, path: pathlib.Path | str) -> str: ...

Return the content digest of the file at path.

Reuse a digest on a settled stat match; otherwise hash the file and check its metadata again. Recent files do not seed the cache. Invalid paths raise FileIdentityError; cache failures fall back to hashing.

Parameters
  • path pathlib.Path | str — The file to identify. Made absolute but not resolved (see StatKey).
Returns str — The 64-character lowercase hex digest of the file’s bytes.

StatCacheBase

class StatCacheBase(abc.ABC):
    def __init__(
        self, on_hash: Callable[[str, str], None] | None = None
    ) -> None: ...

Cache file digests using filesystem metadata.

Subclasses implement _get and _put. Backend failures disable caching and fall back to hashing.

Parameters
  • on_hash Callable[[str, str], None] | None = None — Optional (digest, path) callback after hashing a file. Not called on cache hits.
Attributes
degraded bool

Return whether the backend has been disabled for this run.

Methods
close()
def close(self) -> None: ...

Release backend resources, if any.

Returns None
digest()
def digest(self, path: pathlib.Path | str) -> str: ...

Return the content digest of the file at path.

Reuse a digest on a settled stat match; otherwise hash the file and check its metadata again. Recent files do not seed the cache. Invalid paths raise FileIdentityError; cache failures fall back to hashing.

Parameters
  • path pathlib.Path | str — The file to identify. Made absolute but not resolved (see StatKey).
Returns str — The 64-character lowercase hex digest of the file’s bytes.

StatKey

class StatKey(builtins.object):
    def __init__(
        self, path: str, size: int, mtime_ns: int, ctime_ns: int, inode: int
    ) -> None: ...

Path and filesystem metadata identifying a cached file digest.

Parameters
  • path str — Absolute path, without resolving symlinks.
  • size int — File size in bytes (st_size).
  • mtime_ns int — Modification time in nanoseconds (st_mtime_ns).
  • ctime_ns int — Metadata change time in nanoseconds (native ChangeTime on Windows, st_ctime_ns elsewhere).
  • inode int — File inode (st_ino).

Exceptions

FileIdentityError

Raised when a file is inaccessible, invalid, or has changed contents.