CacheFile

ClassSource

cache = CacheFile(
    cache_dir: str | os.PathLike | TempDir | None,
    chunk_size: int = 1,
)

The cache implementation based on a temporary folder.

Different from a memory-based cache like CachePlain and CacheQueue, this CacheFile is purely implemented by file I/O. Therefore, it will not automatically delete expired file. Users need to take responsibility of managing the files by themselves.

However, when the quit of the running program is catched by atexit, the entire temporary folder should be removed.

Aliases

This class can be acquired by

import dash_file_cache as dfc


dfc.CacheFile
dfc.caches.CacheFile
dfc.caches.memory.CacheFile

Arguments

Argument	Type	Required	Description
cache_dir	str | os.PathLike | TempDir | None		The path of the temporary directory used by this cache. If a str or PathLike is used, cache_dir is the path to the folder. It means that this folder will be managed by this CacheFile. The path will be converted to TempDir. If a TempDir is used, it means that this cache is sharing a temporary folder with other caches. The folder will be managed by the given cache_dir. If None is used, a temporary folder will be created by tempfile.mkdtemp and the folder will be managed by a TempDir created by this CacheFile.
chunk_size	int		The chunk size when saving a large file. The unit is MB.

Methods

key_to_path

path: str = cache.key_to_path(key: str)

Given the key of the file, return the file path without extensions.

Requires

Argument	Type	Required	Description
key	str		The keyword of a cached item.

Returns

Argument	Type	Description
path	str	The base path to the cached item queried by key.

---

is_in

flag: bool = cache.is_in(key: str)

Check whether key is registered in the cache.

The __contains__ operator is delegated to this method.

Requires

Argument	Type	Required	Description
key	str		The keyword to be validated.

Returns

Argument	Type	Description
flag	bool	If True, the given key value exists in the cache.

---

remove

info: CachedFileInfo = cache.remove(key: str)

Remove the info of one cached item from this cache.

Using this method implies that the data in the cache reaches its end of life. Only the cache item information will still be usable.

Requires

Argument	Type	Required	Description
key	str		The keyword of the data to be removed.

Returns

Argument	Type	Description
info	CachedFileInfo	The light-weighted metadata queried in the cache.

---

dump

cache.dump(key: str, info: CachedFileInfo, data: CachedData)

Dump data to the cache.

Requires

Argument	Type	Required	Description
key	str		The key value of this new data. If the key exists in the cache, will replace the original value.
info	CachedFileInfo		The light-weighted metadata to be dumped into the cache.
data	CachedData		The data to be dumped into the cache.

---

load

info, data_loader = cache.load(key: str)

Load the data by a specific keyword.

Requires

Argument	Type	Required	Description
key	str		The key value of to be queried. If key does not exist in the cache, will raise a FileNotFoundError.

Returns

Argument	Type	Description
info	CachedFileInfo	The light-weighted metadata queried in the cache.
data_loader	Callable[[], CachedData]	The lazy loader for the data. This function implements a deferred loading mechanism allowing that the large-size data to be actually loaded when this method is called.

---

load_info

info: CachedFileInfo = cache.load_info(key: str)

Load the metadata by a specific keyword.

This method is implemented by fetching the returned value load(key)[0].

Requires

Argument	Type	Required	Description
key	str		The key value of to be queried. If key does not exist in the cache, will raise a FileNotFoundError.

Returns

Argument	Type	Description
info	CachedFileInfo	The light-weighted metadata queried in the cache.

---

load_data

data: CachedData = cache.load_data(key: str)

Load the data by a specific keyword.

This method is implemented by fetching and calling load(key)[1]().

Requires

Argument	Type	Required	Description
key	str		The key value of to be queried. If key does not exist in the cache, will raise a FileNotFoundError.

Returns

Argument	Type	Description
data	CachedData	The data object queried in the cache. Since data may be large, this value should be a file-like object in most cases.

Properties

chunk_size

chunk_size: int = cache.chunk_size

new_chunk_size: int
cache.chunk_size = new_chunk_size

The chunk size when saving a large file. The unit is MB.

---

dir

cache_dir: TempDir = cache.dir

Get the temporary dir (see TempDir) of this cache. Exporting this value to other CacheFile instances can make the temporary directory shared.

Operators

__contains__

flag: bool = key in cache

Check whether key is registered in the cache.

Requires

Argument	Type	Required	Description
key	str		The keyword to be validated.

Returns

Argument	Type	Description
flag	bool	If True, the given key value exists in the cache.

Examples

See

Cache types