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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-cachex
-Version: 0.3.9
+Version: 0.4.1
 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
@@ -26,7 +26,6 @@ Requires-Dist: itsdangerous>=1.1.0
 Requires-Dist: pydantic>=2.7.0
 Requires-Dist: starlette>=1.0.0
 Requires-Dist: pyjwt>=2.9.0 ; extra == 'jwt'
-Requires-Dist: pymemcache>=4.0.0 ; extra == 'memcache'
 Requires-Dist: pymemcache>=4.0.0 ; extra == 'memcached'
 Requires-Dist: redis[hiredis]>=5.3.0 ; extra == 'redis'
 Requires-Dist: orjson>=3.4.7 ; extra == 'redis'
@@ -36,7 +35,6 @@ Project-URL: Repository, https://github.com/allen0099/FastAPI-CacheX.git
 Project-URL: Issues, https://github.com/allen0099/FastAPI-CacheX/issues
 Project-URL: Documentation, https://fastapi-cachex.readthedocs.io/
 Provides-Extra: jwt
-Provides-Extra: memcache
 Provides-Extra: memcached
 Provides-Extra: redis
 Description-Content-Type: text/markdown
@@ -57,7 +55,7 @@ Description-Content-Type: text/markdown
 
 [English](https://fastapi-cachex.readthedocs.io/en/latest/) | [繁體中文](https://fastapi-cachex.readthedocs.io/zh-tw/latest/)
 
-A high-performance caching extension for FastAPI: a server-side response cache with `Cache-Control` and `ETag` support, application-level caching, and optional session management.
+A high-performance caching extension for FastAPI: a server-side response cache with `Cache-Control` and `ETag` support, and application-level caching.
 
 **Documentation:** <https://fastapi-cachex.readthedocs.io/en/latest/> — guides and the full API reference.
 
@@ -69,9 +67,9 @@ A high-performance caching extension for FastAPI: a server-side response cache w
   your own code, with compute-on-miss `get_or_set()` and atomic store-if-absent `add()`.
 - **Backends** — in-memory, Redis and Memcached, with atomic counters,
   one-shot values and locks.
-- **Sessions (optional)** — HMAC-signed or JWT session tokens over headers,
-  bearer tokens or cookies, with sliding expiration and IP/User-Agent binding.
-- **OAuth state** — one-time state tokens for CSRF protection in OAuth/OIDC flows.
+- **Sessions and OAuth state (deprecated)**: signed session tokens and one-time
+  OAuth state tokens. Both are deprecated in 0.4.0 and removed in 0.5.0; see
+  [where to move](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_0_4/#session-state-deprecated).
 
 ## Installation
 
@@ -85,7 +83,7 @@ backends and the optional session transports ship as extras:
 | Extra | Install | Pulls in | Needed for |
 |-------|---------|----------|------------|
 | `redis` | `uv add "fastapi-cachex[redis]"` | `redis[hiredis]`, `orjson` | `AsyncRedisCacheBackend` |
-| `memcached` | `uv add "fastapi-cachex[memcached]"` | `pymemcache` | `MemcachedBackend` (the older `memcache` name still works until 0.4.0) |
+| `memcached` | `uv add "fastapi-cachex[memcached]"` | `pymemcache` | `MemcachedBackend` |
 | `jwt` | `uv add "fastapi-cachex[jwt]"` | `PyJWT` | `SessionConfig(token_format="jwt")` |
 
 Extras combine: `uv add "fastapi-cachex[redis,jwt]"`.
@@ -114,9 +112,9 @@ def build_report() -> dict:
 
 @app.get("/report")
 async def report(cache: AppCache):
-    # 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)
+    # Cache any JSON value in your own code. Concurrent misses run
+    # build_report once: get_or_set() locks by default.
+    return await cache.get_or_set("report", build_report, ttl=300)
 ```
 
 > [!IMPORTANT]
@@ -143,12 +141,12 @@ async def report(cache: AppCache):
 
 ## 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
+- [Migrating to 0.4.0](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_0_4/) — what 0.4.0 changes and how to upgrade from 0.3.x
 - [HTTP caching](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/) — the `@cache` decorator, Cache-Control directives, cache keys, invalidation and monitoring routes
 - [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
 - [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/)
+- Deprecated, removed in 0.5.0: [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/)

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

@@ -14,7 +14,7 @@
 
 [English](https://fastapi-cachex.readthedocs.io/en/latest/) | [繁體中文](https://fastapi-cachex.readthedocs.io/zh-tw/latest/)
 
-A high-performance caching extension for FastAPI: a server-side response cache with `Cache-Control` and `ETag` support, application-level caching, and optional session management.
+A high-performance caching extension for FastAPI: a server-side response cache with `Cache-Control` and `ETag` support, and application-level caching.
 
 **Documentation:** <https://fastapi-cachex.readthedocs.io/en/latest/> — guides and the full API reference.
 
@@ -26,9 +26,9 @@ A high-performance caching extension for FastAPI: a server-side response cache w
   your own code, with compute-on-miss `get_or_set()` and atomic store-if-absent `add()`.
 - **Backends** — in-memory, Redis and Memcached, with atomic counters,
   one-shot values and locks.
-- **Sessions (optional)** — HMAC-signed or JWT session tokens over headers,
-  bearer tokens or cookies, with sliding expiration and IP/User-Agent binding.
-- **OAuth state** — one-time state tokens for CSRF protection in OAuth/OIDC flows.
+- **Sessions and OAuth state (deprecated)**: signed session tokens and one-time
+  OAuth state tokens. Both are deprecated in 0.4.0 and removed in 0.5.0; see
+  [where to move](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_0_4/#session-state-deprecated).
 
 ## Installation
 
@@ -42,7 +42,7 @@ backends and the optional session transports ship as extras:
 | Extra | Install | Pulls in | Needed for |
 |-------|---------|----------|------------|
 | `redis` | `uv add "fastapi-cachex[redis]"` | `redis[hiredis]`, `orjson` | `AsyncRedisCacheBackend` |
-| `memcached` | `uv add "fastapi-cachex[memcached]"` | `pymemcache` | `MemcachedBackend` (the older `memcache` name still works until 0.4.0) |
+| `memcached` | `uv add "fastapi-cachex[memcached]"` | `pymemcache` | `MemcachedBackend` |
 | `jwt` | `uv add "fastapi-cachex[jwt]"` | `PyJWT` | `SessionConfig(token_format="jwt")` |
 
 Extras combine: `uv add "fastapi-cachex[redis,jwt]"`.
@@ -71,9 +71,9 @@ def build_report() -> dict:
 
 @app.get("/report")
 async def report(cache: AppCache):
-    # 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)
+    # Cache any JSON value in your own code. Concurrent misses run
+    # build_report once: get_or_set() locks by default.
+    return await cache.get_or_set("report", build_report, ttl=300)
 ```
 
 > [!IMPORTANT]
@@ -100,12 +100,12 @@ async def report(cache: AppCache):
 
 ## 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
+- [Migrating to 0.4.0](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_0_4/) — what 0.4.0 changes and how to upgrade from 0.3.x
 - [HTTP caching](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/) — the `@cache` decorator, Cache-Control directives, cache keys, invalidation and monitoring routes
 - [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
 - [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/)
+- Deprecated, removed in 0.5.0: [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/)

fastapi_cachex-0.4.1/fastapi_cachex/__init__.py

@@ -0,0 +1,149 @@
+"""FastAPI-CacheX: A powerful and flexible caching extension for FastAPI."""
+
+import logging
+from importlib import import_module
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version
+from typing import TYPE_CHECKING
+
+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
+from .cache_key import CacheKey as CacheKey
+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 .exceptions import BackendNotFoundError as BackendNotFoundError
+from .exceptions import CacheXError as CacheXError
+from .exceptions import LockTimeoutError as LockTimeoutError
+from .exceptions import ProxyNotSetError as ProxyNotSetError
+from .exceptions import RequestNotFoundError as RequestNotFoundError
+from .lock import CacheLock as CacheLock
+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 .types import CacheKeyBuilder as CacheKeyBuilder
+
+if TYPE_CHECKING:
+    # Type checkers see the real types; at runtime `__getattr__` loads them.
+    from .session import (
+        FastAPICacheXSessionMiddleware as FastAPICacheXSessionMiddleware,
+    )
+    from .session import Session as Session
+    from .session import SessionConfig as SessionConfig
+    from .session import SessionManager as SessionManager
+    from .session import SessionManagerProxy as SessionManagerProxy
+    from .session import SessionUser as SessionUser
+    from .session import get_optional_session as get_optional_session
+    from .session import get_session as get_session
+    from .session import get_session_manager as get_session_manager
+    from .session import require_session as require_session
+    from .session import require_user_session as require_user_session
+    from .session.exceptions import SessionError as SessionError
+    from .session.exceptions import SessionExpiredError as SessionExpiredError
+    from .session.exceptions import SessionInvalidError as SessionInvalidError
+    from .session.exceptions import SessionNotFoundError as SessionNotFoundError
+    from .session.exceptions import SessionSecurityError as SessionSecurityError
+    from .session.exceptions import SessionTokenError as SessionTokenError
+    from .state import InvalidStateError as InvalidStateError
+    from .state import StateData as StateData
+    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
+
+
+def _read_version() -> str:
+    """Return the installed distribution's version.
+
+    Importing from a source tree that was never installed leaves no metadata to
+    read; reporting a development version there is part of the contract, so this
+    lives in a function the tests can drive rather than behind a coverage pragma.
+    """
+    try:
+        return version("fastapi-cachex")
+    except PackageNotFoundError:
+        return "0.0.0.dev0"
+
+
+__version__ = _read_version()
+
+_package_logger = logging.getLogger("fastapi_cachex")
+_package_logger.addHandler(
+    logging.NullHandler()
+)  # Attach a NullHandler to avoid "No handler found" warnings in user applications.
+
+# Session and OAuth state names, deprecated in 0.4.0 and removed in 0.5.0
+# (#420). They load on first use, so `import fastapi_cachex` does not import
+# either package; importing one emits its FutureWarning. They are left out of
+# `__all__`, so `from fastapi_cachex import *` does not load them either.
+_DEPRECATED_NAMES = {
+    "FastAPICacheXSessionMiddleware": "fastapi_cachex.session",
+    "InvalidStateError": "fastapi_cachex.state",
+    "Session": "fastapi_cachex.session",
+    "SessionConfig": "fastapi_cachex.session",
+    "SessionError": "fastapi_cachex.session.exceptions",
+    "SessionExpiredError": "fastapi_cachex.session.exceptions",
+    "SessionInvalidError": "fastapi_cachex.session.exceptions",
+    "SessionManager": "fastapi_cachex.session",
+    "SessionManagerProxy": "fastapi_cachex.session",
+    "SessionNotFoundError": "fastapi_cachex.session.exceptions",
+    "SessionSecurityError": "fastapi_cachex.session.exceptions",
+    "SessionTokenError": "fastapi_cachex.session.exceptions",
+    "SessionUser": "fastapi_cachex.session",
+    "StateData": "fastapi_cachex.state",
+    "StateDataError": "fastapi_cachex.state",
+    "StateError": "fastapi_cachex.state",
+    "StateExpiredError": "fastapi_cachex.state",
+    "StateManager": "fastapi_cachex.state",
+    "StateManagerDep": "fastapi_cachex.state",
+    "StateManagerProxy": "fastapi_cachex.state",
+    "get_optional_session": "fastapi_cachex.session",
+    "get_session": "fastapi_cachex.session",
+    "get_session_manager": "fastapi_cachex.session",
+    "get_state_manager": "fastapi_cachex.state",
+    "require_session": "fastapi_cachex.session",
+    "require_user_session": "fastapi_cachex.session",
+}
+
+
+def __getattr__(name: str) -> object:
+    """Resolve a deprecated session or state name on first use."""
+    module_name = _DEPRECATED_NAMES.get(name)
+    if module_name is None:
+        msg = f"module {__name__!r} has no attribute {name!r}"
+        raise AttributeError(msg)
+    value = getattr(import_module(module_name), name)
+    globals()[name] = value
+    return value
+
+
+__all__ = [
+    "AppCache",
+    "BackendNotFoundError",
+    "BackendProxy",
+    "CacheBackend",
+    "CacheKey",
+    "CacheKeyBuilder",
+    "CacheLock",
+    "CacheManager",
+    "CacheManagerProxy",
+    "CacheXError",
+    "LockTimeoutError",
+    "ProxyNotSetError",
+    "RequestNotFoundError",
+    "__version__",
+    "add_routes",
+    "build_cache_key",
+    "cache",
+    "default_key_builder",
+    "get_app_cache",
+    "get_cache_backend",
+    "invalidate",
+]

fastapi_cachex-0.4.1/fastapi_cachex/_deprecation.py

@@ -0,0 +1,68 @@
+"""Deprecation of the session and OAuth state subsystems (#420).
+
+Both packages warn once, when they are first imported, and are removed in
+0.5.0 (#421).
+"""
+
+import inspect
+import warnings
+from types import FrameType
+
+_MIGRATION_URL = (
+    "https://fastapi-cachex.readthedocs.io/en/latest/"
+    "MIGRATING_0_4/#session-state-deprecated"
+)
+
+SESSION_DEPRECATION = (
+    "fastapi_cachex.session is deprecated and will be removed in "
+    "fastapi-cachex 0.5.0. Use Starlette's SessionMiddleware for signed-cookie "
+    f"sessions, or a dedicated session library for server-side sessions; see {_MIGRATION_URL}"
+)
+
+STATE_DEPRECATION = (
+    "fastapi_cachex.state is deprecated and will be removed in "
+    "fastapi-cachex 0.5.0. Use the state handling of your OAuth client library "
+    f"(Authlib, for example); see {_MIGRATION_URL}"
+)
+
+
+def _is_import_machinery(frame: FrameType) -> bool:
+    """Whether ``warnings.warn()`` skips ``frame`` when it counts stacklevel."""
+    filename = frame.f_code.co_filename
+    return "importlib" in filename and "_bootstrap" in filename
+
+
+def _importer_stacklevel() -> int:
+    """Return the ``stacklevel`` of the first frame outside this package.
+
+    Frames of fastapi_cachex and of the import machinery are skipped, so the
+    warning names the application's ``import`` line, or the line that read a
+    deprecated name from the ``fastapi_cachex`` package.
+    """
+    frame = inspect.currentframe()
+    if frame is None or frame.f_back is None:  # no frame support
+        return 2
+    # Level 1 is warn_deprecated(); start at its caller.
+    level, frame = 2, frame.f_back.f_back
+    while frame is not None:
+        module = frame.f_globals.get("__name__", "")
+        if not module.startswith(("fastapi_cachex.", "importlib.")) and module not in {
+            "fastapi_cachex",
+            "importlib",
+        }:
+            break
+        # warnings.warn() does not count the frozen import machinery's frames
+        # towards stacklevel, so neither may this.
+        if not _is_import_machinery(frame):
+            level += 1
+        frame = frame.f_back
+    return level
+
+
+def warn_deprecated(message: str) -> None:
+    """Emit the ``FutureWarning`` for a deprecated subsystem.
+
+    ``FutureWarning`` rather than ``DeprecationWarning``: it is shown by
+    default, and the removal affects the application, not only its tests.
+    """
+    warnings.warn(message, FutureWarning, stacklevel=_importer_stacklevel())

fastapi_cachex-0.4.1/fastapi_cachex/_warnings.py

@@ -0,0 +1,25 @@
+"""Point a warning at the application's line rather than the library's (#333)."""
+
+import inspect
+
+
+def caller_stacklevel() -> int:
+    """Return the ``stacklevel`` of the first frame outside fastapi_cachex.
+
+    For a ``warnings.warn`` in the function that calls this. The depth of a
+    library call varies (a backend method called directly, through
+    ``CacheManager`` or through a base-class fallback), so a fixed
+    ``stacklevel`` names a library file on some paths.
+    """
+    frame = inspect.currentframe()
+    if frame is None or frame.f_back is None:  # no frame support
+        return 2
+    # Level 1 is the function 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

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

@@ -8,7 +8,10 @@ from types import TracebackType
 from typing import TYPE_CHECKING
 from typing import Any
 
+from fastapi_cachex._warnings import caller_stacklevel
+from fastapi_cachex.exceptions import CacheXError
 from fastapi_cachex.types import CACHE_KEY_SEPARATOR
+from fastapi_cachex.types import HTTP_KEY_FORMAT_TAG
 from fastapi_cachex.types import CacheEntry
 from fastapi_cachex.types import counter_entry
 from fastapi_cachex.types import counter_value
@@ -30,13 +33,14 @@ def warn_if_path_shaped(pattern: str, cleared: int) -> None:
     paths (stored directly through ``set``) stay silent when they work.
     """
     if cleared == 0 and pattern.startswith("/") and CACHE_KEY_SEPARATOR not in pattern:
+        sep = CACHE_KEY_SEPARATOR
         warnings.warn(
             f"clear_pattern({pattern!r}) cleared nothing. Patterns match whole "
-            f"cache keys, which look like 'method{CACHE_KEY_SEPARATOR}host"
-            f"{CACHE_KEY_SEPARATOR}path{CACHE_KEY_SEPARATOR}query', so a bare "
-            "path matches no HTTP cache entry. Use clear_path(path, "
-            "include_params=True) to clear by path, or write the whole key out "
-            f"as 'GET{CACHE_KEY_SEPARATOR}*{CACHE_KEY_SEPARATOR}{pattern}'.",
+            f"cache keys, which look like '{HTTP_KEY_FORMAT_TAG}{sep}method{sep}"
+            f"host{sep}path{sep}query', so a bare path matches no HTTP cache "
+            "entry. Use clear_path(path, include_params=True) to clear by "
+            "path, or write the whole key out as "
+            f"'{HTTP_KEY_FORMAT_TAG}{sep}GET{sep}*{sep}{pattern}{sep}*'.",
             RuntimeWarning,
             stacklevel=3,
         )
@@ -95,6 +99,18 @@ def validate_delta(delta: int) -> int:
     return delta
 
 
+def check_counter_range(value: int) -> int:
+    """Return ``value`` if a signed 64-bit counter can hold it.
+
+    Raises:
+        CacheXError: If ``value`` is outside the signed 64-bit range
+    """
+    if not -(2**63) <= value < 2**63:
+        msg = "Counter increment would overflow a signed 64-bit integer"
+        raise CacheXError(msg)
+    return value
+
+
 class BaseCacheBackend(ABC):
     """Base class for all cache backends.
 
@@ -138,23 +154,50 @@ class BaseCacheBackend(ABC):
         """
 
     @abstractmethod
-    async def delete(self, key: str) -> None:
-        """Remove a response from the cache."""
+    async def delete(self, key: str) -> bool:
+        """Remove a response from the cache.
+
+        Returns:
+            Whether ``key`` held an entry that had not expired yet
+        """
 
     async def delete_many(self, keys: Iterable[str]) -> int:
         """Remove every key in ``keys``; returns how many were removed.
 
-        The base implementation deletes one key at a time and reports how
-        many were attempted, since ``delete`` does not say whether the key
-        existed. The built-in backends override it and count what was
-        actually removed.
+        The base implementation deletes one key at a time and counts the
+        deletes that found an entry. The built-in backends override it with
+        batched deletes.
         """
         count = 0
         for key in keys:
-            await self.delete(key)
-            count += 1
+            if await self._delete_reporting(key):
+                count += 1
         return count
 
+    async def _delete_reporting(self, key: str) -> bool:
+        """Call ``delete`` for the fallbacks, accepting a 0.3.x ``None`` result.
+
+        ``delete`` returned ``None`` before 0.4.0, and a third-party backend
+        written then may still do so. ``None`` counts as removed, as every
+        fallback assumed in 0.3.x, and warns: 0.5.0 will treat it as ``False``.
+        ``FutureWarning`` rather than ``DeprecationWarning``: the warning is
+        raised inside the package, where a ``DeprecationWarning`` is hidden by
+        default, and the change affects the application at runtime.
+        """
+        result: object = await self.delete(key)
+        if result is None:
+            warnings.warn(
+                f"{type(self).__name__}.delete() returned None. Since "
+                "fastapi-cachex 0.4.0 it must return whether the key was "
+                "removed; None is counted as removed until 0.5.0, which treats "
+                "it as False. See https://fastapi-cachex.readthedocs.io/en/"
+                "stable/MIGRATING_0_4/#backend-delete",
+                FutureWarning,
+                stacklevel=caller_stacklevel(),
+            )
+            return True
+        return bool(result)
+
     async def get_and_delete(self, key: str) -> CacheEntry | None:
         """Atomically retrieve and remove a cached entry.
 
@@ -170,8 +213,10 @@ class BaseCacheBackend(ABC):
             The entry that was stored under ``key``, or ``None`` if there was none
         """
         value = await self.get(key)
-        if value is not None:
-            await self.delete(key)
+        if value is None or not await self._delete_reporting(key):
+            # Absent, or another caller removed it between the get and the
+            # delete: that caller got the entry.
+            return None
         return value
 
     async def set_if_absent(
@@ -224,8 +269,7 @@ class BaseCacheBackend(ABC):
         """
         if await self.get(key) != expected:
             return False
-        await self.delete(key)
-        return True
+        return await self._delete_reporting(key)
 
     async def expire_if_equals(self, key: str, expected: CacheEntry, ttl: int) -> bool:
         """Update expiry on ``key`` to ``ttl`` seconds only while it still holds ``expected``.
@@ -253,6 +297,39 @@ class BaseCacheBackend(ABC):
         await self.set(key, expected, ttl=ttl)
         return True
 
+    async def set_if_equals(
+        self,
+        key: str,
+        expected: CacheEntry,
+        value: CacheEntry,
+        ttl: int | None = None,
+    ) -> bool:
+        """Store ``value`` only while ``key`` still holds ``expected``.
+
+        A compare-and-set: a caller that read ``expected`` earlier overwrites
+        it only if nothing changed, deleted or expired the key since. Sessions
+        save through it, so a request that loaded a session cannot bring it
+        back after another request deleted or invalidated it.
+
+        The base implementation is a best-effort, NON-atomic get-compare-set
+        fallback for third-party backends; the built-in backends override it
+        with an atomic implementation.
+
+        Args:
+            key: Cache key to overwrite
+            expected: The entry the caller last read or wrote (compared with ``==``)
+            value: Entry to store in its place
+            ttl: Time to live in seconds (``None`` = never expires)
+
+        Returns:
+            Whether ``value`` was stored
+        """
+        validate_ttl(ttl)
+        if await self.get(key) != expected:
+            return False
+        await self.set(key, value, ttl=ttl)
+        return True
+
     async def increment(self, key: str, delta: int = 1, ttl: int | None = None) -> int:
         """Atomically add ``delta`` to the integer counter stored at ``key``.
 
@@ -277,7 +354,10 @@ class BaseCacheBackend(ABC):
             The counter value after the increment
 
         Raises:
-            CacheXError: If ``key`` holds a cached response instead of a counter
+            CacheXError: If ``key`` holds a cached response instead of a
+                counter, or the result would leave the counter's range: signed
+                64-bit, except on Memcached, whose counters are unsigned 64-bit.
+                The counter is left unchanged.
             TypeError: If ``delta`` or ``ttl`` is not an ``int``
             ValueError: If ``ttl`` is out of range, or ``delta`` does not fit
                 in a signed 64-bit integer
@@ -286,6 +366,7 @@ class BaseCacheBackend(ABC):
         validate_ttl(ttl)
         current = await self.get(key)
         value = delta if current is None else counter_value(current) + delta
+        check_counter_range(value)
         await self.set(key, counter_entry(value), ttl=ttl)
         return value
 
@@ -311,10 +392,11 @@ class BaseCacheBackend(ABC):
 
         The pattern is matched against the whole logical key — the key as the
         caller sees it, without whatever prefix the backend adds internally.
-        HTTP cache keys are ``method|||host|||path|||query``, so matching a
-        path means writing the other components out::
+        HTTP cache keys are ``http:v2|method|host|path|query`` (see
+        ``CacheKey``), so matching a path means writing the other components
+        out::
 
-            await backend.clear_pattern("GET|||*|||/users/*")
+            await backend.clear_pattern("http:v2|GET|*|/users/*")
             await backend.clear_pattern("cache:user:*")  # a CacheManager key
 
         To clear by path, prefer ``clear_path(path, include_params=...)``: it

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

@@ -46,7 +46,7 @@ def encode_entry(entry: CacheEntry) -> bytes:
             "content": entry.content.decode("latin-1"),
             "media_type": entry.media_type,
             "status_code": entry.status_code,
-            "headers": entry.headers,
+            "headers": [[name, value] for name, value in entry.headers],
             "stored_at": entry.stored_at,
         },
     )
@@ -72,7 +72,9 @@ def decode_entry(raw: str | bytes | None) -> CacheEntry | None:
 
     Documents written before entries carried a status code and headers simply
     lack those keys and decode to a plain ``200`` with no extra headers; those
-    written before entries carried ``stored_at`` decode with ``None``.
+    written before entries carried ``stored_at`` decode with ``None``. Headers
+    are a list of ``[name, value]`` lines; the object 0.3.x wrote (one value
+    per name) is still read.
     """
     if raw is None:
         return None

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

@@ -16,14 +16,6 @@ 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=(
-            "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"
     )