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

`cache_dir`
`allow_clear`
`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
>>> disk_cache = DiskCacheStore(cache_dir="cache", allow_clear=True)
>>> disk_cache.exists("file.nc")
False

>>> from pycontrails import GCPCacheStore
>>> gcp_cache = GCPCacheStore(bucket="contrails-301217-unit-test", cache_dir="cache")
>>> gcp_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'

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
>>> disk_cache = DiskCacheStore(cache_dir="cache", allow_clear=True)
>>> disk_cache.path("file.nc")
'cache/file.nc'

>>> disk_cache.clear()  # cleanup

>>> from pycontrails import GCPCacheStore
>>> gcp_cache = GCPCacheStore(bucket="contrails-301217-unit-test", cache_dir="cache")
>>> gcp_cache.path("file.nc")
'cache/file.nc'

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'

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
>>> disk_cache = DiskCacheStore(cache_dir="cache", allow_clear=True)
>>> disk_cache.size
0.0...

>>> disk_cache.clear()  # cleanup

>>> from pycontrails import GCPCacheStore
>>> gcp_cache = GCPCacheStore(bucket="contrails-301217-unit-test", cache_dir="cache")
>>> gcp_cache.size
0.0...