persista 0.0.1__py3-none-any.whl

persista/__init__.py

@@ -0,0 +1,13 @@
+r"""Root package."""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version(__name__)
+except PackageNotFoundError:  # pragma: no cover
+    # Package is not installed, fallback if needed
+    __version__ = "0.0.0"

persista/cache/__init__.py

@@ -0,0 +1,27 @@
+r"""Contain caches."""
+
+from __future__ import annotations
+
+__all__ = [
+    "AsyncTTLCache",
+    "TTLCache",
+    "async_cached",
+    "cached",
+    "get_async_ttl_cache",
+    "get_ttl_cache",
+    "make_key",
+    "set_async_ttl_cache",
+    "set_ttl_cache",
+]
+
+from persista.cache.async_ttl import AsyncTTLCache
+from persista.cache.interface import (
+    async_cached,
+    cached,
+    get_async_ttl_cache,
+    get_ttl_cache,
+    set_async_ttl_cache,
+    set_ttl_cache,
+)
+from persista.cache.ttl import TTLCache
+from persista.cache.utils import make_key

persista/cache/async_ttl.py

@@ -0,0 +1,237 @@
+r"""Provide an async TTL cache backed by any ``AsyncBaseStore``."""
+
+from __future__ import annotations
+
+__all__ = ["AsyncTTLCache"]
+
+import functools
+import time
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from persista.cache.utils import make_key
+from persista.store.async_in_memory import AsyncInMemoryStore
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from persista.store.base import AsyncBaseStore
+
+T = TypeVar("T")
+
+
+class AsyncTTLCache:
+    """Async cache with per-entry expiry, backed by any
+    :class:`~persista.store.base.AsyncBaseStore`.
+
+    Each entry is wrapped as ``{"value": value, "expires_at":
+    expires_at}`` before being written to the store, since
+    :class:`~persista.store.base.AsyncBaseStore` only accepts ``dict``
+    values. If the backing store is one that serializes values (e.g.
+    a SQLite- or Redis-backed store), cached values must be
+    JSON-serializable.
+
+    ``expires_at`` is a Unix timestamp (``time.time()``), not a
+    monotonic clock reading, because entries may be read back by a
+    different process or after a restart of this one. Expiry is
+    checked lazily on :meth:`get`: an expired entry is only evicted
+    the next time it is looked up, not proactively at its expiry
+    time.
+
+    Args:
+        store: The backing store. Defaults to a new
+            :class:`~persista.store.async_in_memory.AsyncInMemoryStore`.
+        default_ttl: The default time-to-live, in seconds, applied to
+            entries whose ``ttl`` is not explicitly set. Must be
+            positive.
+
+    Raises:
+        ValueError: If ``default_ttl`` is not positive.
+
+    Example:
+        ```pycon
+        >>> import asyncio
+        >>> from persista.cache import AsyncTTLCache
+        >>> async def main():
+        ...     cache = AsyncTTLCache(default_ttl=60)
+        ...     await cache.set("greeting", "hello")
+        ...     print(await cache.get("greeting"))
+        ...
+        >>> asyncio.run(main())
+        hello
+
+        ```
+    """
+
+    def __init__(self, store: AsyncBaseStore | None = None, default_ttl: float = 300) -> None:
+        if default_ttl <= 0:
+            msg = f"default_ttl must be a positive number, got {default_ttl}"
+            raise ValueError(msg)
+        self._store: AsyncBaseStore = store if store is not None else AsyncInMemoryStore()
+        self.default_ttl = default_ttl
+
+    async def get(self, key: str) -> Any | None:
+        """Retrieve a value by its key.
+
+        If the entry has expired, it is evicted from the backing
+        store as a side effect of this call, before ``None`` is
+        returned.
+
+        Args:
+            key: The key to look up.
+
+        Returns:
+            The cached value, or ``None`` if the key is missing or
+            its entry has expired. This means a cached value of
+            ``None`` is indistinguishable from a cache miss.
+
+        Example:
+            ```pycon
+            >>> import asyncio
+            >>> from persista.cache import AsyncTTLCache
+            >>> async def main():
+            ...     cache = AsyncTTLCache()
+            ...     await cache.set("greeting", "hello")
+            ...     print(await cache.get("greeting"))
+            ...     print(await cache.get("missing"))
+            ...
+            >>> asyncio.run(main())
+            hello
+            None
+
+            ```
+        """
+        entry = await self._store.get(key)
+        if entry is None:
+            return None
+        if time.time() > entry["expires_at"]:
+            await self._store.delete(key)  # expired, evict
+            return None
+        return entry["value"]
+
+    async def set(self, key: str, value: Any, ttl: float | None = None) -> None:
+        """Add a value to the cache.
+
+        Calling this again with an existing key overwrites the
+        previous value and resets its expiry.
+
+        Args:
+            key: The key to set.
+            value: The value to cache. Must be JSON-serializable if
+                the backing store serializes values (see the class
+                docstring).
+            ttl: The time-to-live, in seconds, before the entry
+                expires. Defaults to ``self.default_ttl``. Must be
+                positive.
+
+        Raises:
+            ValueError: If ``ttl`` is not positive.
+
+        Example:
+            ```pycon
+            >>> import asyncio
+            >>> from persista.cache import AsyncTTLCache
+            >>> async def main():
+            ...     cache = AsyncTTLCache()
+            ...     await cache.set("greeting", "hello")
+            ...     print(await cache.get("greeting"))
+            ...     await cache.set("greeting", "bonjour")
+            ...     print(await cache.get("greeting"))
+            ...
+            >>> asyncio.run(main())
+            hello
+            bonjour
+
+            ```
+        """
+        ttl = ttl if ttl is not None else self.default_ttl
+        if ttl <= 0:
+            msg = f"ttl must be a positive number, got {ttl}"
+            raise ValueError(msg)
+        await self._store.set(key, {"value": value, "expires_at": time.time() + ttl})
+
+    async def clear(self) -> None:
+        """Remove every entry from the cache, expired or not.
+
+        Example:
+            ```pycon
+            >>> import asyncio
+            >>> from persista.cache import AsyncTTLCache
+            >>> async def main():
+            ...     cache = AsyncTTLCache()
+            ...     await cache.set("greeting", "hello")
+            ...     await cache.clear()
+            ...     print(await cache.get("greeting"))
+            ...
+            >>> asyncio.run(main())
+            None
+
+            ```
+        """
+        await self._store.clear()
+
+    def memoize(
+        self, ttl: float | None = None
+    ) -> Callable[[Callable[..., Awaitable[T]]], Callable[..., Awaitable[T]]]:
+        """Decorate an async function so its return values are cached.
+
+        The cache key is derived from the decorated function's
+        qualified name (``__qualname__``) and call arguments, via
+        :func:`~persista.cache.utils.make_key`, so calls with equal
+        arguments share a cached result. Call arguments must always
+        be JSON-serializable, regardless of the backing store; the
+        return value must additionally be JSON-serializable if the
+        backing store serializes values (see the class docstring).
+        Because the key is based on ``__qualname__`` rather than
+        object identity, two distinct functions defined with the same
+        qualified name (e.g. two calls to the same factory returning
+        a closure) share their cache entries.
+
+        Args:
+            ttl: The time-to-live, in seconds, applied to cached
+                results. Defaults to ``self.default_ttl``. Must be
+                positive.
+
+        Returns:
+            A decorator that wraps an async function with caching.
+
+        Raises:
+            ValueError: If ``ttl`` is not positive.
+
+        Example:
+            ```pycon
+            >>> import asyncio
+            >>> from persista.cache import AsyncTTLCache
+            >>> cache = AsyncTTLCache()
+            >>> calls = []
+            >>> @cache.memoize(ttl=60)
+            ... async def square(x):
+            ...     calls.append(x)
+            ...     return x * x
+            ...
+            >>> async def main():
+            ...     print(await square(4))
+            ...     print(await square(4))  # served from the cache, not re-computed
+            ...
+            >>> asyncio.run(main())
+            16
+            16
+            >>> calls
+            [4]
+
+            ```
+        """
+
+        def decorator(func: Callable[..., Awaitable[T]]) -> Callable[..., Awaitable[T]]:
+            @functools.wraps(func)
+            async def wrapper(*args: Any, **kwargs: Any) -> Any:
+                key = make_key(func.__qualname__, args, kwargs)
+                cached = await self.get(key)
+                if cached is not None:
+                    return cached
+                result = await func(*args, **kwargs)
+                await self.set(key, result, ttl=ttl)
+                return result
+
+            return wrapper
+
+        return decorator

