fastapi-cachex 0.2.12__tar.gz → 0.3.0__tar.gz

{fastapi_cachex-0.2.12 → fastapi_cachex-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-cachex
-Version: 0.2.12
+Version: 0.3.0
 Summary: A caching library for FastAPI with support for Cache-Control, ETag, and multiple backends.
 Keywords: fastapi,cache,etag,cache-control,redis,memcached,in-memory
 Author: allen0099
@@ -146,6 +146,44 @@ async def remove_cache(cache: CacheBackend):
     await cache.clear_pattern("/path/to/clear/*")  # Clear cache for a specific pattern
 ```
 
+### Application-Level Caching (Manual Get/Set)
+
+Beyond HTTP response caching via `@cache`, you can cache arbitrary JSON-serializable
+Python values directly in your business logic using `CacheManager`. It's a thin,
+namespaced wrapper around whichever backend is configured via `BackendProxy`.
+
+```python
+from fastapi_cachex import AppCache, CacheManager
+
+@app.get("/expensive")
+async def expensive_operation(cache: AppCache):
+    result = await cache.get("expensive:result")
+    if result is None:
+        result = perform_expensive_calculation()
+        await cache.set("expensive:result", result, ttl=300)
+    return result
+
+
+# Or instantiate directly, e.g. outside of a request:
+manager = CacheManager(key_prefix="myapp:", default_ttl=60)
+await manager.set("user:42", {"name": "Alice"})
+user = await manager.get("user:42")  # {"name": "Alice"}
+await manager.delete("user:42")
+await manager.clear_prefix()  # clear everything under "myapp:"
+```
+
+`CacheManager.get()` returns `None` (or a supplied `default=`) on a cache miss —
+it never raises for missing or corrupted entries. `CacheManager` keys live under
+their own `cache:`-prefixed namespace by default, separate from the HTTP route
+cache and OAuth state, so `clear()`/`clear_prefix()` never touch unrelated cache
+entries.
+
+**Note**: `clear()`/`clear_prefix()` are implemented via the backend's
+`get_all_keys()`. Since Memcached doesn't support key enumeration (see
+[Memcached limitations](#memcached)), these two methods are no-ops on a
+Memcached backend — `get()`/`set()`/`delete()`/`has()` work normally. Use
+Redis or the in-memory backend if you need bulk clearing.
+
 ## Backend Configuration
 
 FastAPI-CacheX supports multiple caching backends. You can easily switch between them using the `BackendProxy`.
@@ -166,6 +204,8 @@ This ensures that:
 
 All backends automatically namespace keys with a prefix (e.g., `fastapi_cachex:`) to avoid conflicts with other applications.
 
+`CacheManager` (see [Application-Level Caching](#application-level-caching-manual-getset)) uses a separate, simpler `cache:`-prefixed key namespace instead of this `|||`-separated format, since its keys aren't tied to HTTP requests.
+
 ### Cache Hit Behavior
 
 When a cached entry is valid (within TTL):

{fastapi_cachex-0.2.12 → fastapi_cachex-0.3.0}/README.md

@@ -110,6 +110,44 @@ async def remove_cache(cache: CacheBackend):
     await cache.clear_pattern("/path/to/clear/*")  # Clear cache for a specific pattern
 ```
 
+### Application-Level Caching (Manual Get/Set)
+
+Beyond HTTP response caching via `@cache`, you can cache arbitrary JSON-serializable
+Python values directly in your business logic using `CacheManager`. It's a thin,
+namespaced wrapper around whichever backend is configured via `BackendProxy`.
+
+```python
+from fastapi_cachex import AppCache, CacheManager
+
+@app.get("/expensive")
+async def expensive_operation(cache: AppCache):
+    result = await cache.get("expensive:result")
+    if result is None:
+        result = perform_expensive_calculation()
+        await cache.set("expensive:result", result, ttl=300)
+    return result
+
+
+# Or instantiate directly, e.g. outside of a request:
+manager = CacheManager(key_prefix="myapp:", default_ttl=60)
+await manager.set("user:42", {"name": "Alice"})
+user = await manager.get("user:42")  # {"name": "Alice"}
+await manager.delete("user:42")
+await manager.clear_prefix()  # clear everything under "myapp:"
+```
+
+`CacheManager.get()` returns `None` (or a supplied `default=`) on a cache miss —
+it never raises for missing or corrupted entries. `CacheManager` keys live under
+their own `cache:`-prefixed namespace by default, separate from the HTTP route
+cache and OAuth state, so `clear()`/`clear_prefix()` never touch unrelated cache
+entries.
+
+**Note**: `clear()`/`clear_prefix()` are implemented via the backend's
+`get_all_keys()`. Since Memcached doesn't support key enumeration (see
+[Memcached limitations](#memcached)), these two methods are no-ops on a
+Memcached backend — `get()`/`set()`/`delete()`/`has()` work normally. Use
+Redis or the in-memory backend if you need bulk clearing.
+
 ## Backend Configuration
 
 FastAPI-CacheX supports multiple caching backends. You can easily switch between them using the `BackendProxy`.
@@ -130,6 +168,8 @@ This ensures that:
 
 All backends automatically namespace keys with a prefix (e.g., `fastapi_cachex:`) to avoid conflicts with other applications.
 
+`CacheManager` (see [Application-Level Caching](#application-level-caching-manual-getset)) uses a separate, simpler `cache:`-prefixed key namespace instead of this `|||`-separated format, since its keys aren't tied to HTTP requests.
+
 ### Cache Hit Behavior
 
 When a cached entry is valid (within TTL):

{fastapi_cachex-0.2.12 → fastapi_cachex-0.3.0}/fastapi_cachex/__init__.py

@@ -4,8 +4,12 @@ import logging
 
 from .cache import cache as cache
 from .cache import default_key_builder as default_key_builder
+from .dependencies import AppCache as AppCache
 from .dependencies import CacheBackend as CacheBackend
+from .dependencies import get_app_cache as get_app_cache
 from .dependencies import get_cache_backend as get_cache_backend
+from .manager import CacheManager as CacheManager
+from .manager_proxy import CacheManagerProxy as CacheManagerProxy
 from .proxy import BackendProxy as BackendProxy
 from .routes import add_routes as add_routes
 from .session import Session as Session
@@ -38,9 +42,12 @@ _package_logger.addHandler(
 )  # Attach a NullHandler to avoid "No handler found" warnings in user applications.
 
 __all__ = [
+    "AppCache",
     "BackendProxy",
     "CacheBackend",
     "CacheKeyBuilder",
+    "CacheManager",
+    "CacheManagerProxy",
     "InvalidStateError",
     "Session",
     "SessionConfig",
@@ -62,6 +69,7 @@ __all__ = [
     "add_routes",
     "cache",
     "default_key_builder",
+    "get_app_cache",
     "get_cache_backend",
     "get_optional_session",
     "get_session",

{fastapi_cachex-0.2.12 → fastapi_cachex-0.3.0}/fastapi_cachex/backends/base.py

@@ -4,18 +4,18 @@ from abc import ABC
 from abc import abstractmethod
 from typing import Any
 
-from fastapi_cachex.types import ETagContent
+from fastapi_cachex.types import CacheEntry
 
 
 class BaseCacheBackend(ABC):
     """Base class for all cache backends."""
 
     @abstractmethod
-    async def get(self, key: str) -> ETagContent | None:
+    async def get(self, key: str) -> CacheEntry | None:
         """Retrieve a cached response."""
 
     @abstractmethod
-    async def set(self, key: str, value: ETagContent, ttl: int | None = None) -> None:
+    async def set(self, key: str, value: CacheEntry, ttl: int | None = None) -> None:
         """Store a response in the cache."""
 
     @abstractmethod

{fastapi_cachex-0.2.12 → fastapi_cachex-0.3.0}/fastapi_cachex/backends/memcached.py

@@ -5,7 +5,7 @@ import logging
 import warnings
 
 from fastapi_cachex.exceptions import CacheXError
-from fastapi_cachex.types import ETagContent
+from fastapi_cachex.types import CacheEntry
 
 from .base import BaseCacheBackend
 
@@ -63,18 +63,17 @@ class MemcachedBackend(BaseCacheBackend):
         """Add prefix to cache key."""
         return f"{self.key_prefix}{key}"
 
-    async def get(self, key: str) -> ETagContent | None:
+    async def get(self, key: str) -> CacheEntry | None:
         """Get value from cache.
 
         Args:
             key: Cache key to retrieve
 
         Returns:
-            Optional[ETagContent]: Cached value with ETag if exists, None otherwise
+            Cached entry if found, None otherwise
         """
         prefixed_key = self._make_key(key)
-        loop = asyncio.get_running_loop()
-        value = await loop.run_in_executor(None, self.client.get, prefixed_key)
+        value = await asyncio.to_thread(self.client.get, prefixed_key)
         if value is None:
             logger.debug("Memcached MISS; key=%s", key)
             return None
@@ -83,8 +82,8 @@ class MemcachedBackend(BaseCacheBackend):
         try:
             data = json.loads(value)
             logger.debug("Memcached HIT; key=%s", key)
-            return ETagContent(
-                etag=data["etag"],
+            return CacheEntry(
+                fingerprint=data["fingerprint"],
                 content=data["content"].encode("latin-1"),
                 media_type=data.get("media_type"),
             )
@@ -92,12 +91,12 @@ class MemcachedBackend(BaseCacheBackend):
             logger.debug("Memcached DESERIALIZE ERROR; key=%s", key)
             return None
 
-    async def set(self, key: str, value: ETagContent, ttl: int | None = None) -> None:
+    async def set(self, key: str, value: CacheEntry, ttl: int | None = None) -> None:
         """Set value in cache.
 
         Args:
             key: Cache key
-            value: ETagContent to store
+            value: CacheEntry instance to store
             ttl: Time to live in seconds
         """
         prefixed_key = self._make_key(key)
@@ -107,7 +106,7 @@ class MemcachedBackend(BaseCacheBackend):
 
         serialized_data: str | bytes = json.dumps(
             {
-                "etag": value.etag,
+                "fingerprint": value.fingerprint,
                 "content": content,
                 "media_type": value.media_type,
             },
@@ -121,11 +120,7 @@ class MemcachedBackend(BaseCacheBackend):
         )
 
         expire = ttl if ttl is not None else 0
-        loop = asyncio.get_running_loop()
-        await loop.run_in_executor(
-            None,
-            lambda: self.client.set(prefixed_key, serialized_bytes, expire=expire),
-        )
+        await asyncio.to_thread(self.client.set, prefixed_key, serialized_bytes, expire)
         logger.debug("Memcached SET; key=%s ttl=%s", key, ttl)
 
     async def delete(self, key: str) -> None:
@@ -135,8 +130,7 @@ class MemcachedBackend(BaseCacheBackend):
             key: Cache key to delete
         """
         prefixed = self._make_key(key)
-        loop = asyncio.get_running_loop()
-        await loop.run_in_executor(None, self.client.delete, prefixed)
+        await asyncio.to_thread(self.client.delete, prefixed)
         logger.debug("Memcached DELETE; key=%s", key)
 
     async def clear(self) -> None:
@@ -152,8 +146,7 @@ class MemcachedBackend(BaseCacheBackend):
             RuntimeWarning,
             stacklevel=2,
         )
-        loop = asyncio.get_running_loop()
-        await loop.run_in_executor(None, self.client.flush_all)
+        await asyncio.to_thread(self.client.flush_all)
         logger.debug("Memcached CLEAR; flush_all issued")
 
     async def clear_path(self, path: str, include_params: bool = False) -> int:
@@ -183,12 +176,8 @@ class MemcachedBackend(BaseCacheBackend):
 
         # Try to delete the prefixed key (exact match only)
         prefixed_key = self._make_key(path)
-        loop = asyncio.get_running_loop()
         try:
-            result = await loop.run_in_executor(
-                None,
-                lambda: self.client.delete(prefixed_key, noreply=False),
-            )
+            result = await asyncio.to_thread(self.client.delete, prefixed_key, False)
         except Exception:  # noqa: BLE001
             return 0
         else:
@@ -245,7 +234,7 @@ class MemcachedBackend(BaseCacheBackend):
         logger.debug("Memcached GET_ALL_KEYS unsupported; returning empty list")
         return []
 
-    async def get_cache_data(self) -> dict[str, tuple[ETagContent, float | None]]:
+    async def get_cache_data(self) -> dict[str, tuple[CacheEntry, float | None]]:
         """Get all cache data with expiry information.
 
         Note: Memcached does not support key enumeration or pattern matching.

{fastapi_cachex-0.2.12 → fastapi_cachex-0.3.0}/fastapi_cachex/backends/memory.py

@@ -6,8 +6,8 @@ import logging
 import time
 
 from fastapi_cachex.types import CACHE_KEY_SEPARATOR
+from fastapi_cachex.types import CacheEntry
 from fastapi_cachex.types import CacheItem
-from fastapi_cachex.types import ETagContent
 
 from .base import BaseCacheBackend
 
@@ -68,7 +68,7 @@ class MemoryBackend(BaseCacheBackend):
             self._cleanup_task = None
             logger.debug("Stopped memory backend cleanup task")
 
-    async def get(self, key: str) -> ETagContent | None:
+    async def get(self, key: str) -> CacheEntry | None:
         """Retrieve a cached response.
 
         Expired entries are skipped and return None.
@@ -89,7 +89,7 @@ class MemoryBackend(BaseCacheBackend):
             logger.debug("Memory cache MISS; key=%s", key)
             return None
 
-    async def set(self, key: str, value: ETagContent, ttl: int | None = None) -> None:
+    async def set(self, key: str, value: CacheEntry, ttl: int | None = None) -> None:
         """Store a response in the cache.
 
         Args:
@@ -201,11 +201,11 @@ class MemoryBackend(BaseCacheBackend):
         async with self.lock:
             return list(self.cache.keys())
 
-    async def get_cache_data(self) -> dict[str, tuple[ETagContent, float | None]]:
+    async def get_cache_data(self) -> dict[str, tuple[CacheEntry, float | None]]:
         """Get all cache data with expiry information.
 
         Returns:
-            Dictionary mapping cache keys to (ETagContent, expiry) tuples
+            Dictionary mapping cache keys to (CacheEntry, expiry) tuples
         """
         async with self.lock:
             return {key: (item.value, item.expiry) for key, item in self.cache.items()}

{fastapi_cachex-0.2.12 → fastapi_cachex-0.3.0}/fastapi_cachex/backends/redis.py

@@ -11,7 +11,7 @@ from fastapi_cachex.backends.config import (
 from fastapi_cachex.backends.config import RedisConfig
 from fastapi_cachex.exceptions import CacheXError
 from fastapi_cachex.types import CACHE_KEY_SEPARATOR
-from fastapi_cachex.types import ETagContent
+from fastapi_cachex.types import CacheEntry
 
 from .base import BaseCacheBackend
 
@@ -125,14 +125,14 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         """Add prefix to cache key."""
         return f"{self.key_prefix}{key}"
 
-    def _serialize(self, value: ETagContent) -> str:
-        """Serialize ETagContent to JSON string."""
+    def _serialize(self, value: CacheEntry) -> str:
+        """Serialize CacheEntry to JSON string."""
         # Use latin-1 to round-trip arbitrary bytes through JSON/UTF-8 Redis storage
         content = value.content.decode("latin-1")
 
         serialized: str | bytes = json.dumps(
             {
-                "etag": value.etag,
+                "fingerprint": value.fingerprint,
                 "content": content,
                 "media_type": value.media_type,
             },
@@ -141,8 +141,8 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         # orjson returns bytes, stdlib json returns str
         return serialized.decode() if isinstance(serialized, bytes) else serialized
 
-    def _deserialize(self, value: str | None) -> ETagContent | None:
-        """Deserialize JSON string to ETagContent.
+    def _deserialize(self, value: str | None) -> CacheEntry | None:
+        """Deserialize JSON string to CacheEntry.
 
         Converts string content back to bytes to maintain consistency with
         other backends and standard Response.body type (bytes).
@@ -152,22 +152,22 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         try:
             data = json.loads(value)
             logger.debug("Content type in JSON: %s", type(data["content"]))
-            return ETagContent(
-                etag=data["etag"],
+            return CacheEntry(
+                fingerprint=data["fingerprint"],
                 content=data["content"].encode("latin-1"),
                 media_type=data.get("media_type"),
             )
         except (json.JSONDecodeError, KeyError, AttributeError):
             return None
 
-    async def get(self, key: str) -> ETagContent | None:
+    async def get(self, key: str) -> CacheEntry | None:
         """Retrieve a cached response."""
         result = await self.client.get(self._make_key(key))
         value = self._deserialize(result)
         logger.debug("Redis %s; key=%s", "HIT" if value else "MISS", key)
         return value
 
-    async def set(self, key: str, value: ETagContent, ttl: int | None = None) -> None:
+    async def set(self, key: str, value: CacheEntry, ttl: int | None = None) -> None:
         """Store a response in the cache."""
         serialized = self._serialize(value)
         prefixed_key = self._make_key(key)
@@ -327,7 +327,7 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         """Get all cache keys in the backend.
 
         Returns:
-            List of all cache keys currently stored in the backend
+            List of logical cache keys (without the backend key prefix)
         """
         pattern = f"{self.key_prefix}*"
         cursor = 0
@@ -346,34 +346,34 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
             if cursor == 0:
                 break
 
-        logger.debug("Redis GET_ALL_KEYS; count=%s", len(all_keys))
-        return all_keys
+        logical_keys = [k.removeprefix(self.key_prefix) for k in all_keys]
+        logger.debug("Redis GET_ALL_KEYS; count=%s", len(logical_keys))
+        return logical_keys
 
-    async def get_cache_data(self) -> dict[str, tuple[ETagContent, float | None]]:
+    async def get_cache_data(self) -> dict[str, tuple[CacheEntry, float | None]]:
         """Get all cache data with expiry information.
 
         Returns:
-            Dictionary mapping cache keys to (ETagContent, expiry) tuples.
+            Dictionary mapping cache keys to (CacheEntry, expiry) tuples.
             Note: Redis stores TTL but not absolute expiry time, so this
             returns None for expiry (no expiry tracking in Redis backend).
         """
         all_keys = await self.get_all_keys()
-        cache_data: dict[str, tuple[ETagContent, float | None]] = {}
+        cache_data: dict[str, tuple[CacheEntry, float | None]] = {}
 
         if not all_keys:
             return cache_data
 
         # Fetch all values in a single pipeline round-trip instead of N+1 GETs
         pipe = self.client.pipeline()
-        for prefixed_key in all_keys:
-            pipe.get(prefixed_key)
+        for key in all_keys:
+            pipe.get(self._make_key(key))
         raw_values: list[str | None] = await pipe.execute()
 
-        for prefixed_key, raw in zip(all_keys, raw_values, strict=False):
-            original_key = prefixed_key.removeprefix(self.key_prefix)
+        for key, raw in zip(all_keys, raw_values, strict=False):
             value = self._deserialize(raw)
             if value is not None:
-                cache_data[original_key] = (value, None)
+                cache_data[key] = (value, None)
 
         logger.debug("Redis GET_CACHE_DATA; keys=%s", len(cache_data))
         return cache_data

{fastapi_cachex-0.2.12 → fastapi_cachex-0.3.0}/fastapi_cachex/cache.py

@@ -25,8 +25,8 @@ from .exceptions import CacheXError
 from .exceptions import RequestNotFoundError
 from .proxy import BackendProxy
 from .types import CACHE_KEY_SEPARATOR
+from .types import CacheEntry
 from .types import CacheKeyBuilder
-from .types import ETagContent
 
 if TYPE_CHECKING:
     from fastapi.routing import APIRoute
@@ -85,6 +85,11 @@ class CacheControl:
         return ", ".join(self.directives)
 
 
+def _get_response_body(response: Response) -> bytes | None:
+    """Return response body bytes, or None for streaming/file responses."""
+    return getattr(response, "body", None)
+
+
 async def get_response(
     __func: HandlerCallable,
     __request: Request,
@@ -151,10 +156,16 @@ def cache(
     """
 
     def decorator(func: HandlerCallable) -> AsyncResponseCallable:
-        # Validate stale parameters eagerly at decoration time
+        # Validate parameters eagerly at decoration time
         if stale is not None and stale_ttl is None:
             msg = "stale_ttl must be set if stale is used"
             raise CacheXError(msg)
+        if stale_ttl is not None and stale is None:
+            msg = "stale must be set if stale_ttl is used"
+            raise CacheXError(msg)
+        if public and private:
+            msg = "public and private are mutually exclusive"
+            raise CacheXError(msg)
 
         # Analyze the original function's signature
         sig: Signature = inspect.signature(func)
@@ -266,7 +277,7 @@ def cache(
                 if no_cache:
                     # Get fresh response first if using no-cache
                     current_response = await get_response(func, req, *args, **kwargs)
-                    current_body = getattr(current_response, "body", None)
+                    current_body = _get_response_body(current_response)
                     if current_body is None:
                         # StreamingResponse/FileResponse — cannot compute ETag; serve as-is
                         current_response.headers["Cache-Control"] = cache_control
@@ -287,9 +298,7 @@ def cache(
                         )
 
                 # Compare with cached ETag - if match, return 304
-                elif (
-                    cached_data and client_etag == cached_data.etag
-                ):  # pragma: no branch
+                elif cached_data and client_etag == cached_data.fingerprint:
                     # Cache hit with matching ETag: return 304 Not Modified
                     logger.debug(
                         "304 Not Modified (cached ETag match); key=%s", cache_key
@@ -297,7 +306,7 @@ def cache(
                     return Response(
                         status_code=HTTP_304_NOT_MODIFIED,
                         headers={
-                            "ETag": cached_data.etag,
+                            "ETag": cached_data.fingerprint,
                             "Cache-Control": cache_control,
                         },
                     )
@@ -313,7 +322,7 @@ def cache(
                     status_code=200,
                     media_type=cached_data.media_type,
                     headers={
-                        "ETag": cached_data.etag,
+                        "ETag": cached_data.fingerprint,
                         "Cache-Control": cache_control,
                     },
                 )
@@ -321,7 +330,7 @@ def cache(
             if not current_response or not current_etag:
                 # Retrieve the current response if not already done
                 current_response = await get_response(func, req, *args, **kwargs)
-                current_body = getattr(current_response, "body", None)
+                current_body = _get_response_body(current_response)
                 if current_body is None:
                     # StreamingResponse/FileResponse — cannot compute ETag; serve as-is
                     current_response.headers["Cache-Control"] = cache_control
@@ -333,17 +342,15 @@ def cache(
             current_response.headers["ETag"] = current_etag
 
             # Update cache if needed
-            if not cached_data or cached_data.etag != current_etag:
-                if current_body is None:  # pragma: no cover - guaranteed by earlier guards
-                    msg = "Unexpected state: response body unavailable after ETag computation"
-                    raise CacheXError(msg)
+            if not cached_data or cached_data.fingerprint != current_etag:
+                assert current_body is not None  # guaranteed by early-return guards above
                 # Store in cache if data changed
                 await cache_backend.set(
                     cache_key,
-                    ETagContent(
-                        current_etag,
-                        current_body,
-                        current_response.media_type,
+                    CacheEntry(
+                        fingerprint=current_etag,
+                        content=current_body,
+                        media_type=current_response.media_type,
                     ),
                     ttl=ttl,
                 )

fastapi_cachex-0.3.0/fastapi_cachex/dependencies.py

@@ -0,0 +1,37 @@
+"""FastAPI dependency injection utilities for cache control."""
+
+from typing import Annotated
+
+from fastapi import Depends
+
+from .backends.base import BaseCacheBackend
+from .exceptions import BackendNotFoundError
+from .manager import CacheManager
+from .manager_proxy import CacheManagerProxy
+from .proxy import BackendProxy
+
+
+def get_cache_backend() -> BaseCacheBackend:
+    """Dependency to get the current cache backend instance."""
+    return BackendProxy.get()
+
+
+CacheBackend = Annotated[BaseCacheBackend, Depends(get_cache_backend)]
+
+
+def get_app_cache() -> CacheManager:
+    """Dependency to get the application CacheManager instance.
+
+    Lazily creates and registers a default CacheManager (backed by
+    BackendProxy) the first time it's requested, unless one was already
+    set via CacheManagerProxy.set(...).
+    """
+    try:
+        return CacheManagerProxy.get()
+    except BackendNotFoundError:
+        manager = CacheManager()
+        CacheManagerProxy.set(manager)
+        return manager
+
+
+AppCache = Annotated[CacheManager, Depends(get_app_cache)]

fastapi_cachex-0.3.0/fastapi_cachex/manager.py

@@ -0,0 +1,147 @@
+"""Generic application-level cache manager for FastAPI-CacheX."""
+
+import hashlib
+import json
+import logging
+from typing import Any
+
+from .backends.base import BaseCacheBackend
+from .proxy import BackendProxy
+from .types import CacheEntry
+
+logger = logging.getLogger(__name__)
+
+_DECODE_ERRORS = (AttributeError, UnicodeDecodeError, json.JSONDecodeError)
+
+
+class CacheManager:
+    """Provides convenient get/set/delete access to the configured cache backend.
+
+    Unlike the ``@cache`` decorator (which caches HTTP response bodies) or
+    ``StateManager``/``SessionManager`` (which manage OAuth state and sessions),
+    ``CacheManager`` is a thin, JSON-serializing wrapper for caching arbitrary
+    application values under a dedicated key namespace.
+    """
+
+    def __init__(
+        self,
+        backend: BaseCacheBackend | None = None,
+        key_prefix: str = "cache:",
+        default_ttl: int | None = None,
+    ) -> None:
+        """Initialize CacheManager.
+
+        Args:
+            backend: Cache backend instance. If None, uses BackendProxy.get().
+            key_prefix: Prefix prepended to all logical keys in the cache backend.
+            default_ttl: Default TTL (seconds) applied when set() is called
+                without an explicit ttl. None means no expiry by default.
+        """
+        self.backend = backend if backend is not None else BackendProxy.get()
+        self.key_prefix = key_prefix
+        self.default_ttl = default_ttl
+
+    def _cache_key(self, key: str) -> str:
+        return f"{self.key_prefix}{key}"
+
+    async def get(self, key: str, default: Any = None) -> Any:
+        """Retrieve and JSON-decode a cached value.
+
+        Args:
+            key: Logical cache key (without the manager's prefix).
+            default: Value returned when the key is missing, expired, or the
+                stored content cannot be decoded.
+
+        Returns:
+            The cached value, or ``default`` on a miss or decode failure.
+        """
+        cached = await self.backend.get(self._cache_key(key))
+        if cached is None:
+            return default
+
+        try:
+            json_content = cached.content.decode("utf-8")
+            return json.loads(json_content)
+        except _DECODE_ERRORS:
+            logger.warning("Failed to decode cached value; key=%s", key)
+            return default
+
+    async def set(self, key: str, value: Any, ttl: int | None = None) -> None:
+        """JSON-encode and store a value in the cache.
+
+        Args:
+            key: Logical cache key (without the manager's prefix).
+            value: A JSON-serializable Python value.
+            ttl: Time-to-live in seconds. If None, uses ``self.default_ttl``
+                (which itself defaults to no expiry).
+
+        Raises:
+            TypeError: If ``value`` is not JSON-serializable.
+        """
+        effective_ttl = ttl if ttl is not None else self.default_ttl
+
+        json_content = json.dumps(value)
+        fingerprint = hashlib.sha256(json_content.encode()).hexdigest()
+        entry = CacheEntry(
+            fingerprint=fingerprint, content=json_content.encode("utf-8")
+        )
+
+        await self.backend.set(self._cache_key(key), entry, ttl=effective_ttl)
+        logger.debug("Cache SET; key=%s ttl=%s", key, effective_ttl)
+
+    async def delete(self, key: str) -> bool:
+        """Remove a value from the cache.
+
+        Args:
+            key: Logical cache key (without the manager's prefix).
+
+        Returns:
+            True if the key existed and was deleted, False otherwise.
+        """
+        cache_key = self._cache_key(key)
+        existing = await self.backend.get(cache_key)
+        if existing is None:
+            return False
+        await self.backend.delete(cache_key)
+        logger.debug("Cache DELETE; key=%s", key)
+        return True
+
+    async def has(self, key: str) -> bool:
+        """Check whether a key exists in the cache without decoding its value.
+
+        Args:
+            key: Logical cache key (without the manager's prefix).
+
+        Returns:
+            True if the key exists and has not expired.
+        """
+        return await self.backend.get(self._cache_key(key)) is not None
+
+    async def clear_prefix(self, prefix: str | None = None) -> int:
+        """Clear all keys under this manager's namespace matching a sub-prefix.
+
+        Args:
+            prefix: Optional additional prefix (relative to ``self.key_prefix``)
+                to restrict which keys are cleared. If None, clears everything
+                under ``self.key_prefix``.
+
+        Returns:
+            Number of cache entries cleared.
+        """
+        match_prefix = self._cache_key(prefix or "")
+        keys = await self.backend.get_all_keys()
+        matching_keys = [key for key in keys if key.startswith(match_prefix)]
+        for key in matching_keys:
+            await self.backend.delete(key)
+        logger.debug(
+            "Cache CLEAR_PREFIX; prefix=%s removed=%s", match_prefix, len(matching_keys)
+        )
+        return len(matching_keys)
+
+    async def clear(self) -> int:
+        """Clear all keys under this manager's namespace.
+
+        Returns:
+            Number of cache entries cleared.
+        """
+        return await self.clear_prefix()

fastapi_cachex-0.3.0/fastapi_cachex/manager_proxy.py

@@ -0,0 +1,8 @@
+"""Proxy for CacheManager singleton access."""
+
+from .manager import CacheManager
+from .proxy import ProxyBase
+
+
+class CacheManagerProxy(ProxyBase[CacheManager]):
+    """FastAPI CacheX Proxy for CacheManager instance management."""

{fastapi_cachex-0.2.12 → fastapi_cachex-0.3.0}/fastapi_cachex/routes.py

@@ -124,7 +124,7 @@ async def _get_cached_hits_handler(backend: BaseCacheBackend) -> CacheHitsRespon
     now = time.time()
     cached_hits: list[CacheHitRecord] = []
 
-    for cache_key, (etag_content, expiry) in cache_data.items():
+    for cache_key, (entry, expiry) in cache_data.items():
         method, host, path, query_params = _parse_cache_key(cache_key)
         if method:  # Valid cache key
             # Check if cache entry is expired
@@ -138,7 +138,7 @@ async def _get_cached_hits_handler(backend: BaseCacheBackend) -> CacheHitsRespon
                     host=host,
                     path=path,
                     query_params=query_params,
-                    etag=etag_content.etag,
+                    etag=entry.fingerprint,
                     is_expired=is_expired,
                     ttl_remaining=ttl_remaining,
                 )
@@ -178,14 +178,14 @@ async def _get_cached_records_handler(
     now = time.time()
     cached_records: list[CachedRecord] = []
 
-    for cache_key, (etag_content, expiry) in cache_data.items():
+    for cache_key, (entry, expiry) in cache_data.items():
         method, host, path, query_params = _parse_cache_key(cache_key)
         if method:  # Valid cache key
             # Check if cache entry is expired
             is_expired = expiry is not None and expiry <= now
 
             # Get content size
-            content = etag_content.content
+            content = entry.content
             content_size = len(content) if isinstance(content, (bytes, str)) else 0
 
             ttl_remaining = max(0.0, round(expiry - now, 2)) if expiry is not None else None
@@ -203,7 +203,7 @@ async def _get_cached_records_handler(
                     host=host,
                     path=path,
                     query_params=query_params,
-                    etag=etag_content.etag,
+                    etag=entry.fingerprint,
                     content_type=type(content).__name__,
                     content_size=content_size,
                     is_expired=is_expired,

{fastapi_cachex-0.2.12 → fastapi_cachex-0.3.0}/fastapi_cachex/session/manager.py

@@ -6,7 +6,7 @@ from datetime import timedelta
 from datetime import timezone
 
 from fastapi_cachex.backends.base import BaseCacheBackend
-from fastapi_cachex.types import ETagContent
+from fastapi_cachex.types import CacheEntry
 
 from .config import SessionConfig
 from .exceptions import SessionExpiredError
@@ -130,10 +130,22 @@ class SessionManager:
             )
 
         # Bind IP and User-Agent if configured
-        if self.config.ip_binding and ip_address:
-            session.ip_address = ip_address
-        if self.config.user_agent_binding and user_agent:
-            session.user_agent = user_agent
+        if self.config.ip_binding:
+            if ip_address:
+                session.ip_address = ip_address
+            else:
+                logger.warning(
+                    "ip_binding is enabled but no IP address available; "
+                    "session created without IP binding"
+                )
+        if self.config.user_agent_binding:
+            if user_agent:
+                session.user_agent = user_agent
+            else:
+                logger.warning(
+                    "user_agent_binding is enabled but no User-Agent available; "
+                    "session created without UA binding"
+                )
 
         # Store in backend
         await self._save_session(session)
@@ -155,7 +167,7 @@ class SessionManager:
         token_string: str,
         ip_address: str | None = None,
         user_agent: str | None = None,
-    ) -> Session:
+    ) -> tuple[Session, str | None]:
         """Retrieve and validate a session.
 
         Args:
@@ -164,7 +176,9 @@ class SessionManager:
             user_agent: Current request User-Agent
 
         Returns:
-            Session object
+            Tuple of (session, new_token_string). new_token_string is non-None
+            when sliding expiration triggered a renewal; the caller should
+            propagate it to the client (e.g. via a response header).
 
         Raises:
             SessionTokenError: If token is invalid
@@ -260,6 +274,7 @@ class SessionManager:
         # Update last accessed and handle sliding expiration
         session.update_last_accessed()
 
+        renewed_token: str | None = None
         if self.config.sliding_expiration and session.expires_at:
             time_remaining = (
                 session.expires_at - datetime.now(timezone.utc)
@@ -268,6 +283,10 @@ class SessionManager:
 
             if time_remaining < threshold:
                 session.renew(self.config.session_ttl)
+                token = self._create_token(
+                    session.session_id, expires_at=session.expires_at
+                )
+                renewed_token = self._serializer.to_string(token)
                 logger.debug(
                     "Session renewed (sliding expiration); id=%s ttl=%s",
                     session.session_id,
@@ -276,7 +295,7 @@ class SessionManager:
 
         await self._save_session(session)
 
-        return session
+        return session, renewed_token
 
     async def update_session(self, session: Session) -> None:
         """Update an existing session.
@@ -429,9 +448,8 @@ class SessionManager:
             ttl = int((session.expires_at - datetime.now(timezone.utc)).total_seconds())
             ttl = max(ttl, 1)  # Ensure at least 1 second
 
-        # Store as bytes in cache backend (wrapped in ETagContent for compatibility)
-        etag = self.security.hash_data(value.decode("utf-8"))
-        await self.backend.set(key, ETagContent(etag=etag, content=value), ttl=ttl)
+        fingerprint = self.security.hash_data(value.decode("utf-8"))
+        await self.backend.set(key, CacheEntry(fingerprint=fingerprint, content=value), ttl=ttl)
         logger.debug("Session saved; id=%s ttl=%s", session.session_id, ttl)
 
     async def _load_session(self, session_id: str) -> Session | None:
@@ -462,7 +480,6 @@ class SessionManager:
 
         try:
             return Session.model_validate_json(cached.content)
-        except (ValueError, TypeError):  # pragma: no cover
-            # Invalid session data
+        except (ValueError, TypeError):
             logger.debug("Session load DESERIALIZE ERROR; key=%s", key)
             return None

{fastapi_cachex-0.2.12 → fastapi_cachex-0.3.0}/fastapi_cachex/session/middleware.py

@@ -78,11 +78,12 @@ class SessionMiddleware(BaseHTTPMiddleware):
 
         # Try to load session
         session: Session | None = None
+        renewed_token: str | None = None
         if token:
             try:
                 ip_address = self._get_client_ip(request)
                 user_agent = request.headers.get("user-agent")
-                session = await self.session_manager.get_session(
+                session, renewed_token = await self.session_manager.get_session(
                     token,
                     ip_address=ip_address,
                     user_agent=user_agent,
@@ -99,6 +100,10 @@ class SessionMiddleware(BaseHTTPMiddleware):
         # Process request
         response: Response = await call_next(request)
 
+        # Propagate renewed token to client so its JWT exp stays in sync
+        if renewed_token is not None:
+            response.headers[self.config.header_name] = renewed_token
+
         return response
 
     def _extract_token(self, request: Request) -> str | None:

{fastapi_cachex-0.2.12 → fastapi_cachex-0.3.0}/fastapi_cachex/session/security.py

@@ -21,8 +21,7 @@ class SecurityManager:
         if len(secret_key) < 32:  # noqa: PLR2004
             msg = "Secret key must be at least 32 characters"
             raise ValueError(msg)
-        # Use name mangling so the key bytes are not trivially accessible via repr
-        self.__secret_key_bytes = secret_key.encode("utf-8")
+        self._secret_key_bytes = secret_key.encode("utf-8")
 
         logger.debug(
             "SecurityManager initialized with secret length=%s", len(secret_key)
@@ -38,7 +37,7 @@ class SecurityManager:
             The signature as a hex string
         """
         return hmac.new(
-            self.__secret_key_bytes,
+            self._secret_key_bytes,
             session_id.encode("utf-8"),
             hashlib.sha256,
         ).hexdigest()

{fastapi_cachex-0.2.12 → fastapi_cachex-0.3.0}/fastapi_cachex/session/token_serializers.py

@@ -80,7 +80,7 @@ class SimpleTokenSerializer:
         session_id, signature, timestamp = parts
         try:
             issued_at = datetime.fromtimestamp(int(timestamp), tz=timezone.utc)
-        except (ValueError, OSError) as e:
+        except (ValueError, OSError, OverflowError) as e:
             msg = f"Invalid timestamp in token: {e}"
             raise ValueError(msg) from e
 

{fastapi_cachex-0.2.12 → fastapi_cachex-0.3.0}/fastapi_cachex/state/manager.py

@@ -11,7 +11,7 @@ from typing import Any
 
 from fastapi_cachex.backends.base import BaseCacheBackend
 from fastapi_cachex.proxy import BackendProxy
-from fastapi_cachex.types import ETagContent
+from fastapi_cachex.types import CacheEntry
 
 from .exceptions import InvalidStateError
 from .exceptions import StateDataError
@@ -44,11 +44,11 @@ class StateManager:
         self.key_prefix = key_prefix
         self.default_ttl = default_ttl
 
-    def _extract_json_content(self, cached: ETagContent) -> str:
-        """Extract JSON string from a cached ETagContent value.
+    def _extract_json_content(self, cached: CacheEntry) -> str:
+        """Extract JSON string from a cached CacheEntry.
 
         Args:
-            cached: The ETagContent retrieved from backend
+            cached: The CacheEntry retrieved from backend
 
         Returns:
             JSON string
@@ -122,13 +122,11 @@ class StateManager:
         # Serialize to JSON
         json_content = json.dumps(state_data.model_dump(mode="json"))
 
-        # Create ETag from hash of state data
-        etag = hashlib.sha256(json_content.encode()).hexdigest()
+        fingerprint = hashlib.sha256(json_content.encode()).hexdigest()
 
-        # Store in backend with TTL using ETagContent
         cache_key = f"{self.key_prefix}{state}"
-        etag_content = ETagContent(etag=etag, content=json_content.encode("utf-8"))
-        await self.backend.set(cache_key, etag_content, ttl=effective_ttl)
+        entry = CacheEntry(fingerprint=fingerprint, content=json_content.encode("utf-8"))
+        await self.backend.set(cache_key, entry, ttl=effective_ttl)
 
         logger.debug("OAuth state created; state=%s ttl=%s", state, effective_ttl)
         return state
@@ -150,13 +148,13 @@ class StateManager:
         cache_key = f"{self.key_prefix}{state}"
 
         # Retrieve state data from backend
-        cached_etag_content = await self.backend.get(cache_key)
-        if cached_etag_content is None:
+        cached = await self.backend.get(cache_key)
+        if cached is None:
             logger.warning("OAuth state not found or expired; state=%s", state)
             msg = "Invalid or expired state"
             raise InvalidStateError(msg)
 
-        json_content = self._extract_json_content(cached_etag_content)
+        json_content = self._extract_json_content(cached)
         state_data = self._parse_state_data(json_content, state)
 
         # Verify expiry
@@ -182,15 +180,15 @@ class StateManager:
         """
         cache_key = f"{self.key_prefix}{state}"
 
-        cached_etag_content = await self.backend.get(cache_key)
-        if cached_etag_content is None:
+        cached = await self.backend.get(cache_key)
+        if cached is None:
             logger.debug("State validation failed - not found; state=%s", state)
             return False
 
         try:
-            json_content = self._extract_json_content(cached_etag_content)
+            json_content = self._extract_json_content(cached)
             state_data = self._parse_state_data(json_content, state)
-        except (StateDataError, UnicodeDecodeError):
+        except StateDataError:
             logger.exception(
                 "Failed to parse or validate state data; state=%s",
                 state,
@@ -215,14 +213,14 @@ class StateManager:
         """
         cache_key = f"{self.key_prefix}{state}"
 
-        cached_etag_content = await self.backend.get(cache_key)
-        if cached_etag_content is None:
+        cached = await self.backend.get(cache_key)
+        if cached is None:
             return None
 
         try:
-            json_content = self._extract_json_content(cached_etag_content)
+            json_content = self._extract_json_content(cached)
             state_data = self._parse_state_data(json_content, state)
-        except (StateDataError, UnicodeDecodeError):
+        except StateDataError:
             logger.exception("Failed to parse or validate state data; state=%s", state)
             return None
 

{fastapi_cachex-0.2.12 → fastapi_cachex-0.3.0}/fastapi_cachex/types.py

@@ -13,10 +13,10 @@ CacheKeyBuilder = Callable[[Request], str]
 
 
 @dataclass
-class ETagContent:
-    """ETag and content for cache items."""
+class CacheEntry:
+    """Cache entry storing a fingerprint, raw content bytes, and an optional media type."""
 
-    etag: str
+    fingerprint: str
     content: bytes
     media_type: str | None = None
 
@@ -26,9 +26,9 @@ class CacheItem:
     """Cache item with optional expiry time.
 
     Args:
-        value: The cached ETagContent
+        value: The cached entry
         expiry: Epoch timestamp when this cache item expires (None = never expires)
     """
 
-    value: ETagContent
+    value: CacheEntry
     expiry: float | None = None

{fastapi_cachex-0.2.12 → fastapi_cachex-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-cachex"
-version = "0.2.12"
+version = "0.3.0"
 description = "A caching library for FastAPI with support for Cache-Control, ETag, and multiple backends."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -60,7 +60,7 @@ redis = ["redis[hiredis]>=5.3.0", "orjson"]
 jwt = ["PyJWT>=2.9.0"]
 
 [build-system]
-requires = ["uv_build>=0.9.17,<0.11.0"]
+requires = ["uv_build>=0.11.26,<0.12"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]

fastapi_cachex-0.2.12/fastapi_cachex/dependencies.py

@@ -1,16 +0,0 @@
-"""FastAPI dependency injection utilities for cache control."""
-
-from typing import Annotated
-
-from fastapi import Depends
-
-from .backends.base import BaseCacheBackend
-from .proxy import BackendProxy
-
-
-def get_cache_backend() -> BaseCacheBackend:
-    """Dependency to get the current cache backend instance."""
-    return BackendProxy.get()
-
-
-CacheBackend = Annotated[BaseCacheBackend, Depends(get_cache_backend)]