fastapi-cachekit 0.1.0__py3-none-any.whl

fast_cache/backends/postgres.py

@@ -0,0 +1,230 @@
+import pickle
+from datetime import datetime, timezone, timedelta
+from typing import Any, Optional, Union
+from .backend import CacheBackend
+
+
+class PostgresBackend(CacheBackend):
+    """
+    PostgreSQL cache backend implementation.
+
+    Uses an UNLOGGED TABLE for performance and lazy expiration.
+    """
+
+    def __init__(
+        self,
+        dsn: str,
+        namespace: str = "fastapi",
+        min_size: int = 1,
+        max_size: int = 10,
+    ) -> None:
+        try:
+            from psycopg_pool import AsyncConnectionPool, ConnectionPool
+        except ImportError:
+            raise ImportError(
+                "PostgresBackend requires the 'psycopg[pool]' package. "
+                "Install it with: pip install fast-cache[postgres]"
+            )
+
+        self._namespace = namespace
+        self._table_name = f"{namespace}_cache_store"
+
+        # The pools are opened on creation and will auto-reopen if needed
+        # when using the context manager (`with/async with`).
+        self._sync_pool = ConnectionPool(
+            conninfo=dsn, min_size=min_size, max_size=max_size, open=True
+        )
+        self._async_pool = AsyncConnectionPool(
+            conninfo=dsn, min_size=min_size, max_size=max_size, open=False
+        )
+        self._create_unlogged_table_if_not_exists()
+
+    def _create_unlogged_table_if_not_exists(self):
+        """Create the cache table if it doesn't exist."""
+        # The index on expire_at is for efficient periodic cleanup jobs,
+        # though not used in the lazy-delete implementation.
+        create_sql = f"""
+        CREATE UNLOGGED TABLE IF NOT EXISTS {self._table_name} (
+            key TEXT PRIMARY KEY,
+            value BYTEA NOT NULL,
+            expire_at TIMESTAMPTZ
+        );
+        CREATE INDEX IF NOT EXISTS idx_{self._table_name}_expire_at
+        ON {self._table_name} (expire_at);
+        """
+        with self._sync_pool.connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute(create_sql)
+                conn.commit()
+
+    def _make_key(self, key: str) -> str:
+        return f"{self._namespace}:{key}"
+
+    def _is_expired(self, expire_at: Optional[datetime]) -> bool:
+        return expire_at is not None and expire_at < datetime.now(
+            timezone.utc
+        )
+
+    def set(
+        self, key: str, value: Any, expire: Optional[Union[int, timedelta]] = None
+    ) -> None:
+        expire_at = None
+        if expire:
+            delta = (
+                timedelta(seconds=expire)
+                if isinstance(expire, int)
+                else expire
+            )
+            expire_at = datetime.now(timezone.utc) + delta
+
+        with self._sync_pool.connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    f"""
+                    INSERT INTO {self._table_name} (key, value, expire_at)
+                    VALUES (%s, %s, %s)
+                    ON CONFLICT (key)
+                    DO UPDATE SET value = EXCLUDED.value,
+                                  expire_at = EXCLUDED.expire_at;
+                    """,
+                    (self._make_key(key), pickle.dumps(value), expire_at),
+                )
+                conn.commit()
+
+    def get(self, key: str) -> Optional[Any]:
+        with self._sync_pool.connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    f"SELECT value, expire_at FROM {self._table_name} WHERE key = %s;",
+                    (self._make_key(key),),
+                )
+                row = cur.fetchone()
+                if not row:
+                    return None
+                value, expire_at = row
+                if self._is_expired(expire_at):
+                    self.delete(key)  # Lazy delete
+                    return None
+                return pickle.loads(value)
+
+    def delete(self, key: str) -> None:
+        with self._sync_pool.connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    f"DELETE FROM {self._table_name} WHERE key = %s;",
+                    (self._make_key(key),),
+                )
+                conn.commit()
+
+    def has(self, key: str) -> bool:
+        with self._sync_pool.connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    f"SELECT expire_at FROM {self._table_name} WHERE key = %s;",
+                    (self._make_key(key),),
+                )
+                row = cur.fetchone()
+                if not row:
+                    return False
+                return not self._is_expired(row[0])
+
+    def clear(self) -> None:
+        """Clear all keys in the current namespace from the cache."""
+        with self._sync_pool.connection() as conn:
+            with conn.cursor() as cur:
+                # FIX: Use the dynamic table name
+                cur.execute(
+                    f"DELETE FROM {self._table_name} WHERE key LIKE %s;",
+                    (self._make_key("%"),),
+                )
+                conn.commit()
+
+    async def aset(
+        self, key: str, value: Any, expire: Optional[Union[int, timedelta]] = None
+    ) -> None:
+
+        if not self._async_pool._opened:
+            await self._async_pool.open()
+
+        expire_at = None
+        if expire:
+            delta = (
+                timedelta(seconds=expire)
+                if isinstance(expire, int)
+                else expire
+            )
+            expire_at = datetime.now(timezone.utc) + delta
+
+        async with self._async_pool.connection() as conn:
+            async with conn.cursor() as cur:
+                await cur.execute(
+                    f"""
+                    INSERT INTO {self._table_name} (key, value, expire_at)
+                    VALUES (%s, %s, %s)
+                    ON CONFLICT (key)
+                    DO UPDATE SET value = EXCLUDED.value,
+                                  expire_at = EXCLUDED.expire_at;
+                    """,
+                    (self._make_key(key), pickle.dumps(value), expire_at),
+                )
+                await conn.commit()
+
+    async def aget(self, key: str) -> Optional[Any]:
+        if not self._async_pool._opened:
+            await self._async_pool.open()
+        async with self._async_pool.connection() as conn:
+            async with conn.cursor() as cur:
+                await cur.execute(
+                    f"SELECT value, expire_at FROM {self._table_name} WHERE key = %s;",
+                    (self._make_key(key),),
+                )
+                row = await cur.fetchone()
+                if not row:
+                    return None
+                value, expire_at = row
+                if self._is_expired(expire_at):
+                    await self.adelete(key)  # Lazy delete
+                    return None
+                return pickle.loads(value)
+
+    async def adelete(self, key: str) -> None:
+        if not self._async_pool._opened:
+            await self._async_pool.open()
+        async with self._async_pool.connection() as conn:
+            async with conn.cursor() as cur:
+                await cur.execute(
+                    f"DELETE FROM {self._table_name} WHERE key = %s;",
+                    (self._make_key(key),),
+                )
+                await conn.commit()
+
+    async def ahas(self, key: str) -> bool:
+        if not self._async_pool._opened:
+            await self._async_pool.open()
+        async with self._async_pool.connection() as conn:
+            async with conn.cursor() as cur:
+                await cur.execute(
+                    f"SELECT expire_at FROM {self._table_name} WHERE key = %s;",
+                    (self._make_key(key),),
+                )
+                row = await cur.fetchone()
+                if not row:
+                    return False
+                return not self._is_expired(row[0])
+
+    async def aclear(self) -> None:
+        """Asynchronously clear all keys in the current namespace."""
+        if not self._async_pool._opened:
+            await self._async_pool.open()
+        async with self._async_pool.connection() as conn:
+            async with conn.cursor() as cur:
+                # FIX: Use the dynamic table name
+                await cur.execute(
+                    f"DELETE FROM {self._table_name} WHERE key LIKE %s;",
+                    (self._make_key("%"),),
+                )
+                await conn.commit()
+
+    async def close(self) -> None:
+        self._sync_pool.close()
+        await self._async_pool.close()

