uf.caching#

Result caching for uf.

Provides caching decorators and backends to cache function results, improving performance for expensive operations.

Functions

cache_clear_all([backend])

Clear all cache entries.

cache_invalidate(cache_key[, backend])

Invalidate a specific cache entry.

cached([ttl, backend, key_func])

Decorator to cache function results.

get_global_cache_backend()

Get the global cache backend.

make_cache_key(func_name, args, kwargs)

Create a cache key from function call.

set_global_cache_backend(backend)

Set the global cache backend.

Classes

CacheBackend()

Base class for cache backends.

CacheStats()

Track cache hit/miss statistics.

DiskCache([cache_dir, default_ttl])

Disk-based cache backend using pickle.

MemoryCache([default_ttl, max_size])

In-memory cache backend.
class uf.caching.CacheBackend[source]#

Bases: object

Base class for cache backends.

clear()[source]#

Clear all cache entries.

Return type:

None

delete(key)[source]#

Delete a key from cache.

Parameters:

key (str) – Cache key

Return type:

bool

Returns:

True if deleted

exists(key)[source]#

Check if key exists in cache.

Parameters:

key (str) – Cache key

Return type:

bool

Returns:

True if exists and not expired

get(key)[source]#

Get a value from cache.

Parameters:

key (str) – Cache key

Return type:

Optional[Any]

Returns:

Cached value or None if not found/expired

set(key, value, ttl=None)[source]#

Set a value in cache.

Parameters:

  • key (str) – Cache key

  • value (Any) – Value to cache

  • ttl (Optional[int]) – Time to live in seconds

Return type:

None

class uf.caching.CacheStats[source]#

Bases: object

Track cache hit/miss statistics.

hit_rate()[source]#

Calculate hit rate.

Return type:

float

Returns:

Hit rate as a percentage (0-100)

record_hit()[source]#

Record a cache hit.

record_miss()[source]#

Record a cache miss.

record_set()[source]#

Record a cache set.

reset()[source]#

Reset all statistics.

to_dict()[source]#

Convert to dictionary.

Return type:

dict

Returns:

Statistics dictionary

class uf.caching.DiskCache(cache_dir='.uf_cache', default_ttl=3600)[source]#

Bases: CacheBackend

Disk-based cache backend using pickle.

Persists cache to disk, suitable for larger datasets or persistence across restarts.

Example

>>> cache = DiskCache(cache_dir='/tmp/uf_cache')
>>> cache.set('expensive_result', big_data)
clear()[source]#

Clear all cache entries.

Return type:

None

delete(key)[source]#

Delete a key from cache.

Return type:

bool

get(key)[source]#

Get a value from cache.

Return type:

Optional[Any]

set(key, value, ttl=None)[source]#

Set a value in cache.

Return type:

None

class uf.caching.MemoryCache(default_ttl=3600, max_size=1000)[source]#

Bases: CacheBackend

In-memory cache backend.

Simple dictionary-based caching suitable for single-process applications.

Example

>>> cache = MemoryCache(default_ttl=3600)
>>> cache.set('key', 'value', ttl=60)
>>> value = cache.get('key')
cleanup_expired()[source]#

Remove expired entries.

Return type:

int

Returns:

Number of entries removed

clear()[source]#

Clear all cache entries.

Return type:

None

delete(key)[source]#

Delete a key from cache.

Return type:

bool

get(key)[source]#

Get a value from cache.

Return type:

Optional[Any]

set(key, value, ttl=None)[source]#

Set a value in cache.

Return type:

None

stats()[source]#

Get cache statistics.

Return type:

dict

Returns:

Dictionary with cache stats

uf.caching.cache_clear_all(backend=None)[source]#

Clear all cache entries.

Parameters:

backend (Optional[CacheBackend]) – Cache backend (uses global if None)

Return type:

None

uf.caching.cache_invalidate(cache_key, backend=None)[source]#

Invalidate a specific cache entry.

Parameters:

  • cache_key (str) – Cache key to invalidate

  • backend (Optional[CacheBackend]) – Cache backend (uses global if None)

Return type:

bool

Returns:

True if invalidated

uf.caching.cached(ttl=3600, backend=None, key_func=None)[source]#

Decorator to cache function results.

Parameters:

  • ttl (int) – Time to live in seconds

  • backend (Optional[CacheBackend]) – Cache backend (uses global MemoryCache if None)

  • key_func (Optional[Callable]) – Optional function to generate cache key

Returns:

Decorator function

Example

>>> @cached(ttl=3600)
... def expensive_calculation(x: int, y: int) -> int:
...     # Only runs once per unique (x, y) combination
...     return heavy_computation(x, y)
>>>
>>> result = expensive_calculation(10, 20)  # Computes
>>> result2 = expensive_calculation(10, 20)  # From cache
uf.caching.get_global_cache_backend()[source]#

Get the global cache backend.

Return type:

Optional[CacheBackend]

uf.caching.make_cache_key(func_name, args, kwargs)[source]#

Create a cache key from function call.

Parameters:

  • func_name (str) – Function name

  • args (tuple) – Positional arguments

  • kwargs (dict) – Keyword arguments

Return type:

str

Returns:

Cache key string

uf.caching.set_global_cache_backend(backend)[source]#

Set the global cache backend.

Return type:

None