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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-cachex
-Version: 0.3.0
+Version: 0.3.2
 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
@@ -25,6 +25,7 @@ Requires-Dist: pyjwt>=2.9.0 ; extra == 'jwt'
 Requires-Dist: pymemcache ; extra == 'memcache'
 Requires-Dist: redis[hiredis]>=5.3.0 ; extra == 'redis'
 Requires-Dist: orjson ; extra == 'redis'
+Requires-Dist: itsdangerous ; extra == 'starlette'
 Requires-Python: >=3.10
 Project-URL: Homepage, https://github.com/allen0099/FastAPI-CacheX
 Project-URL: Repository, https://github.com/allen0099/FastAPI-CacheX.git
@@ -32,6 +33,7 @@ Project-URL: Issues, https://github.com/allen0099/FastAPI-CacheX/issues
 Provides-Extra: jwt
 Provides-Extra: memcache
 Provides-Extra: redis
+Provides-Extra: starlette
 Description-Content-Type: text/markdown
 
 # FastAPI-Cache X

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

@@ -4,6 +4,7 @@ import logging
 
 from .cache import cache as cache
 from .cache import default_key_builder as default_key_builder
+from .cache import invalidate as invalidate
 from .dependencies import AppCache as AppCache
 from .dependencies import CacheBackend as CacheBackend
 from .dependencies import get_app_cache as get_app_cache
@@ -12,6 +13,7 @@ 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 FastAPICacheXSessionMiddleware as FastAPICacheXSessionMiddleware
 from .session import Session as Session
 from .session import SessionConfig as SessionConfig
 from .session import SessionManager as SessionManager
@@ -34,6 +36,9 @@ from .state import StateDataError as StateDataError
 from .state import StateError as StateError
 from .state import StateExpiredError as StateExpiredError
 from .state import StateManager as StateManager
+from .state import StateManagerDep as StateManagerDep
+from .state import StateManagerProxy as StateManagerProxy
+from .state import get_state_manager as get_state_manager
 from .types import CacheKeyBuilder as CacheKeyBuilder
 
 _package_logger = logging.getLogger("fastapi_cachex")
