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...