Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/alex-ber/AlexBerUtils/llms.txt

Use this file to discover all available pages before exploring further.

​
AsyncCache

An asynchronous, thread-safe cache supporting LFU (Least Frequently Used) and LRU (Least Recently Used) eviction policies with an optional per-entry Time-to-Live. All item access methods are coroutines and internally guard state with an RLock, making the cache safe for use across concurrent async tasks.
​
maxsize
int
required
Maximum number of entries the cache will hold before evicting.
​
ttl
Optional[int]
default:"None"
Time-to-Live in seconds. When set, expired entries are treated as cache misses. Pass None to disable expiry.
​
policy
str
default:"LFU"
Eviction policy. Accepted values: "LFU" or "LRU".
Raises:
  • ValueError — if policy is not "LFU" or "LRU".
from alexber.utils.cache import AsyncCache

cache = AsyncCache(maxsize=128, ttl=60, policy="LRU")

# store
await cache.__setitem__("key", value)

# retrieve
try:
    value = await cache.__getitem__("key")
except KeyError:
    value = compute()

​
AsyncCache.__getitem__

Retrieves a cached value by key. Non-hashable keys are automatically wrapped in a HashableWrapper.
​
key
Any
required
Cache key. Need not be natively hashable.
Returns: The cached value (Any). Raises:
  • KeyError — if the key is not present or has expired.

​
AsyncCache.__setitem__

Stores a value under the given key. If TTL is configured, the expiry timestamp is recorded in nanoseconds. Non-hashable keys are automatically wrapped.
​
key
Any
required
Cache key.
​
value
Any
required
Value to cache.
Returns: None

​
AsyncCache.update_profiling

Records one function execution time for statistical purposes. Called automatically by the async_cache decorator after each cache miss.
​
exec_time_ns
int
required
Execution time of the wrapped function in nanoseconds.
Returns: None

​
AsyncCache.get_stats

Returns a snapshot of cache performance statistics. Returns: dict with the following string keys:
KeyTypeDescription
hitsintNumber of cache hits
missesintNumber of cache misses
hit_miss_ratiostrRatio formatted to 4 decimal places
max_timestrLongest observed execution, formatted as "X.XXXX s"
min_timestrShortest observed execution, formatted as "X.XXXX s"
avg_timestrAverage execution time, formatted as "X.XXXX s"
total_callsintTotal number of decorated function calls
current_sizeintCurrent number of entries in the cache
max_sizeintMaximum capacity (maxsize)
ttl_secstrTTL as "X.XXXX" or "None"
stats = await cache.get_stats()
print(stats["hit_miss_ratio"])  # e.g. "0.8750"

​
AsyncCache.clear

Evicts all entries and resets all statistics counters to zero. Returns: None 
await cache.clear()

​
async_cache

Decorator that applies an AsyncCache to an async function. On each call, a cache key is derived from the arguments and the result is returned from cache when available, skipping function execution.
​
maxsize
int
Maximum cache size. When omitted, AsyncCache uses its own default.
​
ttl
Optional[int]
default:"None"
Time-to-Live in seconds. Forwarded to AsyncCache.
​
policy
str
default:"LFU"
Eviction policy: "LFU" or "LRU". Forwarded to AsyncCache.
Returns: A decorator that wraps the target async function. The wrapped function exposes a cache_instance attribute (an AsyncCache) for direct inspection or clearing. Cache key strategy:
  • No positional args → key based on frozenset(kwargs.items()).
  • First arg looks like a class instance → key uses id(args[0]) plus remaining args (bound method pattern).
  • Otherwise → key uses all positional args and kwargs.
Non-hashable arguments are converted via make_hashable. 
from alexber.utils.cache import async_cache

@async_cache(maxsize=256, ttl=300, policy="LRU")
async def fetch_user(user_id: int) -> dict:
    return await db.get_user(user_id)

# Access the underlying cache
stats = await fetch_user.cache_instance.get_stats()
await fetch_user.cache_instance.clear()

​
Internal cache backends

These classes are internal implementation details and are not part of the public API. They are documented here for completeness.

​
_LRUCache

A simple LRU (Least Recently Used) eviction cache backed by a dict and a deque. O(n) removal on access due to deque.remove.
MethodDescription
__getitem__(key)Returns value and promotes key to MRU position. Raises KeyError if absent.
__setitem__(key, value)Inserts or updates. Evicts oldest entry when at capacity.
__len__()Current number of cached entries.
__contains__(key)Membership test.
clear()Empties cache and order tracking.

​
_LFUCache

A simple LFU (Least Frequently Used) eviction cache backed by a dict for values, a defaultdict for frequency counts, and a defaultdict(deque) for frequency buckets.
MethodDescription
__getitem__(key)Returns value and increments frequency. Raises KeyError if absent.
__setitem__(key, value)Inserts or updates. Evicts the least-frequently-used entry when at capacity.
__len__()Current number of cached entries.
__contains__(key)Membership test.
clear()Empties all internal structures and resets min_freq.

Build docs developers (and LLMs) love

Get started for freeTalk to us