libera_utils.libera_spice.spice_utils.KernelFileCache

class libera_utils.libera_spice.spice_utils.KernelFileCache(kernel_url: str | Path | S3Path, max_cache_age: timedelta = datetime.timedelta(days=1), fallback_kernel: Path | None = None)

Bases: object

Download, cache, and furnish SPICE kernel files under the user cache directory.

On first access of kernel_path, a valid cached copy (younger than max_cache_age) is reused; otherwise the kernel is materialized from its source into the cache and that path is returned.

Supported sources for kernel_url:

• HTTP(S) URL — str starting with http:// or https://; fetched with requests.

• S3 — s3:// string or cloudpathlib.S3Path; read via smart_open.

• Local file — pathlib.Path or non-URL str path to an existing file; copied with shutil.copy2(). Relative paths are resolved with pathlib.Path.expanduser() and pathlib.Path.resolve() against the process current working directory at the time download_kernel() runs (typically the first uncached read of kernel_path), not at construction time.

If materialization fails and fallback_kernel is set, kernel_path may return that path instead (not recommended for production).

Attributes:

cache_dir

Directory where cached kernel files are stored.

kernel_basename

Base filename of the kernel used in the cache directory.

kernel_path

Path to the kernel in the cache, materializing it if necessary.

Methods

clear()	Remove the cached kernel file from the cache directory if it exists.
download_kernel(kernel_url[, allowed_attempts])	Copy or download a kernel into the user cache directory.
is_cached([include_stale])	Return whether a usable cached copy of the kernel exists.

__init__(kernel_url: str | Path | S3Path, max_cache_age: timedelta = datetime.timedelta(days=1), fallback_kernel: Path | None = None) → None

Create a cache handle; copying or download happens on first use of kernel_path if needed.

Parameters:

• kernel_url (str or pathlib.Path or cloudpathlib.S3Path) – Remote URL, S3 location, or path to a local kernel file.

• max_cache_age (datetime.timedelta) – Maximum age of a cached file before it is treated as stale and replaced.

• fallback_kernel (pathlib.Path or None) – Optional path returned if materialization from kernel_url fails.

Methods

clear()	Remove the cached kernel file from the cache directory if it exists.
download_kernel(kernel_url[, allowed_attempts])	Copy or download a kernel into the user cache directory.
is_cached([include_stale])	Return whether a usable cached copy of the kernel exists.

Attributes

cache_dir	Directory where cached kernel files are stored.
kernel_basename	Base filename of the kernel used in the cache directory.
kernel_path	Path to the kernel in the cache, materializing it if necessary.

static _resolve_local_kernel_file(kernel_url: Path | str) → Path

Return an absolute path to an existing local kernel file.

Parameters:

kernel_url (pathlib.Path or str) – Path to a kernel file (not a directory).

Returns:

Resolved path suitable as the copy source.

Return type:

pathlib.Path

Raises:

FileNotFoundError – If the resolved path is not a regular file.

property cache_dir: Path

Directory where cached kernel files are stored.

Returns:

User-specific cache directory for this application.

Return type:

pathlib.Path

clear() → None

Remove the cached kernel file from the cache directory if it exists.

download_kernel(kernel_url: str | Path | S3Path, allowed_attempts: int = 3) → Path

Copy or download a kernel into the user cache directory.

Parameters:

• kernel_url (str or pathlib.Path or cloudpathlib.S3Path) – Same kinds of sources as KernelFileCache (S3, HTTP(S) URL, or local file).

• allowed_attempts (int, optional) – Retries for HTTP downloads only.

Returns:

Path to the file in the cache directory.

Return type:

pathlib.Path

Raises:

• FileNotFoundError – If kernel_url denotes a local path that does not exist or is not a file.

• requests.exceptions.RequestException – If the HTTP download fails after all retries.

• ValueError – If kernel_url is not a supported type or not an HTTP(S) URL when given as str.

is_cached(include_stale: bool = False) → bool

Return whether a usable cached copy of the kernel exists.

Parameters:

include_stale (bool, optional) – If True, treat kernels older than max_cache_age as still cached.

Returns:

True if the cache file exists and is not stale (unless include_stale is True).

Return type:

bool

property kernel_basename: str

Base filename of the kernel used in the cache directory.

Returns:

Filename only (no directory components).

Return type:

str

property kernel_path: Path

Path to the kernel in the cache, materializing it if necessary.

Returns:

Path to the cached file, or fallback_kernel if materialization failed and a fallback was set.

Return type:

pathlib.Path