fast_cache/backends/redis.py

@@ -0,0 +1,257 @@
+import asyncio
+import inspect
+from typing import Any, Optional, Union
+from datetime import timedelta
+import pickle
+
+from .backend import CacheBackend
+
+
+class RedisBackend(CacheBackend):
+    """
+    Redis cache backend implementation with namespace support.
+
+    Attributes:
+        _namespace (str): Namespace prefix for all keys.
+        _sync_pool (redis.ConnectionPool): Synchronous Redis connection pool.
+        _async_pool (aioredis.ConnectionPool): Asynchronous Redis connection pool.
+        _sync_client (redis.Redis): Synchronous Redis client.
+        _async_client (aioredis.Redis): Asynchronous Redis client.
+    """
+
+    def __init__(
+        self,
+        redis_url: str,
+        namespace: str = "fastapi-cache",
+        pool_size: int = 10,
+        max_connections: int = 20,
+    ) -> None:
+        """
+        Initialize Redis backend with connection URL and pool settings.
+
+        Args:
+            redis_url (str): Redis connection URL (e.g., "redis://localhost:6379/0").
+            namespace (str): Namespace prefix for all keys (default: "fastapi-cache").
+            pool_size (int): Minimum number of connections in the pool.
+            max_connections (int): Maximum number of connections in the pool.
+        """
+
+        try:
+            import redis.asyncio as aioredis
+            import redis
+        except ImportError:
+            raise ImportError(
+                "RedisBackend requires the 'redis' package. "
+                "Install it with: pip install fast-cache[redis]"
+            )
+
+        self._namespace = namespace
+        self._sync_pool = redis.ConnectionPool.from_url(
+            redis_url, max_connections=max_connections, decode_responses=False
+        )
+
+        self._async_pool = aioredis.ConnectionPool.from_url(
+            redis_url,
+            max_connections=max_connections,
+            decode_responses=False,
+            encoding="utf-8",
+        )
+
+        self._sync_client = redis.Redis(connection_pool=self._sync_pool)
+        self._async_client = aioredis.Redis(connection_pool=self._async_pool)
+
+    def _make_key(self, key: str) -> str:
+        """
+        Create a namespaced key.
+
+        Args:
+            key (str): The original key.
+
+        Returns:
+            str: The namespaced key.
+        """
+        return f"{self._namespace}:{key}"
+
+    async def _scan_keys(self, pattern: str = "*") -> list[str]:
+        """
+        Scan all keys in the namespace asynchronously.
+
+        Args:
+            pattern (str): Pattern to match keys (default: "*").
+
+        Returns:
+            List[str]: List of matching keys.
+        """
+        keys = []
+        cursor = 0
+        namespace_pattern = self._make_key(pattern)
+
+        while True:
+            cursor, batch = await self._async_client.scan(
+                cursor=cursor, match=namespace_pattern, count=100
+            )
+            keys.extend(batch)
+            if cursor == 0:
+                break
+        return keys
+
+    async def aget(self, key: str) -> Optional[Any]:
+        """
+        Asynchronously retrieve a value from the cache.
+
+        Args:
+            key (str): The key to retrieve.
+
+        Returns:
+            Optional[Any]: The cached value, or None if not found.
+        """
+        try:
+            result = await self._async_client.get(self._make_key(key))
+            return pickle.loads(result) if result else None
+        except Exception:
+            return None
+
+    def get(self, key: str) -> Optional[Any]:
+        """
+        Synchronously retrieve a value from the cache.
+
+        Args:
+            key (str): The key to retrieve.
+
+        Returns:
+            Optional[Any]: The cached value, or None if not found.
+        """
+        try:
+            result = self._sync_client.get(self._make_key(key))
+            return pickle.loads(result) if result else None
+        except Exception:
+            return None
+
+    async def aset(
+        self, key: str, value: Any, expire: Optional[Union[int, timedelta]] = None
+    ) -> None:
+        """
+        Asynchronously set a value in the cache.
+
+        Args:
+            key (str): The key under which to store the value.
+            value (Any): The value to store.
+            expire (Optional[Union[int, timedelta]]): Expiration time in seconds or as timedelta.
+        """
+        try:
+            ex = expire.total_seconds() if isinstance(expire, timedelta) else expire
+            await self._async_client.set(
+                self._make_key(key), pickle.dumps(value), ex=ex
+            )
+        except Exception:
+            pass
+
+    def set(
+        self, key: str, value: Any, expire: Optional[Union[int, timedelta]] = None
+    ) -> None:
+        """
+        Synchronously set a value in the cache.
+
+        Args:
+            key (str): The key under which to store the value.
+            value (Any): The value to store.
+            expire (Optional[Union[int, timedelta]]): Expiration time in seconds or as timedelta.
+        """
+        try:
+            ex = expire.total_seconds() if isinstance(expire, timedelta) else expire
+            self._sync_client.set(self._make_key(key), pickle.dumps(value), ex=ex)
+        except Exception:
+            pass
+
+    async def adelete(self, key: str) -> None:
+        """
+        Asynchronously delete a value from the cache.
+
+        Args:
+            key (str): The key to delete.
+        """
+        try:
+            await self._async_client.delete(self._make_key(key))
+        except Exception:
+            pass
+
+    def delete(self, key: str) -> None:
+        """
+        Synchronously delete a value from the cache.
+
+        Args:
+            key (str): The key to delete.
+        """
+        try:
+            self._sync_client.delete(self._make_key(key))
+        except Exception:
+            pass
+
+    async def aclear(self) -> None:
+        """
+        Asynchronously clear all values from the namespace.
+        """
+        try:
+            keys = await self._scan_keys()
+            if keys:
+                await self._async_client.delete(*keys)
+        except Exception:
+            pass
+
+    def clear(self) -> None:
+        """
+        Synchronously clear all values from the namespace.
+        """
+        try:
+            cursor = 0
+            namespace_pattern = self._make_key("*")
+
+            while True:
+                cursor, keys = self._sync_client.scan(
+                    cursor=cursor, match=namespace_pattern, count=100
+                )
+                if keys:
+                    self._sync_client.delete(*keys)
+                if cursor == 0:
+                    break
+        except Exception:
+            pass
+
+    async def ahas(self, key: str) -> bool:
+        """
+        Asynchronously check if a key exists in the cache.
+
+        Args:
+            key (str): The key to check.
+
+        Returns:
+            bool: True if the key exists, False otherwise.
+        """
+        try:
+            return await self._async_client.exists(self._make_key(key)) > 0
+        except Exception:
+            return False
+
+    def has(self, key: str) -> bool:
+        """
+        Synchronously check if a key exists in the cache.
+
+        Args:
+            key (str): The key to check.
+
+        Returns:
+            bool: True if the key exists, False otherwise.
+        """
+        try:
+            return self._sync_client.exists(self._make_key(key)) > 0
+        except Exception:
+            return False
+
+    async def close(self) -> None:
+        """
+        Close Redis connections and clean up pools.
+        """
+        await self._async_client.close()
+        await self._async_pool.disconnect()
+        self._sync_client.close()
+        self._sync_pool.disconnect()

