pycontrails.DiskCacheStore¶

class pycontrails.DiskCacheStore(cache_dir=None, allow_clear=False)¶

Bases: CacheStore

Cache that uses a folder on the local filesystem.

Parameters:

allow_clear (bool, optional) – Allow this cache to be cleared using clear(). Defaults to False.
cache_dir (str | pathlib.Path, optional) – Root cache directory. By default, looks first for PYCONTRAILS_CACHE_DIR environment variable, then uses the OS specific platformdirs.user_cache_dir() function.

Examples

>>> from pycontrails import DiskCacheStore
>>> disk_cache = DiskCacheStore(cache_dir="cache", allow_clear=True)
>>> disk_cache.cache_dir
'cache'

>>> disk_cache.clear()  # cleanup

__init__(cache_dir=None, allow_clear=False)¶

Methods

`__init__`([cache_dir, allow_clear])
`clear`([cache_path])	Delete all files and folders within `cache_path`.
`exists`(cache_path)	Check if a path in cache exists.
`get`(cache_path)	Get data path from the local cache store.
`listdir`([path])	List the contents of a directory in the cache.
`path`(cache_path)	Return a full filepath in cache.
`put`(data_path[, cache_path])	Save data to the local cache store.
`put_multiple`(data_path, cache_path)	Put multiple files into the cache at once.

Attributes

`allow_clear`
`cache_dir`
`size`	Return the disk size (in MBytes) of the local cache.

allow_clear¶

cache_dir¶

clear(cache_path='')¶

Delete all files and folders within cache_path.

If no cache_path is provided, this will clear the entire cache.

If allow_clear is set to False, this method will do nothing.

Parameters:: cache_path (str, optional) – Path to subdirectory or file in cache
Raises:: RuntimeError – Raises a RuntimeError when allow_clear is set to False

Examples

>>> from pycontrails import DiskCacheStore
>>> disk_cache = DiskCacheStore(cache_dir="cache", allow_clear=True)

>>> # Write some data to the cache
>>> disk_cache.put("README.md", "test/example.txt")
'test/example.txt'

>>> disk_cache.exists("test/example.txt")
True

>>> # clear a specific path
>>> disk_cache.clear("test/example.txt")

>>> # clear the whole cache
>>> disk_cache.clear()

exists(cache_path)¶

Check if a path in cache exists.

Parameters:: cache_path (str) – Path to directory or file in cache
Returns:: bool – True if directory or file exists

Examples

>>> from pycontrails import DiskCacheStore
>>> cache = DiskCacheStore(cache_dir="cache", allow_clear=True)
>>> cache.exists("file.nc")
False

get(cache_path)¶

Get data path from the local cache store.

Alias for path()

Parameters:: cache_path (str) – Cache path to retrieve
Returns:: str – Returns the relative path in the cache to the stored file

Examples

>>> from pycontrails import DiskCacheStore
>>> disk_cache = DiskCacheStore(cache_dir="cache", allow_clear=True)
>>>
>>> # returns a path
>>> disk_cache.get("test/file.md")
'cache/test/file.md'

>>> disk_cache.clear()  # cleanup

listdir(path='')¶

List the contents of a directory in the cache.

Parameters:: path (str) – Path to the directory to list
Returns:: list[str] – List of files in the directory

path(cache_path)¶

Return a full filepath in cache.

Parameters:: cache_path (str) – string path or filepath to create in cache If parent directories do not exist, they will be created.
Returns:: str – Full path string to subdirectory directory or object in cache directory

Examples

>>> from pycontrails import DiskCacheStore
>>> cache = DiskCacheStore(cache_dir="cache", allow_clear=True)
>>> cache.path("file.nc")
'cache/file.nc'

>>> cache.clear()  # cleanup

put(data_path, cache_path=None)¶

Save data to the local cache store.

Parameters:

data_path (str | pathlib.Path) – Path to data to cache.
cache_path (str | None, optional) – Path in cache store to save data Defaults to the same filename as data_path

Returns:

str – Returns the relative path in the cache to the stored file

Raises:

FileNotFoundError – Raises if data is a string and a file is not found at the string

Examples

>>> from pycontrails import DiskCacheStore
>>> disk_cache = DiskCacheStore(cache_dir="cache", allow_clear=True)
>>>
>>> # put a file directly
>>> disk_cache.put("README.md", "test/file.md")
'test/file.md'

>>> disk_cache.clear()  # cleanup

put_multiple(data_path, cache_path)¶

Put multiple files into the cache at once.

Parameters:

data_path (Sequence[str | pathlib.Path]) – List of data files to cache. Each member is passed directly on to put().
cache_path (list[str]) – List of cache paths corresponding to each element in the data_path list. Each member is passed directly on to put().

Returns:

list[str] – Returns a list of relative paths to the stored files in the cache

property size¶

Return the disk size (in MBytes) of the local cache.

Returns:: float – Size of the disk cache store in MB

Examples

>>> from pycontrails import DiskCacheStore
>>> cache = DiskCacheStore(cache_dir="cache", allow_clear=True)
>>> cache.size
0.0...

>>> cache.clear()  # cleanup