DirCache

class file_caching.dir_cache.DirCache(server_root_path: str, target_subdir: str | None = None, cache_root_path: str | None = None, expand_path_fct: ~typing.Callable[[str], str] = <function expandvars>, enable_no_root_access_warnings: bool = True)

Bases: object

Caches all access to a user-defined server root path or its sub-folders.

DEFAULT_CACHE_ROOT_ID = '__DIRCACHE__'

Used as root folder name for the cache directory.

exception NoSourceAccessWarning

Bases: UserWarning

add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception RootPathMustBeAbsoluteError(server_root_path)

Bases: ValueError

add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

get(source_path: str = '.', prune_target_folder=True) → str

Used to access content (file or directory) at the cache’s source path, cached or not.

If source_path is a sub-path of the caches’ server_root_path, it will first check if it has access to server_root_path. If so, it will sync the cache for source_path, and return the cached path, if source_path exists, and raise a FileNotFoundError otherwise. If there is no source access, it will check if there is a cached version of source_path and return its path, issuing a DirCache.NoSourceAccessWarning (unless self.enable_no_root_access_warnings was set to False).

If source_path is not a sub-path of the caches’ server_root_path, it will just check if the path exists, (raising a FileNotFoundError if not) and return source_path again.

Parameters:

• source_path – Path to the content, can be absolute or relative, where relative is interpreted relative to the caches server root path.

• prune_target_folder – If the path is a directory AND source access exists AND the result path contains unexpected extra contents, removing the extra contents on cache update can be disabled by providing False.

Returns:

Path to the (cached or original) version of source_path.

Raises:

FileNotFoundError – If source_path does not exist and there is no cached version.

clear() → None

Clears the entire cache.

remove(result_path: str) → None

Ensures the given result_path is no longer in the cache. If the path is not a cache path, nothing will happen.

Parameters:

result_path – Path previously returned by a get_path call, can be cached or not.

get_server_root_path()

Returns:

The root path managed by this cache.

get_cached_path(source_path: str) → [<class 'str'>, None]

Returns the cached path associated with source_path without doing any caching. Returns None if the given source path is not valid for this cache.

is_valid_source_path(source_path: str) → bool

Parameters:

source_path – A directory or file path

Returns:

True if the given source_path is a sub-path of this caches’ server root path.

is_cache_path(result_path: str) → bool

Allows the user to find out if a path (e.g. one returned by get) is in the cache or not.

Parameters:

result_path – Some path, typically a result of get

Returns:

True if result_path is located in the cache.

has_source_access() → bool

Returns:

True if there is read access to the caches’ server root path.

get_cache_root_path() → str

Returns:

The root of the cached version of the caches’ server root path.