fast_cache/integration.py

@@ -0,0 +1,199 @@
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from typing import Optional, Callable, Union, AsyncIterator, Any
+from datetime import timedelta
+import inspect
+from functools import wraps
+from .backends.backend import CacheBackend
+
+
+class FastAPICache:
+    """
+    FastAPI Cache Extension.
+
+    This class provides caching utilities for FastAPI applications, including
+    decorator-based caching and dependency-injection-based backend access.
+    """
+
+    def __init__(self) -> None:
+        """
+        Initialize the FastAPICache instance.
+        """
+        self._backend: Optional[CacheBackend] = None
+        self._app: Optional[FastAPI] = None
+        self._default_expire: Optional[Union[int, timedelta]] = None
+
+    def get_cache(self) -> CacheBackend:
+        """
+        Get the configured cache backend for dependency injection.
+
+        Returns:
+            CacheBackend: The configured cache backend instance.
+
+        Raises:
+            RuntimeError: If the cache is not initialized.
+        """
+        if self._backend is None:
+            raise RuntimeError("Cache not initialized. Call init_app first.")
+        return self._backend
+
+    def cached(
+        self,
+        expire: Optional[Union[int, timedelta]] = None,
+        key_builder: Optional[Callable[..., str]] = None,
+        namespace: Optional[str] = None,
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """
+        Decorator for caching function results.
+
+        Args:
+            expire (Optional[Union[int, timedelta]]): Expiration time in seconds or as a timedelta.
+            key_builder (Optional[Callable[..., str]]): Custom function to build the cache key.
+            namespace (Optional[str]): Optional namespace for the cache key.
+
+        Returns:
+            Callable: A decorator that caches the function result.
+        """
+
+        def decorator(func: Callable) -> Callable[..., Any]:
+            """
+            The actual decorator that wraps the function.
+
+            Args:
+                func (Callable): The function to be cached.
+
+            Returns:
+                Callable: The wrapped function with caching.
+            """
+            is_async = inspect.iscoroutinefunction(func)
+
+            def build_cache_key(*args, **kwargs) -> str:
+                """
+                Build the cache key for the function call.
+
+                Args:
+                    *args: Positional arguments for the function.
+                    **kwargs: Keyword arguments for the function.
+
+                Returns:
+                    str: The generated cache key.
+                """
+                if key_builder is not None:
+                    key = key_builder(*args, **kwargs)
+                else:
+                    # Default key building logic
+                    key = f"{func.__module__}:{func.__name__}:{str(args)}:{str(kwargs)}"
+
+                if namespace:
+                    key = f"{namespace}:{key}"
+
+                return key
+
+            @wraps(func)
+            async def async_wrapper(*args, **kwargs) -> Any:
+                """
+                Async wrapper for caching.
+
+                Args:
+                    *args: Positional arguments.
+                    **kwargs: Keyword arguments.
+
+                Returns:
+                    Any: The cached or computed result.
+                """
+                if not self._backend:
+                    return await func(*args, **kwargs)
+
+                # Skip cache if explicitly requested
+                if kwargs.pop("skip_cache", False):
+                    return await func(*args, **kwargs)
+
+                cache_key = build_cache_key(*args, **kwargs)
+
+                # Try to get from cache
+                cached_value = await self._backend.aget(cache_key)
+                if cached_value is not None:
+                    return cached_value
+
+                # Execute function and cache result
+                result = await func(*args, **kwargs)
+                await self._backend.aset(
+                    cache_key, result, expire=expire or self._default_expire
+                )
+                return result
+
+            @wraps(func)
+            def sync_wrapper(*args, **kwargs):
+                """
+                Sync wrapper for caching.
+
+                Args:
+                    *args: Positional arguments.
+                    **kwargs: Keyword arguments.
+
+                Returns:
+                    Any: The cached or computed result.
+                """
+                if not self._backend:
+                    return func(*args, **kwargs)
+
+                # Skip cache if explicitly requested
+                if kwargs.pop("skip_cache", False):
+                    return func(*args, **kwargs)
+
+                cache_key = build_cache_key(*args, **kwargs)
+
+                # Try to get from cache
+                cached_value = self._backend.get(cache_key)
+                if cached_value is not None:
+                    return cached_value
+
+                # Execute function and cache result
+                result = func(*args, **kwargs)
+                self._backend.set(
+                    cache_key, result, expire=expire or self._default_expire
+                )
+                return result
+
+            return async_wrapper if is_async else sync_wrapper
+
+        return decorator
+
+    @asynccontextmanager
+    async def lifespan_handler(self, app: FastAPI) -> AsyncIterator[None]:
+        """
+        Lifespan context manager for FastAPI.
+
+        This can be used as the `lifespan` argument to FastAPI to manage
+        cache lifecycle.
+
+        Args:
+            app (FastAPI): The FastAPI application instance.
+
+        Yields:
+            None
+        """
+        if not hasattr(app, "state"):
+            app.state = {}
+        app.state["cache"] = self
+        yield
+        self._backend = None
+        self._app = None
+
+    def init_app(
+        self,
+        app: FastAPI,
+        backend: CacheBackend,
+        default_expire: Optional[Union[int, timedelta]] = None,
+    ) -> None:
+        """
+        Initialize the cache extension.
+
+        Args:
+            app (FastAPI): FastAPI application instance.
+            backend (CacheBackend): Cache backend instance.
+            default_expire (Optional[Union[int, timedelta]]): Default expiration time for cached items.
+        """
+        self._backend = backend
+        self._app = app
+        self._default_expire = default_expire