fastapi-cachex 0.3.8__tar.gz → 0.3.9__tar.gz

{fastapi_cachex-0.3.8 → fastapi_cachex-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-cachex
-Version: 0.3.8
+Version: 0.3.9
 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
@@ -114,27 +114,45 @@ def build_report() -> dict:
 
 @app.get("/report")
 async def report(cache: AppCache):
-    # Cache any JSON value in your own code.
-    return await cache.get_or_set("report", build_report, ttl=300)
+    # Cache any JSON value in your own code. lock=True runs build_report once
+    # for concurrent misses (the default from 0.4.0).
+    return await cache.get_or_set("report", build_report, ttl=300, lock=True)
 ```
 
+> [!IMPORTANT]
+> Put `@cache` **below** the route decorator. FastAPI registers whatever function
+> reaches `@app.get(...)`; with `@cache` on top, FastAPI registers the
+> undecorated handler, so the route works but nothing is cached and nothing warns
+> (see [Decorator order](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/#decorator-order)).
+>
+> ```python
+> @app.get("/items")  # ✅ route decorator first,
+> @cache(ttl=60)      #    @cache directly above the function
+> async def items(): ...
+>
+> @cache(ttl=60)      # ❌ never called: nothing is cached
+> @app.get("/items")
+> async def items(): ...
+> ```
+
 > [!WARNING]
 > The default cache key carries no user identity. Cache authenticated endpoints
-> with `private=True` or a per-user key builder — see
+> with `private=True` or a per-user key builder plus `cache_authorized=True`
+> (requests with `Authorization` or a session otherwise bypass the backend) — see
 > [Authenticated endpoints](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/#authenticated-endpoints).
 
 ## Documentation
 
+- [Migrating to 0.4.0](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_0_4/) — what 0.4.0 changes and how to act on the 0.3.9 warnings now
 - [HTTP caching](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/) — the `@cache` decorator, Cache-Control directives, cache keys, invalidation and monitoring routes
-- [Cache flow](https://fastapi-cachex.readthedocs.io/en/latest/CACHE_FLOW/) — what happens inside a cached request
 - [Application cache](https://fastapi-cachex.readthedocs.io/en/latest/APP_CACHE/) — `CacheManager`
 - [Backends](https://fastapi-cachex.readthedocs.io/en/latest/BACKENDS/) — choosing and configuring a backend, atomic primitives
-- [Session management](https://fastapi-cachex.readthedocs.io/en/latest/SESSION/) and [JWT claims](https://fastapi-cachex.readthedocs.io/en/latest/JWT_CLAIMS/)
-- [OAuth state](https://fastapi-cachex.readthedocs.io/en/latest/STATE/) — one-shot OAuth/CSRF state tokens
 - [Distributed lock](https://fastapi-cachex.readthedocs.io/en/latest/LOCK/) — `CacheLock` for multi-process mutual exclusion
+- [Session management](https://fastapi-cachex.readthedocs.io/en/latest/SESSION/), [OAuth state](https://fastapi-cachex.readthedocs.io/en/latest/STATE/) (one-shot OAuth/CSRF state tokens) and [JWT claims](https://fastapi-cachex.readthedocs.io/en/latest/JWT_CLAIMS/)
+- [Cache flow](https://fastapi-cachex.readthedocs.io/en/latest/CACHE_FLOW/) — what happens inside a cached request
 - [Runnable examples](https://github.com/allen0099/FastAPI-CacheX/tree/master/examples) — one complete app per feature, each covered by the test suite
 - [API reference](https://fastapi-cachex.readthedocs.io/en/latest/api/http-caching/)
-- [Development guide](https://fastapi-cachex.readthedocs.io/en/latest/DEVELOPMENT/) and [contributing](https://fastapi-cachex.readthedocs.io/en/latest/CONTRIBUTING/)
+- [Development guide](https://fastapi-cachex.readthedocs.io/en/latest/DEVELOPMENT/) and [contributing](https://fastapi-cachex.readthedocs.io/en/latest/CONTRIBUTING/) · [Security policy](https://github.com/allen0099/FastAPI-CacheX/blob/master/SECURITY.md) — report vulnerabilities privately, not in public issues
 - [Changelog](https://github.com/allen0099/FastAPI-CacheX/blob/master/CHANGELOG.md) · [Known limitations and planned work](https://github.com/allen0099/FastAPI-CacheX/issues)
 
 ## License

{fastapi_cachex-0.3.8 → fastapi_cachex-0.3.9}/README.md

@@ -71,27 +71,45 @@ def build_report() -> dict:
 
 @app.get("/report")
 async def report(cache: AppCache):
-    # Cache any JSON value in your own code.
-    return await cache.get_or_set("report", build_report, ttl=300)
+    # Cache any JSON value in your own code. lock=True runs build_report once
+    # for concurrent misses (the default from 0.4.0).
+    return await cache.get_or_set("report", build_report, ttl=300, lock=True)
 ```
 
+> [!IMPORTANT]
+> Put `@cache` **below** the route decorator. FastAPI registers whatever function
+> reaches `@app.get(...)`; with `@cache` on top, FastAPI registers the
+> undecorated handler, so the route works but nothing is cached and nothing warns
+> (see [Decorator order](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/#decorator-order)).
+>
+> ```python
+> @app.get("/items")  # ✅ route decorator first,
+> @cache(ttl=60)      #    @cache directly above the function
+> async def items(): ...
+>
+> @cache(ttl=60)      # ❌ never called: nothing is cached
+> @app.get("/items")
+> async def items(): ...
+> ```
+
 > [!WARNING]
 > The default cache key carries no user identity. Cache authenticated endpoints
-> with `private=True` or a per-user key builder — see
+> with `private=True` or a per-user key builder plus `cache_authorized=True`
+> (requests with `Authorization` or a session otherwise bypass the backend) — see
 > [Authenticated endpoints](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/#authenticated-endpoints).
 
 ## Documentation
 
+- [Migrating to 0.4.0](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_0_4/) — what 0.4.0 changes and how to act on the 0.3.9 warnings now
 - [HTTP caching](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/) — the `@cache` decorator, Cache-Control directives, cache keys, invalidation and monitoring routes
-- [Cache flow](https://fastapi-cachex.readthedocs.io/en/latest/CACHE_FLOW/) — what happens inside a cached request
 - [Application cache](https://fastapi-cachex.readthedocs.io/en/latest/APP_CACHE/) — `CacheManager`
 - [Backends](https://fastapi-cachex.readthedocs.io/en/latest/BACKENDS/) — choosing and configuring a backend, atomic primitives
-- [Session management](https://fastapi-cachex.readthedocs.io/en/latest/SESSION/) and [JWT claims](https://fastapi-cachex.readthedocs.io/en/latest/JWT_CLAIMS/)
-- [OAuth state](https://fastapi-cachex.readthedocs.io/en/latest/STATE/) — one-shot OAuth/CSRF state tokens
 - [Distributed lock](https://fastapi-cachex.readthedocs.io/en/latest/LOCK/) — `CacheLock` for multi-process mutual exclusion
+- [Session management](https://fastapi-cachex.readthedocs.io/en/latest/SESSION/), [OAuth state](https://fastapi-cachex.readthedocs.io/en/latest/STATE/) (one-shot OAuth/CSRF state tokens) and [JWT claims](https://fastapi-cachex.readthedocs.io/en/latest/JWT_CLAIMS/)
+- [Cache flow](https://fastapi-cachex.readthedocs.io/en/latest/CACHE_FLOW/) — what happens inside a cached request
 - [Runnable examples](https://github.com/allen0099/FastAPI-CacheX/tree/master/examples) — one complete app per feature, each covered by the test suite
 - [API reference](https://fastapi-cachex.readthedocs.io/en/latest/api/http-caching/)
-- [Development guide](https://fastapi-cachex.readthedocs.io/en/latest/DEVELOPMENT/) and [contributing](https://fastapi-cachex.readthedocs.io/en/latest/CONTRIBUTING/)
+- [Development guide](https://fastapi-cachex.readthedocs.io/en/latest/DEVELOPMENT/) and [contributing](https://fastapi-cachex.readthedocs.io/en/latest/CONTRIBUTING/) · [Security policy](https://github.com/allen0099/FastAPI-CacheX/blob/master/SECURITY.md) — report vulnerabilities privately, not in public issues
 - [Changelog](https://github.com/allen0099/FastAPI-CacheX/blob/master/CHANGELOG.md) · [Known limitations and planned work](https://github.com/allen0099/FastAPI-CacheX/issues)
 
 ## License

{fastapi_cachex-0.3.8 → fastapi_cachex-0.3.9}/fastapi_cachex/__init__.py

@@ -4,6 +4,7 @@ import logging
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version
 
+from .cache import build_cache_key as build_cache_key
 from .cache import cache as cache
 from .cache import default_key_builder as default_key_builder
 from .cache import invalidate as invalidate
@@ -107,6 +108,7 @@ __all__ = [
     "StateManagerProxy",
     "__version__",
     "add_routes",
+    "build_cache_key",
     "cache",
     "default_key_builder",
     "get_app_cache",

{fastapi_cachex-0.3.8 → fastapi_cachex-0.3.9}/fastapi_cachex/backends/base.py

@@ -4,6 +4,8 @@ import warnings
 from abc import ABC
 from abc import abstractmethod
 from collections.abc import Iterable
+from types import TracebackType
+from typing import TYPE_CHECKING
 from typing import Any
 
 from fastapi_cachex.types import CACHE_KEY_SEPARATOR
@@ -11,6 +13,11 @@ from fastapi_cachex.types import CacheEntry
 from fastapi_cachex.types import counter_entry
 from fastapi_cachex.types import counter_value
 
+if TYPE_CHECKING:
+    # Type-only: typing.Self is 3.11+, and typing_extensions is not a runtime
+    # dependency.
+    from typing_extensions import Self
+
 
 def warn_if_path_shaped(pattern: str, cleared: int) -> None:
     """Warn when a ``clear_pattern`` that cleared nothing was written as a path.
@@ -89,7 +96,33 @@ def validate_delta(delta: int) -> int:
 
 
 class BaseCacheBackend(ABC):
-    """Base class for all cache backends."""
+    """Base class for all cache backends.
+
+    Every backend is an async context manager: ``async with`` returns the
+    backend itself and calls ``aclose()`` on the way out.
+    """
+
+    async def aclose(self) -> None:  # noqa: B027 - a no-op default, not abstract
+        """Release what the backend holds open: connections, background tasks.
+
+        Call it once on shutdown, typically at the end of a FastAPI lifespan.
+        It is safe to call more than once. The base implementation does
+        nothing, for backends with nothing to release; the built-in backends
+        override it.
+        """
+
+    async def __aenter__(self) -> "Self":
+        """Return the backend itself."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Close the backend with ``aclose()``."""
+        await self.aclose()
 
     @abstractmethod
     async def get(self, key: str) -> CacheEntry | None:
@@ -246,7 +279,8 @@ class BaseCacheBackend(ABC):
         Raises:
             CacheXError: If ``key`` holds a cached response instead of a counter
             TypeError: If ``delta`` or ``ttl`` is not an ``int``
-            ValueError: If ``ttl`` is out of range
+            ValueError: If ``ttl`` is out of range, or ``delta`` does not fit
+                in a signed 64-bit integer
         """
         validate_delta(delta)
         validate_ttl(ttl)

{fastapi_cachex-0.3.8 → fastapi_cachex-0.3.9}/fastapi_cachex/backends/codec.py

@@ -4,6 +4,8 @@ Both backends store a ``CacheEntry`` as a JSON document; ``orjson`` is used when
 it is installed and the standard library ``json`` module otherwise.
 """
 
+import math
+
 from fastapi_cachex.types import COUNTER_FINGERPRINT
 from fastapi_cachex.types import DEFAULT_STATUS_CODE
 from fastapi_cachex.types import CacheEntry
@@ -45,12 +47,20 @@ def encode_entry(entry: CacheEntry) -> bytes:
             "media_type": entry.media_type,
             "status_code": entry.status_code,
             "headers": entry.headers,
+            "stored_at": entry.stored_at,
         },
     )
     # orjson returns bytes, stdlib json returns str
     return serialized if isinstance(serialized, bytes) else serialized.encode("utf-8")
 
 
+def _stored_at(value: object) -> float | None:
+    """``stored_at`` from a document; anything but a finite number is unknown."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    return float(value) if math.isfinite(value) else None
+
+
 def decode_entry(raw: str | bytes | None) -> CacheEntry | None:
     """Rebuild a ``CacheEntry`` from a stored value.
 
@@ -61,7 +71,8 @@ def decode_entry(raw: str | bytes | None) -> CacheEntry | None:
     cache miss.
 
     Documents written before entries carried a status code and headers simply
-    lack those keys and decode to a plain ``200`` with no extra headers.
+    lack those keys and decode to a plain ``200`` with no extra headers; those
+    written before entries carried ``stored_at`` decode with ``None``.
     """
     if raw is None:
         return None
@@ -76,6 +87,7 @@ def decode_entry(raw: str | bytes | None) -> CacheEntry | None:
             media_type=data.get("media_type"),
             status_code=data.get("status_code", DEFAULT_STATUS_CODE),
             headers=data.get("headers"),
+            stored_at=_stored_at(data.get("stored_at")),
         )
     except _DECODE_ERRORS:
         return None

{fastapi_cachex-0.3.8 → fastapi_cachex-0.3.9}/fastapi_cachex/backends/config.py

@@ -16,7 +16,14 @@ class RedisConfig(BaseModel):
         default=None, description="Redis server password"
     )
     db: int = Field(default=0, ge=0, description="Redis database number")
-    encoding: str = Field(default="utf-8", description="Character encoding to use")
+    encoding: str = Field(
+        default="utf-8",
+        description=(
+            "Deprecated, removed in 0.4.0: leave it unset. Character encoding "
+            "the client decodes replies with; setting it emits a "
+            "DeprecationWarning in load_from_config()."
+        ),
+    )
     socket_timeout: float = Field(
         default=1.0, description="Timeout for socket operations in seconds"
     )

{fastapi_cachex-0.3.8 → fastapi_cachex-0.3.9}/fastapi_cachex/backends/memcached.py

@@ -2,6 +2,7 @@
 
 import asyncio
 import hashlib
+import inspect
 import logging
 import time
 import warnings
@@ -68,6 +69,26 @@ def _expiry(ttl: int | None) -> int:
     return ttl
 
 
+def _caller_stacklevel() -> int:
+    """Return the ``stacklevel`` of the first frame outside fastapi_cachex.
+
+    For a ``warnings.warn`` in the method that calls this, so a warning raised
+    through ``CacheManager`` names the application's line, not manager.py.
+    """
+    frame = inspect.currentframe()
+    if frame is None or frame.f_back is None:  # no frame support
+        return 2
+    # Level 1 is the method that warns; start at its caller.
+    level, frame = 2, frame.f_back.f_back
+    while frame is not None:
+        module = frame.f_globals.get("__name__", "")
+        if module != "fastapi_cachex" and not module.startswith("fastapi_cachex."):
+            break
+        frame = frame.f_back
+        level += 1
+    return level
+
+
 class MemcachedBackend(BaseCacheBackend):
     """Memcached backend implementation.
 
@@ -78,7 +99,10 @@ class MemcachedBackend(BaseCacheBackend):
     conflicts with other applications.
 
     Limitations:
-    - Pattern-based clearing (clear_pattern) is not supported by Memcached protocol
+    - Memcached cannot enumerate keys: clear_pattern clears nothing (returns
+      0) and get_all_keys/get_cache_data return empty results, each with a
+      RuntimeWarning; clear_path only deletes a key named exactly as the path
+    - clear() issues flush_all, which empties the whole server
     - Operations are wrapped to appear async but use blocking sync client internally
     """
 
@@ -126,6 +150,15 @@ class MemcachedBackend(BaseCacheBackend):
         )
         self.key_prefix = key_prefix
 
+    async def aclose(self) -> None:
+        """Close every pooled connection to every server.
+
+        Safe to call more than once. The pymemcache client reconnects on the
+        next call, so a backend used after ``aclose()`` opens new sockets that
+        need another ``aclose()``.
+        """
+        await asyncio.to_thread(self.client.close)
+
     def _make_key(self, key: str) -> str:
         """Namespace a cache key, hashing it when Memcached would refuse it.
 
@@ -307,20 +340,42 @@ class MemcachedBackend(BaseCacheBackend):
         return None if result is None else int(result)
 
     def _increment(self, prefixed_key: str, delta: int, exptime: int) -> int | None:
-        """Run ``increment``'s INCR, ADD and retried INCR in one worker thread."""
+        """Run ``increment``'s INCR, ADD and retried INCR in one worker thread.
+
+        Returns ``None`` only when the counter vanished after every one of
+        ``_CAS_MAX_RETRIES`` ADD + INCR attempts.
+        """
         value = self._add_delta(prefixed_key, delta)
-        if value is None:
+        if value is not None:
+            return value
+        for _ in range(_CAS_MAX_RETRIES):
             # No counter yet: ADD is atomic and a no-op when a concurrent
-            # call created it first, so the retry always finds a counter.
+            # call created it first.
             self.client.add(prefixed_key, b"0", exptime, noreply=False)
             value = self._add_delta(prefixed_key, delta)
-        return value
+            if value is not None:
+                return value
+            # Memcached keeps time in whole seconds, so a counter created with
+            # a short ttl can expire before the INCR that follows its ADD. It
+            # expired inside its own window, so the next window starts again
+            # at ``delta``.
+            logger.debug("Memcached INCREMENT RETRY; key=%s", prefixed_key)
+        return None
 
     async def increment(self, key: str, delta: int = 1, ttl: int | None = None) -> int:
         """Atomically add ``delta`` to the counter at ``key`` (see base class).
 
         Memcached counters are unsigned, so a negative ``delta`` uses DECR,
         which stops at 0 instead of going negative.
+
+        Creating a counter takes an ADD and then an INCR. If the new counter
+        expires in between (Memcached's clock has one-second resolution, so a
+        ``ttl=1`` counter can live for well under a second), the ADD + INCR
+        pair is retried, starting a new window at ``delta``.
+
+        Raises:
+            CacheXError: If the key holds a value that is not a counter, or
+                the counter vanished after every ADD + INCR attempt.
         """
         validate_delta(delta)
         validate_ttl(ttl)
@@ -339,7 +394,7 @@ class MemcachedBackend(BaseCacheBackend):
             msg = "Cache key holds a value that is not a counter"
             raise CacheXError(msg) from e
         if value is None:
-            msg = "Counter vanished between ADD and INCR"
+            msg = f"Counter vanished between ADD and INCR on each of {_CAS_MAX_RETRIES} attempts"
             raise CacheXError(msg)
         logger.debug("Memcached INCREMENT; key=%s value=%s ttl=%s", key, value, ttl)
         return value
@@ -392,36 +447,38 @@ class MemcachedBackend(BaseCacheBackend):
             "this namespace cannot be cleared on its own; delete known keys "
             "with delete() or delete_many() instead.",
             RuntimeWarning,
-            stacklevel=2,
+            stacklevel=_caller_stacklevel(),
         )
         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:
-        """Clear cached responses for a specific path.
+        """Delete the key that is exactly ``path``; warns on every call.
 
-        Note: Memcached does not support pattern-based queries, so this
-        only deletes the key that is exactly ``path``. HTTP route keys
-        (``method|||host|||path|||query``) are not matched. For path-based
-        clearing, use the Redis or memory backend.
+        Memcached cannot enumerate keys, so this cannot find HTTP route keys
+        (``method|||host|||path|||query``): it only deletes a key stored under
+        the literal name ``path``, and ``include_params`` has no effect. It
+        warns every time, because on this backend ``clear_path()`` after a write
+        would otherwise leave the cached response in place without a sign. Use
+        ``invalidate(request)`` to drop a ``@cache`` route's entry, or the Redis
+        or memory backend for path-based clearing.
 
         Args:
             path: The exact key to delete
-            include_params: Unsupported; emits a ``RuntimeWarning`` and is
-                otherwise ignored
+            include_params: Unsupported; ignored
 
         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,
-            )
+        warnings.warn(
+            "Memcached backend does not support pattern-based key clearing, so "
+            "clear_path() cannot remove HTTP cache entries "
+            "(method|||host|||path|||query): it only deletes a key named "
+            "exactly as the path, and include_params has no effect. Use "
+            "invalidate(request) to drop a cached route's entry.",
+            RuntimeWarning,
+            stacklevel=_caller_stacklevel(),
+        )
 
         # Try to delete the prefixed key (exact match only)
         prefixed_key = self._make_key(path)
@@ -454,7 +511,7 @@ class MemcachedBackend(BaseCacheBackend):
             "Consider using Redis backend for pattern support, "
             "or track keys manually in your application logic.",
             RuntimeWarning,
-            stacklevel=2,
+            stacklevel=_caller_stacklevel(),
         )
         logger.debug("Memcached CLEAR_PATTERN unsupported; pattern=%s", pattern)
         return 0
@@ -476,7 +533,7 @@ class MemcachedBackend(BaseCacheBackend):
             "Consider using Redis backend if you need cache monitoring, "
             "or track keys manually in your application.",
             RuntimeWarning,
-            stacklevel=2,
+            stacklevel=_caller_stacklevel(),
         )
         logger.debug("Memcached GET_ALL_KEYS unsupported; returning empty list")
         return []
@@ -495,6 +552,8 @@ class MemcachedBackend(BaseCacheBackend):
             "get_cache_data() returns an empty dictionary. "
             "Consider using Redis backend if you need cache monitoring.",
             RuntimeWarning,
+            # Called by the monitoring route, whose caller is FastAPI itself:
+            # routes.py names the source better than any frame outside it.
             stacklevel=2,
         )
         logger.debug("Memcached GET_CACHE_DATA unsupported; returning empty dict")

{fastapi_cachex-0.3.8 → fastapi_cachex-0.3.9}/fastapi_cachex/backends/memory.py

@@ -31,8 +31,10 @@ def _split_http_key(key: str) -> tuple[str, bool] | None:
 
     Keys without separators (CacheManager/StateManager keys or custom key
     builders) are not HTTP keys and are matched on their raw value instead.
+    Components after the query string (see ``build_cache_key``) do not count
+    as query params.
     """
-    parts = key.split(CACHE_KEY_SEPARATOR, _QUERY_INDEX)
+    parts = key.split(CACHE_KEY_SEPARATOR)
     if len(parts) <= _PATH_INDEX:
         return None
     has_params = len(parts) > _QUERY_INDEX and bool(parts[_QUERY_INDEX])