hubvault.remote.cache

Cache-layout helpers for hubvault.remote.

This module computes stable cache locations for remote downloads and snapshots. The cache remains a client-local convenience layer rather than repository truth.

The module contains:

RemoteCacheLayout

class hubvault.remote.cache.RemoteCacheLayout(download_root: str, snapshot_root: str)[source]

Describe the cache roots reserved for remote client artifacts.

Parameters:

  • download_root (str) – Root directory for downloaded individual files

  • snapshot_root (str) – Root directory for snapshot-style downloads

get_remote_cache_layout

hubvault.remote.cache.get_remote_cache_layout(cache_dir: str | PathLike | None = None) → RemoteCacheLayout[source]

Resolve the cache roots for one remote client.

Parameters:

cache_dir (Optional[Union[str, os.PathLike]]) – Optional explicit cache root override

Returns:

Cache-root layout for downloads and snapshots

Return type:

RemoteCacheLayout

build_download_target

hubvault.remote.cache.build_download_target(layout: RemoteCacheLayout, *, base_url: str, path_in_repo: str, etag: str | None, revision: str | None = None, local_dir: str | PathLike | None = None) → Path[source]

Build the target path for one remote file download.

Parameters:

  • layout (RemoteCacheLayout) – Cache layout for the current client

  • base_url (str) – Remote base URL

  • path_in_repo (str) – Repo-relative file path

  • etag (Optional[str]) – Download identity used for cache reuse

  • revision (Optional[str]) – Optional selected revision string

  • local_dir (Optional[Union[str, os.PathLike]]) – Optional explicit export directory

Returns:

Filesystem path where the file should be materialized

Return type:

pathlib.Path

build_snapshot_target

hubvault.remote.cache.build_snapshot_target(layout: RemoteCacheLayout, *, base_url: str, snapshot_id: str, local_dir: str | PathLike | None = None) → Path[source]

Build the target directory for one remote snapshot download.

Parameters:

  • layout (RemoteCacheLayout) – Cache layout for the current client

  • base_url (str) – Remote base URL

  • snapshot_id (str) – Stable snapshot identity, typically a commit OID

  • local_dir (Optional[Union[str, os.PathLike]]) – Optional explicit export directory

Returns:

Filesystem path where the snapshot should be materialized

Return type:

pathlib.Path

snapshot_is_complete

hubvault.remote.cache.snapshot_is_complete(target_dir: Path, repo_paths: Iterable[str]) → bool[source]

Return whether a snapshot directory already contains all requested files.

Parameters:

  • target_dir (pathlib.Path) – Candidate snapshot root

  • repo_paths (Iterable[str]) – Repo-relative file paths expected in the snapshot

Returns:

Whether every requested file exists under target_dir

Return type:

bool