persista/cache/interface.py

@@ -0,0 +1,245 @@
+r"""Provide module-level access to shared default caches."""
+
+from __future__ import annotations
+
+__all__ = [
+    "async_cached",
+    "cached",
+    "get_async_ttl_cache",
+    "get_ttl_cache",
+    "set_async_ttl_cache",
+    "set_ttl_cache",
+]
+
+
+import functools
+import inspect
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from persista.cache.async_ttl import AsyncTTLCache
+from persista.cache.ttl import TTLCache
+from persista.cache.utils import make_key
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+T = TypeVar("T")
+
+_state = {"cache": TTLCache(), "async_cache": AsyncTTLCache()}
+
+
+def get_ttl_cache() -> TTLCache:
+    """Return the shared default cache.
+
+    Returns:
+        The shared default :class:`~persista.cache.ttl.TTLCache`
+        instance, used by :func:`cached` when no explicit cache is
+        given.
+
+    Example:
+        ```pycon
+        >>> from persista.cache.interface import get_ttl_cache
+        >>> cache = get_ttl_cache()
+        >>> cache.set("greeting", "hello")
+        >>> cache.get("greeting")
+        'hello'
+
+        ```
+    """
+    return _state["cache"]
+
+
+def set_ttl_cache(cache: TTLCache) -> None:
+    """Replace the shared default cache.
+
+    Args:
+        cache: The :class:`~persista.cache.ttl.TTLCache` instance to
+            install as the new shared default, in place of the one
+            returned by :func:`get_ttl_cache`.
+
+    Example:
+        ```pycon
+        >>> from persista.cache import TTLCache
+        >>> from persista.cache import get_ttl_cache, set_ttl_cache
+        >>> set_ttl_cache(TTLCache(default_ttl=60))
+        >>> get_ttl_cache().default_ttl
+        60
+
+        ```
+    """
+    _state["cache"] = cache
+
+
+def get_async_ttl_cache() -> AsyncTTLCache:
+    """Return the shared default async cache.
+
+    Returns:
+        The shared default :class:`~persista.cache.async_ttl.AsyncTTLCache`
+        instance, used by :func:`async_cached` when no explicit cache
+        is given.
+
+    Example:
+        ```pycon
+        >>> import asyncio
+        >>> from persista.cache.interface import get_async_ttl_cache
+        >>> async def main():
+        ...     cache = get_async_ttl_cache()
+        ...     await cache.set("greeting", "hello")
+        ...     print(await cache.get("greeting"))
+        ...
+        >>> asyncio.run(main())
+        hello
+
+        ```
+    """
+    return _state["async_cache"]
+
+
+def set_async_ttl_cache(cache: AsyncTTLCache) -> None:
+    """Replace the shared default async cache.
+
+    Args:
+        cache: The :class:`~persista.cache.async_ttl.AsyncTTLCache`
+            instance to install as the new shared default, in place of
+            the one returned by :func:`get_async_ttl_cache`.
+
+    Example:
+        ```pycon
+        >>> from persista.cache import AsyncTTLCache
+        >>> from persista.cache import get_async_ttl_cache, set_async_ttl_cache
+        >>> set_async_ttl_cache(AsyncTTLCache(default_ttl=60))
+        >>> get_async_ttl_cache().default_ttl
+        60
+
+        ```
+    """
+    _state["async_cache"] = cache
+
+
+def cached(ttl: int | None = None) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """Cache a function's return values in the shared default cache.
+
+    Works on both sync and async functions (``async def``), by
+    looking up :func:`get_ttl_cache` on every call, so replacing the
+    shared cache via :func:`set_ttl_cache` also changes where
+    already-decorated functions store their results.
+
+    Args:
+        ttl: The time-to-live, in seconds, applied to cached results.
+            Defaults to the cache's ``default_ttl``. Must be positive.
+
+    Returns:
+        A decorator that wraps a function with caching.
+
+    Raises:
+        ValueError: If ``ttl`` is not positive.
+
+    Example:
+        ```pycon
+        >>> from persista.cache import cached
+        >>> calls = []
+        >>> @cached(ttl=60)
+        ... def square(x):
+        ...     calls.append(x)
+        ...     return x * x
+        ...
+        >>> square(4)
+        16
+        >>> square(4)  # served from the cache, not re-computed
+        16
+        >>> calls
+        [4]
+
+        ```
+    """
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        if inspect.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                cache = get_ttl_cache()
+                key = make_key(func.__qualname__, args, kwargs)
+                result = cache.get(key)
+                if result is not None:
+                    return result
+                result = await func(*args, **kwargs)
+                cache.set(key, result, ttl=ttl)
+                return result
+
+            return async_wrapper
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> T:
+            cache = get_ttl_cache()
+            key = make_key(func.__qualname__, args, kwargs)
+            result = cache.get(key)
+            if result is not None:
+                return result
+            result = func(*args, **kwargs)
+            cache.set(key, result, ttl=ttl)
+            return result
+
+        return wrapper
+
+    return decorator
+
+
+def async_cached(
+    ttl: int | None = None,
+) -> Callable[[Callable[..., Awaitable[T]]], Callable[..., Awaitable[T]]]:
+    """Cache an async function's return values in the shared default
+    async cache.
+
+    Looks up :func:`get_async_ttl_cache` on every call, so replacing
+    the shared cache via :func:`set_async_ttl_cache` also changes
+    where already-decorated functions store their results.
+
+    Args:
+        ttl: The time-to-live, in seconds, applied to cached results.
+            Defaults to the cache's ``default_ttl``. Must be positive.
+
+    Returns:
+        A decorator that wraps an async function with caching.
+
+    Raises:
+        ValueError: If ``ttl`` is not positive.
+
+    Example:
+        ```pycon
+        >>> import asyncio
+        >>> from persista.cache import async_cached
+        >>> calls = []
+        >>> @async_cached(ttl=60)
+        ... async def square(x):
+        ...     calls.append(x)
+        ...     return x * x
+        ...
+        >>> async def main():
+        ...     print(await square(4))
+        ...     print(await square(4))  # served from the cache, not re-computed
+        ...
+        >>> asyncio.run(main())
+        16
+        16
+        >>> calls
+        [4]
+
+        ```
+    """
+
+    def decorator(func: Callable[..., Awaitable[T]]) -> Callable[..., Awaitable[T]]:
+        @functools.wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            cache = get_async_ttl_cache()
+            key = make_key(func.__qualname__, args, kwargs)
+            result = await cache.get(key)
+            if result is not None:
+                return result
+            result = await func(*args, **kwargs)
+            await cache.set(key, result, ttl=ttl)
+            return result
+
+        return wrapper
+
+    return decorator