vayu.cache

cache

Serializer

Bases: ABC

Strategy for converting cached values to/from bytes.

Pickler

Bases: Serializer

Serializer that uses pickle with the highest protocol.

Supports arbitrary Python objects but is not safe to read from untrusted sources.

Jsoner

Bases: Serializer

Serializer that uses JSON.

Uses orjson when installed (faster), otherwise falls back to the standard-library json. Only handles JSON-serializable values.

CacheMissError

Bases: Exception

Raised on cache miss or when a cached entry has expired.

Cache

Cache(serializer: Serializer)

Bases: ABC

Abstract TTL cache with sync and async @cached decorators.

Subclasses implement the backend (_read / _write / _delete, each in sync and async form). Concrete implementations include FileCache and MemoryCache.

Source code in vayu/cache.py

def __init__(self, serializer: Serializer):
    self._serializer = serializer
    self._locks = dict()
    self._sync_locks = dict()

cached

cached(
    ttl: Union[timedelta, float],
    prefix: str = None,
    key: Union[str, Callable] = None,
    serializer: Serializer = None,
    log: bool = True,
)

Used as decorator to cache function calls.

Parameters:

Name	Type	Description	Default
ttl	Union[timedelta, float]	cache expiry ttl	required
prefix	str	If set, gets prepended to the rest of the cache key, otherwise uses function, class, and module name to create prefix.	None
key	Union[str, Callable]	None: Use SHA256 digest of args & *kwargs to construct cache key str: Use the specified string and ignore function arguments Callable: Calls it with args * *kwargs which returns a str key.	None
serializer	Serializer	If not specified, default pickler serializer is used	None
log	bool	If True, logs reports such as cache hit, miss etc.	True

Source code in vayu/cache.py

def cached(
    self,
    ttl: Union[timedelta, float],
    prefix: str = None,
    key: Union[str, Callable] = None,
    serializer: Serializer = None,
    log: bool = True,
):
    """Used as decorator to cache function calls.

    Args:
        ttl: cache expiry ttl
        prefix: If set, gets prepended to the rest of the cache key, otherwise uses function,
                    class, and module name to create prefix.
        key:
            - None: Use SHA256 digest of *args & **kwargs to construct cache key
            - str: Use the specified string and ignore function arguments
            - Callable: Calls it with *args * **kwargs which returns a str key.
        serializer: If not specified, default pickler serializer is used
        log: If True, logs reports such as cache hit, miss etc.

    """
    serializer = serializer or self._serializer
    if ttl is None:
        raise ValueError("ttl must be specified for cached decorator")
    if not isinstance(ttl, timedelta):
        ttl = timedelta(seconds=ttl)
    if ttl.total_seconds() <= 0:
        raise ValueError("ttl must be positive")

    @auto_adapt_to_methods
    def decorator(func):
        if asyncio.iscoroutinefunction(func):
            return self._make_async_wrapper(func, serializer, ttl, prefix, key, log)
        else:
            return self._make_sync_wrapper(func, serializer, ttl, prefix, key, log)

    return decorator

FileCache

FileCache(path: str, serializer: Serializer = None)

Bases: Cache

Persistent cache backed by files under a directory.

One file per key. Writes are atomic (write to a temp file in the same directory, then replace). Note: cache keys become filenames, so custom key= callables must return filesystem-legal strings (avoid /, etc.).

Parameters:

Name	Type	Description	Default
path	str	Directory to store cache files. Created if it doesn't exist.	required
serializer	Serializer	How to encode values. Defaults to Pickler.	None

Source code in vayu/cache.py

def __init__(self, path: str, serializer: Serializer = None):
    super().__init__(serializer or Pickler())
    self._path = Path(path)
    self._ttl_bytes_length = 8
    self._path.mkdir(parents=True, exist_ok=True)

MemoryCache

MemoryCache()

Bases: Cache

In-process cache backed by a plain dict.

Uses a no-op serializer — values are stored by reference, not copied. Volatile: everything is lost when the process exits. The module-level mem_cache is an instance of this class, and mem_cached is a shortcut to mem_cache.cached.

Source code in vayu/cache.py

def __init__(self):
    super().__init__(self.NoOpSerializer())
    self._cache = {}

auto_adapt_to_methods

auto_adapt_to_methods(decorator)

Allows you to use the same decorator on methods and functions, hiding the self argument from the decorator.

Source code in vayu/cache.py

def auto_adapt_to_methods(decorator):
    """Allows you to use the same decorator on methods and functions,
    hiding the self argument from the decorator."""

    def adapt(func):
        return _MethodDecoratorAdaptor(decorator, func)

    return adapt