@@ -48,6 +53,7 @@ __all__ = [
     "CacheKeyBuilder",
     "CacheManager",
     "CacheManagerProxy",
+    "FastAPICacheXSessionMiddleware",
     "InvalidStateError",
     "Session",
     "SessionConfig",
@@ -66,6 +72,8 @@ __all__ = [
     "StateError",
     "StateExpiredError",
     "StateManager",
+    "StateManagerDep",
+    "StateManagerProxy",
     "add_routes",
     "cache",
     "default_key_builder",
@@ -74,5 +82,7 @@ __all__ = [
     "get_optional_session",
     "get_session",
     "get_session_manager",
+    "get_state_manager",
+    "invalidate",
     "require_session",
 ]

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

@@ -177,7 +177,9 @@ class MemcachedBackend(BaseCacheBackend):
         # Try to delete the prefixed key (exact match only)
         prefixed_key = self._make_key(path)
         try:
-            result = await asyncio.to_thread(self.client.delete, prefixed_key, False)
+            result = await asyncio.to_thread(
+                self.client.delete, prefixed_key, noreply=False
+            )
         except Exception:  # noqa: BLE001
             return 0
         else:

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

@@ -183,6 +183,11 @@ class MemoryBackend(BaseCacheBackend):
                     if fnmatch.fnmatch(cache_path, pattern):
                         keys_to_delete.append(key)
                         cleared_count += 1
+                elif fnmatch.fnmatch(key, pattern):
+                    # Non-HTTP-cache key (no separators, e.g. CacheManager/
+                    # StateManager keys) - match against the raw key.
+                    keys_to_delete.append(key)
+                    cleared_count += 1
 
             for key in keys_to_delete:
                 del self.cache[key]

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

@@ -61,6 +61,44 @@ def default_key_builder(request: Request) -> str:
     return key
 
 
+async def invalidate(
+    request: Request,
+    key_builder: CacheKeyBuilder | None = None,
+) -> bool:
+    """Invalidate the cache entry a ``@cache``-decorated route would use.
+
+    Builds the same cache key the ``@cache`` decorator would build for
+    ``request`` (via ``key_builder`` or ``default_key_builder``) and deletes
+    it from the configured backend. Use this after a mutation to bust the
+    cache for a specific cached route response.
+
+    Args:
+        request: The request whose cache key should be invalidated. Typically
+            a request to the same route/method as the cached one (e.g. build
+            it via ``request.app.url_path_for(...)`` for a GET route).
+        key_builder: Custom key builder used by the target route's ``@cache``
+            decorator, if any. If None, uses ``default_key_builder``.
+
+    Returns:
+        True if a cache entry existed and was deleted, False otherwise.
+    """
+    builder = key_builder or default_key_builder
+    cache_key = builder(request)
+
+    try:
+        cache_backend = BackendProxy.get()
+    except BackendNotFoundError:
+        return False
+
+    existing = await cache_backend.get(cache_key)
+    if existing is None:
+        return False
+
+    await cache_backend.delete(cache_key)
+    logger.debug("Cache INVALIDATE; key=%s", cache_key)
+    return True
+
+
 class CacheControl:
     """Manages Cache-Control header directives."""
 
@@ -113,11 +151,21 @@ async def get_response(
         msg = "Route not found in request scope"
         raise CacheXError(msg)
 
-    # FastAPI <= 0.136.x stores a DefaultPlaceholder; >= 0.137.0 stores the class directly.
-    # getattr with a fallback handles both without importing the internal class.
+    # A placeholder means this route uses the application default. Unwrap the
+    # application value instead of calling the route's DefaultPlaceholder.
+    route_response_class = route.response_class
+    application_default_response_class = __request.app.router.default_response_class
     response_class: type[Response] = cast(
         "type[Response]",
-        getattr(route.response_class, "value", route.response_class),
+        (
+            getattr(
+                application_default_response_class,
+                "value",
+                application_default_response_class,
+            )
+            if hasattr(route_response_class, "value")
+            else route_response_class
+        ),
     )
 
     # Convert non-Response result to Response using appropriate response_class
@@ -282,9 +330,7 @@ def cache(
                         # StreamingResponse/FileResponse — cannot compute ETag; serve as-is
                         current_response.headers["Cache-Control"] = cache_control
                         return current_response
-                    current_etag = (
-                        f'W/"{hashlib.md5(current_body).hexdigest()}"'  # noqa: S324
-                    )
+                    current_etag = f'W/"{hashlib.md5(current_body).hexdigest()}"'  # noqa: S324
 
                     if client_etag == current_etag:
                         # For no-cache, compare fresh data with client's ETag
@@ -343,7 +389,9 @@ def cache(
 
             # Update cache if needed
             if not cached_data or cached_data.fingerprint != current_etag:
-                assert current_body is not None  # guaranteed by early-return guards above
+                assert (
+                    current_body is not None
+                )  # guaranteed by early-return guards above
                 # Store in cache if data changed
                 await cache_backend.set(
                     cache_key,

{fastapi_cachex-0.3.0 → fastapi_cachex-0.3.2}/fastapi_cachex/manager.py

@@ -1,8 +1,11 @@
 """Generic application-level cache manager for FastAPI-CacheX."""
 
 import hashlib
+import inspect
 import json
 import logging
+from collections.abc import Awaitable
+from collections.abc import Callable
 from typing import Any
 
 from .backends.base import BaseCacheBackend
@@ -117,6 +120,67 @@ class CacheManager:
         """
         return await self.backend.get(self._cache_key(key)) is not None
 
+    async def get_or_set(
+        self,
+        key: str,
+        factory: Callable[[], Any] | Callable[[], Awaitable[Any]],
+        ttl: int | None = None,
+    ) -> Any:
+        """Get a cached value, computing and storing it via ``factory`` on a miss.
+
+        ``factory`` is only invoked when ``key`` is missing, expired, or its
+        stored content cannot be decoded; on a hit the cached value is
+        returned directly. This method does not provide stampede protection:
+        concurrent misses for the same key may each invoke ``factory``.
+
+        Args:
+            key: Logical cache key (without the manager's prefix).
+            factory: Zero-argument callable (sync or async) that produces the
+                JSON-serializable value to cache on a miss.
+            ttl: Time-to-live in seconds for a newly created value. If None,
+                uses ``self.default_ttl``.
+
+        Returns:
+            The cached value (existing or newly created).
+
+        Raises:
+            TypeError: If the value produced by ``factory`` is not JSON-serializable.
+        """
+        sentinel = object()
+        cached = await self.get(key, default=sentinel)
+        if cached is not sentinel:
+            return cached
+
+        if inspect.iscoroutinefunction(factory):
+            value = await factory()
+        else:
+            value = factory()
+
+        await self.set(key, value, ttl=ttl)
+        return value
+
+    async def clear_pattern(self, pattern: str) -> int:
+        """Clear all keys under this manager's namespace matching a glob pattern.
+
+        Delegates to the backend's native ``clear_pattern`` (e.g. Redis ``SCAN``),
+        which can be more efficient than ``clear_prefix``'s full key-space scan.
+        Note that backends without key-enumeration support (e.g. Memcached)
+        cannot honor this and will return 0 with a ``RuntimeWarning``.
+
+        Args:
+            pattern: Glob pattern (relative to ``self.key_prefix``) to match
+                against, e.g. ``"user:*"``.
+
+        Returns:
+            Number of cache entries cleared.
+        """
+        match_pattern = self._cache_key(pattern)
+        cleared = await self.backend.clear_pattern(match_pattern)
+        logger.debug(
+            "Cache CLEAR_PATTERN; pattern=%s removed=%s", match_pattern, cleared
+        )
+        return cleared
+
     async def clear_prefix(self, prefix: str | None = None) -> int:
         """Clear all keys under this manager's namespace matching a sub-prefix.
 

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

@@ -129,7 +129,9 @@ async def _get_cached_hits_handler(backend: BaseCacheBackend) -> CacheHitsRespon
         if method:  # Valid cache key
             # Check if cache entry is expired
             is_expired = expiry is not None and expiry <= now
-            ttl_remaining = max(0.0, round(expiry - now, 2)) if expiry is not None else None
+            ttl_remaining = (
+                max(0.0, round(expiry - now, 2)) if expiry is not None else None
+            )
 
             cached_hits.append(
                 CacheHitRecord(
@@ -188,7 +190,9 @@ async def _get_cached_records_handler(
             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
+            ttl_remaining = (
+                max(0.0, round(expiry - now, 2)) if expiry is not None else None
+            )
 
             content_preview = (
                 content[:100].decode("utf-8", errors="ignore")

{fastapi_cachex-0.3.0 → fastapi_cachex-0.3.2}/fastapi_cachex/session/__init__.py

@@ -6,12 +6,14 @@ from .dependencies import get_session
 from .dependencies import get_session_manager
 from .dependencies import require_session
 from .manager import SessionManager
+from .middleware import FastAPICacheXSessionMiddleware
 from .middleware import SessionMiddleware
 from .models import Session
 from .models import SessionUser
 from .proxy import SessionManagerProxy
 
 __all__ = [
+    "FastAPICacheXSessionMiddleware",
     "Session",
     "SessionConfig",
     "SessionManager",

{fastapi_cachex-0.3.0 → fastapi_cachex-0.3.2}/fastapi_cachex/session/config.py

@@ -3,13 +3,18 @@
 from typing import Literal
 
 from pydantic import BaseModel
+from pydantic import ConfigDict
 from pydantic import Field
 from pydantic import SecretStr
 
+SameSitePolicy = Literal["lax", "strict", "none"]
+
 
 class SessionConfig(BaseModel):
     """Session configuration settings."""
 
+    model_config = ConfigDict(extra="forbid")
+
     # Session lifetime
     session_ttl: int = Field(
         default=3600,
@@ -87,3 +92,33 @@ class SessionConfig(BaseModel):
         default="session:",
         description="Prefix for session keys in backend storage",
     )
+
+    # Cookie settings (FastAPICacheXSessionMiddleware only)
+    cookie_name: str = Field(
+        default="session",
+        description="Name of the cookie used to store the session token "
+        "(FastAPICacheXSessionMiddleware only)",
+    )
+    cookie_max_age: int | None = Field(
+        default=14 * 24 * 60 * 60,
+        description="Max-Age (seconds) for the session cookie; None disables "
+        "Max-Age/Expires (session cookie deleted when browser closes)",
+    )
+    cookie_path: str = Field(
+        default="/",
+        description="Path attribute for the session cookie",
+    )
+    cookie_same_site: SameSitePolicy = Field(
+        default="lax",
+        description="SameSite attribute for the session cookie",
+    )
+    cookie_https_only: bool = Field(
+        default=False,
+        description="Whether to set the Secure flag on the session cookie "
+        "(cookie only sent over HTTPS)",
+    )
+    cookie_domain: str | None = Field(
+        default=None,
+        description="Domain attribute for the session cookie; None omits the "
+        "Domain attribute",
+    )

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

@@ -76,7 +76,7 @@ class SessionManager:
         user: SessionUser,
         ip_address: str | None = None,
         user_agent: str | None = None,
-        **extra_data: dict[str, object],
+        **extra_data: object,
     ) -> tuple[Session, str]:
         """Create a new session for an authenticated user.
 
@@ -100,7 +100,7 @@ class SessionManager:
         self,
         ip_address: str | None = None,
         user_agent: str | None = None,
-        **extra_data: dict[str, object],
+        **extra_data: object,
     ) -> tuple[Session, str]:
         """Create a new session without user information."""
         return await self._create_session(
@@ -115,7 +115,7 @@ class SessionManager:
         user: SessionUser | None,
         ip_address: str | None = None,
         user_agent: str | None = None,
-        **extra_data: dict[str, object],
+        **extra_data: object,
     ) -> tuple[Session, str]:
         """Internal helper to create and persist a session."""
         session = Session(
@@ -449,7 +449,9 @@ class SessionManager:
             ttl = max(ttl, 1)  # Ensure at least 1 second
 
         fingerprint = self.security.hash_data(value.decode("utf-8"))
-        await self.backend.set(key, CacheEntry(fingerprint=fingerprint, content=value), ttl=ttl)
+        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: