swiftpy-framework 0.1.0__py3-none-any.whl

swiftpy/cache/driver.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from typing import Any
+
+logger = logging.getLogger("swiftpy.cache")
+
+_SENTINEL = object()
+
+
+class _LockWithRef:
+    __slots__ = ("lock", "refs")
+
+    def __init__(self) -> None:
+        self.lock = asyncio.Lock()
+        self.refs = 0
+
+
+class CacheDriver(ABC):
+    """
+    Abstract base class defining the contract for all SwiftPY cache drivers.
+    """
+
+    def __init__(self) -> None:
+        self._remember_locks: dict[str, _LockWithRef] = {}
+        self._meta_lock = asyncio.Lock()
+
+    @abstractmethod
+    async def get(self, key: str, default: Any = None) -> Any:
+        """
+        Retrieve an item from the cache by key.
+
+        If the item does not exist or has expired, return the default value.
+        """
+        ...
+
+    @abstractmethod
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        ttl: float | None = None,
+    ) -> bool:
+        """
+        Store an item in the cache with an optional TTL in seconds.
+        """
+        ...
+
+    @abstractmethod
+    async def forget(self, key: str) -> bool:
+        """
+        Remove an item from the cache.
+
+        Returns True if the item was removed, False if it did not exist.
+        """
+        ...
+
+    @abstractmethod
+    async def has(self, key: str) -> bool:
+        """
+        Determine if an item exists in the cache and has not expired.
+        """
+        ...
+
+    @abstractmethod
+    async def flush(self) -> bool:
+        """
+        Remove all items from the cache driver.
+        """
+        ...
+
+    async def pull(self, key: str, default: Any = None) -> Any:
+        """
+        Retrieve an item from the cache and delete it.
+        """
+        value = await self.get(key, _SENTINEL)
+        if value is _SENTINEL:
+            return default
+        await self.forget(key)
+        return value
+
+    async def add(
+        self,
+        key: str,
+        value: Any,
+        ttl: float | None = None,
+    ) -> bool:
+        """
+        Store an item in the cache if the key does not already exist.
+
+        Returns True if the item was added, False otherwise.
+        """
+        if await self.has(key):
+            return False
+        return await self.set(key, value, ttl)
+
+    async def increment(
+        self, key: str, value: int = 1, ttl: float | None = None
+    ) -> int:
+        """
+        Increment the value of an item in the cache.
+
+        If the key does not exist, it is initialized to the given value with optional TTL.
+        """
+        current = await self.get(key, _SENTINEL)
+        is_new = current is _SENTINEL
+        base = 0 if is_new else current
+        try:
+            new_value = int(base) + value
+        except (ValueError, TypeError):
+            raise TypeError(
+                f"Cannot increment non-numeric cached value of type {type(base).__name__}"
+            )
+        await self.set(key, new_value, ttl if is_new else None)
+        return new_value
+
+    async def decrement(
+        self, key: str, value: int = 1, ttl: float | None = None
+    ) -> int:
+        """
+        Decrement the value of an item in the cache.
+        """
+        return await self.increment(key, -value, ttl)
+
+    @asynccontextmanager
+    async def _acquire_key_lock(
+        self, key: str, lock_timeout: float = 10.0
+    ) -> AsyncIterator[bool]:
+        """Acquire an in-process per-key lock with reference-counted cleanup."""
+        async with self._meta_lock:
+            if key not in self._remember_locks:
+                self._remember_locks[key] = _LockWithRef()
+            entry = self._remember_locks[key]
+            entry.refs += 1
+
+        acquired = False
+        try:
+            if lock_timeout <= 0:
+                if not entry.lock.locked():
+                    await entry.lock.acquire()
+                    acquired = True
+            else:
+                try:
+                    await asyncio.wait_for(
+                        entry.lock.acquire(), timeout=float(lock_timeout)
+                    )
+                    acquired = True
+                except TimeoutError:
+                    acquired = False
+
+            yield acquired
+        finally:
+            if acquired:
+                entry.lock.release()
+            async with self._meta_lock:
+                entry.refs -= 1
+                if entry.refs <= 0:
+                    self._remember_locks.pop(key, None)
+
+    async def remember(
+        self,
+        key: str,
+        ttl: float | None,
+        callback: Callable[[], Any] | Callable[[], Awaitable[Any]],
+        lock_timeout: float = 10.0,
+    ) -> Any:
+        """
+        Get an item from the cache, or execute the given callback and store the result.
+
+        Includes stampede protection via per-key locking so that concurrent
+        requests for a missing key execute the callback exactly once.
+        If lock acquisition times out, computes the value without caching and logs a warning.
+        """
+        # Fast path check
+        cached = await self.get(key, _SENTINEL)
+        if cached is not _SENTINEL:
+            return cached
+
+        async with self._acquire_key_lock(key, lock_timeout=lock_timeout) as acquired:
+            if not acquired:
+                logger.warning(
+                    "Cache lock timed out waiting for key '%s'; computing value directly without caching",
+                    key,
+                )
+                if inspect.iscoroutinefunction(callback):
+                    return await callback()
+                res = callback()
+                return await res if inspect.isawaitable(res) else res
+
+            # Double-checked locking
+            cached = await self.get(key, _SENTINEL)
+            if cached is not _SENTINEL:
+                return cached
+
+            # Execute callback (supporting both synchronous and asynchronous callables)
+            if inspect.iscoroutinefunction(callback):
+                result = await callback()
+            else:
+                res = callback()
+                if inspect.isawaitable(res):
+                    result = await res
+                else:
+                    result = res
+
+            await self.set(key, result, ttl)
+            return result
+
+    async def close(self) -> None:
+        """
+        Close any underlying resources, connections, or pools held by the driver.
+        """

swiftpy/cache/drivers/memory.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+import asyncio
+import copy
+import itertools
+import time
+from collections import OrderedDict
+from collections.abc import Callable
+from typing import Any
+
+from swiftpy.cache.driver import _SENTINEL, CacheDriver
+
+
+class MemoryDriver(CacheDriver):
+    """
+    In-memory cache driver suitable for unit tests and local execution
+    without requiring an external Redis instance.
+    Includes LRU eviction when max_items is set and lazy expiry sweeping.
+    """
+
+    def __init__(
+        self,
+        prefix: str = "swiftpy_cache:",
+        default_ttl: float | None = None,
+        clock: Callable[[], float] = time.monotonic,
+        max_items: int | None = 1000,
+    ) -> None:
+        super().__init__()
+        self.prefix = prefix
+        self.default_ttl = default_ttl
+        self._clock = clock
+        self.max_items = max_items
+        self._storage: OrderedDict[str, tuple[Any, float | None]] = OrderedDict()
+        self._lock = asyncio.Lock()
+        self._sweep_cursor: int = 0
+
+    def _sweep_expired(self, max_keys: int = 20) -> None:
+        """Lazily sweep up to max_keys expired entries using a rolling cursor."""
+        total = len(self._storage)
+        if total == 0 or max_keys <= 0:
+            if total == 0:
+                self._sweep_cursor = 0
+            return
+
+        start = self._sweep_cursor % total
+        batch = list(itertools.islice(self._storage.items(), start, start + max_keys))
+        now = self._clock()
+        deleted = 0
+        for k, (_, exp) in batch:
+            if exp is not None and now >= exp:
+                self._storage.pop(k, None)
+                deleted += 1
+
+        new_total = len(self._storage)
+        if new_total == 0:
+            self._sweep_cursor = 0
+        else:
+            scanned_surviving = len(batch) - deleted
+            self._sweep_cursor = (start + scanned_surviving) % new_total
+
+    def _prefixed_key(self, key: str) -> str:
+        return f"{self.prefix}{key}"
+
+    async def get(self, key: str, default: Any = None) -> Any:
+        full_key = self._prefixed_key(key)
+        raw_val: Any = _SENTINEL
+        async with self._lock:
+            if full_key in self._storage:
+                value, expires_at = self._storage[full_key]
+                if expires_at is not None and self._clock() >= expires_at:
+                    del self._storage[full_key]
+                else:
+                    self._storage.move_to_end(full_key)
+                    raw_val = value
+
+        if raw_val is _SENTINEL:
+            return default
+        return copy.deepcopy(raw_val)
+
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        ttl: float | None = None,
+    ) -> bool:
+        full_key = self._prefixed_key(key)
+        effective_ttl = ttl if ttl is not None else self.default_ttl
+        val_to_store = copy.deepcopy(value)
+
+        async with self._lock:
+            self._sweep_expired()
+            if effective_ttl is not None and effective_ttl <= 0:
+                self._storage.pop(full_key, None)
+                return True
+
+            expires_at = (
+                self._clock() + effective_ttl if effective_ttl is not None else None
+            )
+            self._storage[full_key] = (val_to_store, expires_at)
+            self._storage.move_to_end(full_key)
+            if self.max_items is not None and len(self._storage) > self.max_items:
+                self._storage.popitem(last=False)
+            return True
+
+    async def forget(self, key: str) -> bool:
+        full_key = self._prefixed_key(key)
+        async with self._lock:
+            if full_key in self._storage:
+                del self._storage[full_key]
+                return True
+            return False
+
+    async def has(self, key: str) -> bool:
+        return await self.get(key, _SENTINEL) is not _SENTINEL
+
+    async def flush(self) -> bool:
+        async with self._lock:
+            if not self.prefix:
+                self._storage.clear()
+                self._sweep_cursor = 0
+            else:
+                keys_to_delete = [k for k in self._storage if k.startswith(self.prefix)]
+                for k in keys_to_delete:
+                    del self._storage[k]
+                if not self._storage:
+                    self._sweep_cursor = 0
+            return True
+
+    async def add(
+        self,
+        key: str,
+        value: Any,
+        ttl: float | None = None,
+    ) -> bool:
+        full_key = self._prefixed_key(key)
+        effective_ttl = ttl if ttl is not None else self.default_ttl
+        val_to_store = copy.deepcopy(value)
+
+        async with self._lock:
+            self._sweep_expired()
+            if full_key in self._storage:
+                _, expires_at = self._storage[full_key]
+                if expires_at is None or self._clock() < expires_at:
+                    return False
+                # Expired key can be replaced
+                del self._storage[full_key]
+
+            if effective_ttl is not None and effective_ttl <= 0:
+                return True
+
+            expires_at = (
+                self._clock() + effective_ttl if effective_ttl is not None else None
+            )
+            self._storage[full_key] = (val_to_store, expires_at)
+            self._storage.move_to_end(full_key)
+            if self.max_items is not None and len(self._storage) > self.max_items:
+                self._storage.popitem(last=False)
+            return True
+
+    async def increment(
+        self, key: str, value: int = 1, ttl: float | None = None
+    ) -> int:
+        full_key = self._prefixed_key(key)
+        effective_ttl = ttl if ttl is not None else self.default_ttl
+        async with self._lock:
+            self._sweep_expired()
+            current: Any = 0
+            expires_at: float | None = None
+
+            if full_key in self._storage:
+                stored_val, stored_exp = self._storage[full_key]
+                if stored_exp is None or self._clock() < stored_exp:
+                    current = stored_val
+                    expires_at = stored_exp
+                else:
+                    del self._storage[full_key]
+                    if effective_ttl is not None and effective_ttl > 0:
+                        expires_at = self._clock() + effective_ttl
+            else:
+                if effective_ttl is not None and effective_ttl > 0:
+                    expires_at = self._clock() + effective_ttl
+
+            try:
+                new_value = int(current) + value
+            except (ValueError, TypeError):
+                raise TypeError(
+                    f"Cannot increment non-numeric cached value of type {type(current).__name__}"
+                )
+
+            self._storage[full_key] = (new_value, expires_at)
+            self._storage.move_to_end(full_key)
+            if self.max_items is not None and len(self._storage) > self.max_items:
+                self._storage.popitem(last=False)
+            return new_value
+
+    async def close(self) -> None:
+        async with self._lock:
+            self._storage.clear()
+            self._sweep_cursor = 0