Struct Cache 

pub struct Cache { /* private fields */ }

The main cache abstraction.

While the cache is active, it holds a read (shared) lock that prevents cache cleaning

Implementations

impl Cache

pub fn from_path(root: impl Into<PathBuf>) -> Self

A persistent cache directory at root.

pub fn temp() -> Result<Self, Error>

Create a temporary cache directory.

pub fn with_refresh(self, refresh: Refresh) -> Self

Set the Refresh policy for the cache.

pub fn with_removal_accounting( self, removal_accounting: RemovalAccounting, ) -> Self

Set the storage accounting used when removing cache entries.

Falls back to RemovalAccounting::Coarse when fine-grained accounting is unsupported.

pub fn removal(&self) -> Removal

Create an empty removal summary using the cache’s configured accounting.

pub async fn with_exclusive_lock(self) -> Result<Self, LockedFileError>

Acquire a lock that allows removing entries from the cache.

pub fn with_exclusive_lock_no_wait(self) -> Result<Self, Self>

Acquire a lock that allows removing entries from the cache, if available.

If the lock is not immediately available, returns Err with self.

pub fn root(&self) -> &Path

Return the root of the cache.

pub fn bucket(&self, cache_bucket: CacheBucket) -> PathBuf

The folder for a specific cache bucket

pub fn shard( &self, cache_bucket: CacheBucket, dir: impl AsRef<Path>, ) -> CacheShard

Compute an entry in the cache.

pub fn entry( &self, cache_bucket: CacheBucket, dir: impl AsRef<Path>, file: impl AsRef<Path>, ) -> CacheEntry

Compute an entry in the cache.

pub fn archive(&self, id: &ArchiveId) -> PathBuf

Return the path to an archive in the cache.

pub fn archive_file(&self, id: &ArchiveFileId) -> PathBuf

Return the path to an archive file in the cache.

pub fn venv_dir(&self) -> Result<TempDir>

Create a temporary directory to be used as a Python virtual environment.

pub fn build_dir(&self) -> Result<TempDir>

Create a temporary directory to be used for executing PEP 517 source distribution builds.

pub fn must_revalidate_package(&self, package: &PackageName) -> bool

Returns true if a cache entry must be revalidated given the Refresh policy.

pub fn must_revalidate_path(&self, path: &Path) -> bool

Returns true if a cache entry must be revalidated given the Refresh policy.

pub fn freshness( &self, entry: &CacheEntry, package: Option<&PackageName>, path: Option<&Path>, ) -> Result<Freshness>

Returns the Freshness for a cache entry, validating it against the Refresh policy.

A cache entry is considered fresh if it was created after the cache itself was initialized, or if the Refresh policy does not require revalidation.

pub async fn persist( &self, temp_dir: impl AsRef<Path>, path: impl AsRef<Path>, ) -> Result<ArchiveId>

Persist a temporary directory to the artifact store, returning its unique ID.

pub async fn persist_with_id( &self, temp_dir: TempDir, path: impl AsRef<Path>, id: ArchiveId, ) -> Result<ArchiveId>

Persist a temporary directory to the artifact store under a caller-selected ID.

If another writer has already persisted the same ID, discard temp_dir and link path to the existing archive entry. The ID must therefore uniquely identify the directory contents.

pub fn is_temporary(&self) -> bool

Returns true if the Cache is temporary.

pub async fn init(self) -> Result<Self, Error>

Initialize the Cache.

pub fn init_no_wait(self) -> Result<Option<Self>, Error>

Initialize the Cache, assuming that there are no other uv processes running.

pub fn clear(self, reporter: Box<dyn CleanReporter>) -> Result<Removal, Error>

Clear the cache, removing all entries.

pub fn remove(&self, name: &PackageName) -> Result<Removal>

Remove a package from the cache.

Unreferenced file objects are removed separately by Cache::prune_archive_files.

Returns the number of entries removed from the cache.

pub fn prune_archive_files(&self) -> Result<Removal, Error>

Remove file objects with no hardlinks outside the files bucket.

Archives refer to these objects via hardlinks, independently of the installation link mode. Installed copies and reflinks remain valid when the cached file is removed, so they do not need to keep the file object alive.

pub fn prune(&self, ci: bool) -> Result<Removal, Error>

Prune dangling cache entries and cached environments.

pub fn remove_path(&self, path: impl AsRef<Path>) -> Result<Removal>

Remove a cache path using the cache’s configured storage accounting.

pub fn resolve_link(&self, path: impl AsRef<Path>) -> Result<PathBuf>

Resolve an archive link, returning the fully-resolved path.

Returns an error if the link target does not exist.

Trait Implementations

impl Clone for Cache

fn clone(&self) -> Cache

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Cache

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.