Cache

Cache Manager

The sierra.internal.cache module provides a simple file‑based cache for speeding up repeated operations (e.g., sideloader scans, compilation outputs).

Using the CacheManager

from pathlib import Path
from sierra.internal.cache import CacheManager

# Create a cache directory inside your environment
cache_dir = Path("default_env") / "cache"
cache = CacheManager(cache_dir=cache_dir)

# Store a value in the cache
cache.set("last_run_scripts", ["greet.py", "scan.py"])

# Retrieve a cached value (or None if missing)
scripts = cache.get("last_run_scripts")
print(scripts)  # ["greet.py", "scan.py"]

sierra.internal.cache

Classes

CompressionType

Bases: Enum

Compression types for cache entries.

Attributes

NONE class-attribute instance-attribute

Python

NONE = 'none'

GZIP class-attribute instance-attribute

Python

GZIP = 'gzip'

CacheEntry dataclass

Python

CacheEntry(key: str, value: typing.Any, created_at: float, expires_at: float | None = None, compression: CompressionType = CompressionType.NONE, size_bytes: int = 0, access_count: int = 0, last_accessed: float = 0.0)

Represents a cache entry with metadata.

Attributes

key instance-attribute

Python

key: str

value instance-attribute

Python

value: typing.Any

created_at instance-attribute

Python

created_at: float

expires_at class-attribute instance-attribute

Python

expires_at: float | None = None

compression class-attribute instance-attribute

Python

compression: CompressionType = CompressionType.NONE

size_bytes class-attribute instance-attribute

Python

size_bytes: int = 0

access_count class-attribute instance-attribute

Python

access_count: int = 0

last_accessed class-attribute instance-attribute

Python

last_accessed: float = 0.0

CacheManager

Python

CacheManager(cache_dir: pathlib.Path | None = None, max_memory_entries: int = 1000, cleanup_interval: float = 3600, auto_cleanup: bool = True)

A full-featured cache manager with SQLite-backed persistence, TTL expiration, auto-cleanup, compression, and efficient key enumeration.

Features: - SQLite-backed metadata storage for fast key enumeration - Separate file storage for large values - Memory cache for frequently accessed items - TTL support with automatic cleanup - Compression support (gzip) - Thread-safe operations - Access statistics tracking - Atomic operations

Initialize the CacheManager.

PARAMETER	DESCRIPTION
cache_dir	Directory for cache storage. If None, uses OS-appropriate location. TYPE: pathlib.Path DEFAULT: None
max_memory_entries	Maximum number of entries to keep in memory cache. TYPE: int DEFAULT: 1000
cleanup_interval	Interval in seconds between automatic cleanup runs. TYPE: float DEFAULT: 3600
auto_cleanup	Whether to automatically clean up expired entries. TYPE: bool DEFAULT: True

Functions

set

Python

set(key: str, value: typing.Any, ttl: float | None = None, persist: bool = True, compress: bool = False) -> None

Store a value in the cache.

PARAMETER	DESCRIPTION
key	Cache key. TYPE: str
value	Value to cache. TYPE: Any
ttl	Time to live in seconds. TYPE: float DEFAULT: None
persist	Whether to persist to disk (default: True). TYPE: bool DEFAULT: True
compress	Whether to compress the value. TYPE: bool DEFAULT: False

get

Python

get(key: str) -> typing.Any | None

Retrieve a value from the cache.

PARAMETER	DESCRIPTION
key	Cache key. TYPE: str

RETURNS	DESCRIPTION
Any or None	The cached value or None if not found/expired.

exists

Python

exists(key: str) -> bool

Check if a key exists and is not expired.

PARAMETER	DESCRIPTION
key	Cache key. TYPE: str

RETURNS	DESCRIPTION
bool	True if the key exists and is valid.

delete

Python

delete(key: str) -> None

Delete a cache entry.

PARAMETER	DESCRIPTION
key	Cache key. TYPE: str

clear

Python

clear() -> None

Clear all cache entries.

keys

Python

keys(include_expired: bool = False) -> list[str]

Get all cache keys.

PARAMETER	DESCRIPTION
include_expired	Whether to include expired keys. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
List[str]	List of cache keys.

cleanup

Python

cleanup() -> int

Manually clean up expired entries.

RETURNS	DESCRIPTION
int	Number of entries removed.

stats

Python

stats() -> dict[str, typing.Any]

Get cache statistics.

RETURNS	DESCRIPTION
Dict[str, Any]	Statistics dictionary.

get_entry_info

Python

get_entry_info(key: str) -> dict[str, typing.Any] | None

Get detailed information about a cache entry.

PARAMETER	DESCRIPTION
key	Cache key. TYPE: str

RETURNS	DESCRIPTION
Dict[str, Any] or None	Entry information or None if not found.

close

Python

close() -> None

Close the cache manager and perform final cleanup.