fastapi-cachex 0.2.1__py3-none-any.whl

fastapi_cachex/__init__.py

@@ -0,0 +1,7 @@
+"""FastAPI-CacheX: A powerful and flexible caching extension for FastAPI."""
+
+from .cache import cache as cache
+from .dependencies import CacheBackend as CacheBackend
+from .dependencies import get_cache_backend as get_cache_backend
+from .proxy import BackendProxy as BackendProxy
+from .routes import add_routes as add_routes

fastapi_cachex/backends/__init__.py

@@ -0,0 +1,13 @@
+"""Cache backend implementations for FastAPI-CacheX."""
+
+from fastapi_cachex.backends.base import BaseCacheBackend
+from fastapi_cachex.backends.memcached import MemcachedBackend
+from fastapi_cachex.backends.memory import MemoryBackend
+from fastapi_cachex.backends.redis import AsyncRedisCacheBackend
+
+__all__ = [
+    "AsyncRedisCacheBackend",
+    "BaseCacheBackend",
+    "MemcachedBackend",
+    "MemoryBackend",
+]

fastapi_cachex/backends/base.py

@@ -0,0 +1,70 @@
+"""Base cache backend interface and abstract implementation."""
+
+from abc import ABC
+from abc import abstractmethod
+from typing import Any
+
+from fastapi_cachex.types import ETagContent
+
+
+class BaseCacheBackend(ABC):
+    """Base class for all cache backends."""
+
+    @abstractmethod
+    async def get(self, key: str) -> ETagContent | None:
+        """Retrieve a cached response."""
+
+    @abstractmethod
+    async def set(self, key: str, value: ETagContent, ttl: int | None = None) -> None:
+        """Store a response in the cache."""
+
+    @abstractmethod
+    async def delete(self, key: str) -> None:
+        """Remove a response from the cache."""
+
+    @abstractmethod
+    async def clear(self) -> None:
+        """Clear all cached responses."""
+
+    @abstractmethod
+    async def clear_path(self, path: str, include_params: bool = False) -> int:
+        """Clear cached responses for a specific path.
+
+        Args:
+            path: The path to clear cache for
+            include_params: Whether to clear all parameter variations of the path
+
+        Returns:
+            Number of cache entries cleared
+        """
+
+    @abstractmethod
+    async def clear_pattern(self, pattern: str) -> int:
+        """Clear cached responses matching a pattern.
+
+        Args:
+            pattern: A glob pattern to match cache keys against (e.g., "/users/*")
+
+        Returns:
+            Number of cache entries cleared
+        """
+
+    @abstractmethod
+    async def get_all_keys(self) -> list[str]:
+        """Get all cache keys in the backend.
+
+        Returns:
+            List of all cache keys currently stored in the backend
+        """
+
+    @abstractmethod
+    async def get_cache_data(self) -> dict[str, tuple[Any, float | None]]:
+        """Get all cache data with expiry information.
+
+        This method is primarily used for cache monitoring and statistics.
+        Returns cache keys mapped to tuples of (value, expiry_time).
+
+        Returns:
+            Dictionary mapping cache keys to (value, expiry) tuples.
+            Expiry is None if the item never expires.
+        """

fastapi_cachex/backends/memcached.py

@@ -0,0 +1,239 @@
+"""Memcached cache backend implementation."""
+
+import warnings
+
+from fastapi_cachex.backends.base import BaseCacheBackend
+from fastapi_cachex.exceptions import CacheXError
+from fastapi_cachex.types import ETagContent
+
+try:
+    import orjson as json
+
+except ImportError:  # pragma: no cover
+    import json  # type: ignore[no-redef]  # pragma: no cover
+
+# Default Memcached key prefix for fastapi-cachex
+DEFAULT_MEMCACHE_PREFIX = "fastapi_cachex:"
+
+
+class MemcachedBackend(BaseCacheBackend):
+    """Memcached backend implementation.
+
+    Note: This implementation uses synchronous pymemcache client but wraps it
+    in async methods. For blocking concerns, consider using aiomcache for
+    true async Memcached operations. Keys are namespaced with 'fastapi_cachex:'
+    by default to avoid conflicts with other applications.
+
+    Limitations:
+    - Pattern-based clearing (clear_pattern) is not supported by Memcached protocol
+    - Operations are wrapped to appear async but use blocking sync client internally
+    """
+
+    key_prefix: str
+
+    def __init__(
+        self,
+        servers: list[str],
+        key_prefix: str = DEFAULT_MEMCACHE_PREFIX,
+    ) -> None:
+        """Initialize the Memcached backend.
+
+        Args:
+            servers: List of Memcached servers in format ["host:port", ...]
+            key_prefix: Prefix for all cache keys (default: 'fastapi_cachex:')
+
+        Raises:
+            CacheXError: If pymemcache is not installed
+        """
+        try:
+            from pymemcache import HashClient
+        except ImportError:
+            msg = "pymemcache is not installed. Please install it with 'pip install pymemcache'"
+            raise CacheXError(msg)
+
+        self.client = HashClient(servers, connect_timeout=5, timeout=5)
+        self.key_prefix = key_prefix
+
+    def _make_key(self, key: str) -> str:
+        """Add prefix to cache key."""
+        return f"{self.key_prefix}{key}"
+
+    async def get(self, key: str) -> ETagContent | None:
+        """Get value from cache.
+
+        Args:
+            key: Cache key to retrieve
+
+        Returns:
+            Optional[ETagContent]: Cached value with ETag if exists, None otherwise
+        """
+        prefixed_key = self._make_key(key)
+        value = self.client.get(prefixed_key)
+        if value is None:
+            return None
+
+        # Memcached stores data as bytes; deserialize from JSON
+        try:
+            data = json.loads(value.decode("utf-8"))
+            return ETagContent(
+                etag=data["etag"],
+                content=data["content"].encode()
+                if isinstance(data["content"], str)
+                else data["content"],
+            )
+        except (json.JSONDecodeError, KeyError, ValueError):
+            return None
+
+    async def set(self, key: str, value: ETagContent, ttl: int | None = None) -> None:
+        """Set value in cache.
+
+        Args:
+            key: Cache key
+            value: ETagContent to store
+            ttl: Time to live in seconds
+        """
+        prefixed_key = self._make_key(key)
+
+        # Prepare content for JSON serialization
+        if isinstance(value.content, bytes):
+            content = value.content.decode()
+        else:
+            content = value.content
+
+        serialized_data: str | bytes = json.dumps(
+            {
+                "etag": value.etag,
+                "content": content,
+            },
+        )
+
+        # orjson returns bytes, stdlib json returns str
+        serialized_bytes = (
+            serialized_data
+            if isinstance(serialized_data, bytes)
+            else serialized_data.encode("utf-8")
+        )
+
+        self.client.set(
+            prefixed_key,
+            serialized_bytes,
+            expire=ttl if ttl is not None else 0,
+        )
+
+    async def delete(self, key: str) -> None:
+        """Delete value from cache.
+
+        Args:
+            key: Cache key to delete
+        """
+        self.client.delete(self._make_key(key))
+
+    async def clear(self) -> None:
+        """Clear all values from cache.
+
+        Note: Memcached's flush_all affects the entire server.
+        Consider using clear_path() with your specific keys instead.
+        """
+        warnings.warn(
+            "Memcached.clear() flushes ALL cached data from the server, "
+            "affecting other applications. Consider using clear_path() instead "
+            "to selectively remove only this namespace's keys.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        self.client.flush_all()
+
+    async def clear_path(self, path: str, include_params: bool = False) -> int:
+        """Clear cached responses for a specific path.
+
+        Note: Memcached does not support pattern-based queries.
+        This method can only delete keys if the exact key is provided,
+        or will try to match keys in memory if include_params=True.
+        For better pattern support, consider using Redis backend.
+
+        Args:
+            path: The path to clear cache for
+            include_params: Currently unsupported (Memcached limitation)
+
+        Returns:
+            Number of cache entries cleared (0 or 1 for exact match only)
+        """
+        if include_params:
+            warnings.warn(
+                "Memcached backend does not support pattern-based key clearing. "
+                "Only exact key matches can be deleted. "
+                "The include_params option has no effect. "
+                "Consider using Redis backend for pattern support.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+
+        # Try to delete the prefixed key (exact match only)
+        prefixed_key = self._make_key(path)
+        try:
+            result = self.client.delete(prefixed_key, noreply=False)
+        except Exception:  # noqa: BLE001
+            return 0
+        else:
+            return 1 if result else 0
+
+    async def clear_pattern(self, pattern: str) -> int:  # noqa: ARG002
+        """Clear cached responses matching a pattern.
+
+        Memcached does not support pattern matching or key scanning.
+        This operation is not available.
+
+        Args:
+            pattern: A glob pattern (not supported by Memcached)
+
+        Returns:
+            Always 0, as pattern matching is not supported
+        """
+        warnings.warn(
+            "Memcached backend does not support pattern matching. "
+            "Pattern-based cache clearing is not available with Memcached. "
+            "Consider using Redis backend for pattern support, "
+            "or track keys manually in your application logic.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        return 0
+
+    async def get_all_keys(self) -> list[str]:
+        """Get all cache keys in the backend.
+
+        Note: Memcached does not support key scanning directly.
+        This returns an empty list as Memcached has no built-in way to enumerate keys.
+        For key enumeration, consider using Redis backend or tracking keys
+        manually in your application.
+
+        Returns:
+            Empty list (Memcached limitation)
+        """
+        warnings.warn(
+            "Memcached backend does not support key enumeration. "
+            "get_all_keys() returns an empty list. "
+            "Consider using Redis backend if you need cache monitoring, "
+            "or track keys manually in your application.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        return []
+
+    async def get_cache_data(self) -> dict[str, tuple[ETagContent, float | None]]:
+        """Get all cache data with expiry information.
+
+        Note: Memcached does not support key enumeration or pattern matching.
+        This method returns an empty dictionary.
+
+        Returns:
+            Empty dictionary (Memcached limitation)
+        """
+        warnings.warn(
+            "Memcached backend does not support key enumeration. "
+            "get_cache_data() returns an empty dictionary. "
+            "Consider using Redis backend if you need cache monitoring.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        return {}

fastapi_cachex/backends/memory.py

@@ -0,0 +1,198 @@
+"""In-memory cache backend implementation."""
+
+import asyncio
+import contextlib
+import fnmatch
+import time
+
+from fastapi_cachex.types import CacheItem
+from fastapi_cachex.types import ETagContent
+
+from .base import BaseCacheBackend
+
+# Cache keys are formatted as: method:host:path:query_params
+# Minimum parts required to extract path component
+_MIN_KEY_PARTS = 3
+# Maximum parts to split (method, host, path, query_params)
+_MAX_KEY_PARTS = 3
+
+
+class MemoryBackend(BaseCacheBackend):
+    """In-memory cache backend implementation.
+
+    Manages an in-memory cache dictionary with automatic expiration cleanup.
+    Cleanup runs in a background task that periodically removes expired entries.
+    Cleanup is lazily initialized on first cache operation to ensure proper
+    async context.
+    """
+
+    def __init__(self, cleanup_interval: int = 60) -> None:
+        """Initialize in-memory cache backend.
+
+        Args:
+            cleanup_interval: Interval in seconds between cleanup runs (default: 60)
+        """
+        self.cache: dict[str, CacheItem] = {}
+        self.lock = asyncio.Lock()
+        self.cleanup_interval = cleanup_interval
+        self._cleanup_task: asyncio.Task[None] | None = None
+
+    def _ensure_cleanup_started(self) -> None:
+        """Ensure cleanup task is started in proper async context."""
+        if self._cleanup_task is None or self._cleanup_task.done():
+            with contextlib.suppress(RuntimeError):
+                # No event loop yet; will be created on first async operation
+                self._cleanup_task = asyncio.create_task(self._cleanup_task_impl())
+
+    def start_cleanup(self) -> None:
+        """Start the cleanup task if it's not already running.
+
+        Cleanup is lazily started to ensure it's created in proper async context.
+        """
+        self._ensure_cleanup_started()
+
+    def stop_cleanup(self) -> None:
+        """Stop the cleanup task if it's running."""
+        if self._cleanup_task is not None:
+            self._cleanup_task.cancel()
+            self._cleanup_task = None
+
+    async def get(self, key: str) -> ETagContent | None:
+        """Retrieve a cached response.
+
+        Expired entries are skipped and return None.
+        Ensures cleanup task is started.
+        """
+        self._ensure_cleanup_started()
+
+        async with self.lock:
+            cached_item = self.cache.get(key)
+            if cached_item:
+                if cached_item.expiry is None or cached_item.expiry > time.time():
+                    return cached_item.value
+                # Entry has expired; clean it up
+                del self.cache[key]
+                return None
+            return None
+
+    async def set(self, key: str, value: ETagContent, ttl: int | None = None) -> None:
+        """Store a response in the cache.
+
+        Args:
+            key: Cache key
+            value: Content to cache
+            ttl: Time to live in seconds (None = never expires)
+        """
+        async with self.lock:
+            expiry = time.time() + ttl if ttl is not None else None
+            self.cache[key] = CacheItem(value=value, expiry=expiry)
+
+    async def delete(self, key: str) -> None:
+        """Remove a response from the cache."""
+        async with self.lock:
+            self.cache.pop(key, None)
+
+    async def clear(self) -> None:
+        """Clear all cached responses."""
+        async with self.lock:
+            self.cache.clear()
+
+    async def clear_path(self, path: str, include_params: bool = False) -> int:
+        """Clear cached responses for a specific path.
+
+        Parses cache keys to extract the path component and matches against
+        the provided path.
+
+        Args:
+            path: The path to clear cache for
+            include_params: If True, clear all variations including query params
+                           If False, only clear exact path (no query params)
+
+        Returns:
+            Number of cache entries cleared
+        """
+        cleared_count = 0
+        async with self.lock:
+            keys_to_delete = []
+            for key in self.cache:
+                # Keys are formatted as: method:host:path:query_params
+                parts = key.split(":", _MAX_KEY_PARTS)
+                if len(parts) >= _MIN_KEY_PARTS:
+                    cache_path = parts[2]
+                    has_params = len(parts) > _MIN_KEY_PARTS
+                    if cache_path == path and (include_params or not has_params):
+                        keys_to_delete.append(key)
+                        cleared_count += 1
+
+            for key in keys_to_delete:
+                del self.cache[key]
+
+        return cleared_count
+
+    async def clear_pattern(self, pattern: str) -> int:
+        """Clear cached responses matching a pattern.
+
+        Uses fnmatch for glob-style pattern matching against the path component
+        of cache keys.
+
+        Args:
+            pattern: A glob pattern to match against paths (e.g., "/users/*")
+
+        Returns:
+            Number of cache entries cleared
+        """
+        cleared_count = 0
+        async with self.lock:
+            keys_to_delete = []
+            for key in self.cache:
+                # Extract path component (method:host:path:query_params)
+                parts = key.split(":", _MAX_KEY_PARTS)
+                if len(parts) >= _MIN_KEY_PARTS:
+                    cache_path = parts[2]
+                    if fnmatch.fnmatch(cache_path, pattern):
+                        keys_to_delete.append(key)
+                        cleared_count += 1
+
+            for key in keys_to_delete:
+                del self.cache[key]
+
+        return cleared_count
+
+    async def get_all_keys(self) -> list[str]:
+        """Get all cache keys in the backend.
+
+        Returns:
+            List of all cache keys currently stored in the backend
+        """
+        async with self.lock:
+            return list(self.cache.keys())
+
+    async def get_cache_data(self) -> dict[str, tuple[ETagContent, float | None]]:
+        """Get all cache data with expiry information.
+
+        Returns:
+            Dictionary mapping cache keys to (ETagContent, expiry) tuples
+        """
+        async with self.lock:
+            return {key: (item.value, item.expiry) for key, item in self.cache.items()}
+
+    async def _cleanup_task_impl(self) -> None:
+        try:
+            while True:
+                await asyncio.sleep(self.cleanup_interval)
+                await self.cleanup()  # pragma: no cover
+        except asyncio.CancelledError:
+            # Handle task cancellation gracefully
+            pass
+
+    async def cleanup(self) -> None:
+        """Remove expired cache entries from memory."""
+        async with self.lock:
+            now = time.time()
+            expired_keys = [
+                k
+                for k, v in self.cache.items()
+                if v.expiry is not None and v.expiry <= now
+            ]
+            for key in expired_keys:
+                self.cache.pop(key, None)