Caching

🤖 AI-Generated Content

This documentation was generated with AI assistance and is still being audited. Some, or potentially a lot, of this information may be inaccurate. Learn more.

provide.foundation.utils.caching

Caching utilities for Foundation.

Provides efficient caching mechanisms for frequently accessed data with configurable size limits and optional TTL support.

Classes

LRUCache

LRUCache(maxsize: int = 128)

Thread-safe LRU cache with configurable size.

This is a simple LRU cache that maintains insertion order and evicts least recently used items when the cache is full.

Initialize LRU cache.

Parameters:

Name	Type	Description	Default
maxsize	int	Maximum number of items to cache	128

Source code in provide/foundation/utils/caching.py

def __init__(self, maxsize: int = 128) -> None:
    """Initialize LRU cache.

    Args:
        maxsize: Maximum number of items to cache
    """
    self.maxsize = maxsize
    self._cache: OrderedDict[Any, Any] = OrderedDict()
    self._lock = threading.RLock()
    self._hits = 0
    self._misses = 0

Functions

clear

clear() -> None

Clear all cached items.

Source code in provide/foundation/utils/caching.py

def clear(self) -> None:
    """Clear all cached items."""
    with self._lock:
        self._cache.clear()
        self._hits = 0
        self._misses = 0

get

get(key: Any, default: Any = None) -> Any

Get value from cache.

Parameters:

Name	Type	Description	Default
key	Any	Cache key	required
default	Any	Default value if key not found	None

Returns:

Type	Description
Any	Cached value or default

Source code in provide/foundation/utils/caching.py

def get(self, key: Any, default: Any = None) -> Any:
    """Get value from cache.

    Args:
        key: Cache key
        default: Default value if key not found

    Returns:
        Cached value or default
    """
    with self._lock:
        if key in self._cache:
            # Move to end (most recently used)
            self._cache.move_to_end(key)
            self._hits += 1
            return self._cache[key]
        self._misses += 1
        return default

set

set(key: Any, value: Any) -> None

Set value in cache.

Parameters:

Name	Type	Description	Default
key	Any	Cache key	required
value	Any	Value to cache	required

Source code in provide/foundation/utils/caching.py

def set(self, key: Any, value: Any) -> None:
    """Set value in cache.

    Args:
        key: Cache key
        value: Value to cache
    """
    with self._lock:
        if key in self._cache:
            # Update existing and move to end
            self._cache.move_to_end(key)
        self._cache[key] = value

        # Evict oldest if over limit
        if len(self._cache) > self.maxsize:
            self._cache.popitem(last=False)

stats

stats() -> dict[str, int | float]

Get cache statistics.

Returns:

Type	Description
dict[str, int | float]	Dictionary with hits, misses, size, maxsize, and hit_rate

Source code in provide/foundation/utils/caching.py

def stats(self) -> dict[str, int | float]:
    """Get cache statistics.

    Returns:
        Dictionary with hits, misses, size, maxsize, and hit_rate
    """
    with self._lock:
        total = self._hits + self._misses
        hit_rate = (self._hits / total * 100) if total > 0 else 0.0
        return {
            "hits": self._hits,
            "misses": self._misses,
            "size": len(self._cache),
            "maxsize": self.maxsize,
            "hit_rate": hit_rate,
        }

Functions

cached

cached(
    maxsize: int = 128, enabled: bool | None = None
) -> Callable

Decorator to cache function results with LRU eviction.

Parameters:

Name	Type	Description	Default
maxsize	int	Maximum number of cached results	128
enabled	bool | None	Whether caching is enabled (defaults to FOUNDATION_CACHE_ENABLED)	None

Returns:

Type	Description
Callable	Decorated function with caching

Example

@cached(maxsize=100) ... def expensive_operation(x: int) -> int: ... return x * x

Source code in provide/foundation/utils/caching.py

def cached(maxsize: int = 128, enabled: bool | None = None) -> Callable:
    """Decorator to cache function results with LRU eviction.

    Args:
        maxsize: Maximum number of cached results
        enabled: Whether caching is enabled (defaults to FOUNDATION_CACHE_ENABLED)

    Returns:
        Decorated function with caching

    Example:
        >>> @cached(maxsize=100)
        ... def expensive_operation(x: int) -> int:
        ...     return x * x
    """
    cache_enabled = enabled if enabled is not None else _CACHE_ENABLED

    def decorator(func: Callable[..., T]) -> Callable[..., T]:
        if not cache_enabled:
            # Return original function if caching disabled
            return func

        cache = LRUCache(maxsize=maxsize)

        @wraps(func)
        def wrapper(*args: Any, **kwargs: Any) -> T:
            # Create cache key from args and kwargs
            key = (args, tuple(sorted(kwargs.items())))

            result = cache.get(key)
            if result is None:
                result = func(*args, **kwargs)
                cache.set(key, result)

            return cast(T, result)

        # Attach cache object for testing/inspection
        wrapper.cache = cache  # type: ignore[attr-defined]
        wrapper.cache_clear = cache.clear  # type: ignore[attr-defined]
        wrapper.cache_stats = cache.stats  # type: ignore[attr-defined]

        return wrapper

    return decorator

clear_all_caches

clear_all_caches() -> None

Clear all registered caches.

Useful for testing and cache invalidation.

Source code in provide/foundation/utils/caching.py

def clear_all_caches() -> None:
    """Clear all registered caches.

    Useful for testing and cache invalidation.
    """
    with _registry_lock:
        for cache in _cache_registry.values():
            cache.clear()

get_cache

get_cache(name: str) -> LRUCache | None

Get a registered cache by name.

Parameters:

Name	Type	Description	Default
name	str	Cache identifier	required

Returns:

Type	Description
LRUCache | None	Cache instance or None if not found

Source code in provide/foundation/utils/caching.py

def get_cache(name: str) -> LRUCache | None:
    """Get a registered cache by name.

    Args:
        name: Cache identifier

    Returns:
        Cache instance or None if not found
    """
    with _registry_lock:
        return _cache_registry.get(name)

get_cache_stats

get_cache_stats() -> dict[str, dict[str, int | float]]

Get statistics for all registered caches.

Returns:

Type	Description
dict[str, dict[str, int | float]]	Dictionary mapping cache names to their statistics

Source code in provide/foundation/utils/caching.py

def get_cache_stats() -> dict[str, dict[str, int | float]]:
    """Get statistics for all registered caches.

    Returns:
        Dictionary mapping cache names to their statistics
    """
    with _registry_lock:
        return {name: cache.stats() for name, cache in _cache_registry.items()}

register_cache

register_cache(name: str, cache: LRUCache) -> None

Register a named cache for global management.

Parameters:

Name	Type	Description	Default
name	str	Cache identifier	required
cache	LRUCache	Cache instance to register	required

Source code in provide/foundation/utils/caching.py

def register_cache(name: str, cache: LRUCache) -> None:
    """Register a named cache for global management.

    Args:
        name: Cache identifier
        cache: Cache instance to register
    """
    with _registry_lock:
        _cache_registry[name] = cache