fastapi-cachex 0.5.0__tar.gz → 0.5.1__tar.gz

{fastapi_cachex-0.5.0 → fastapi_cachex-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-cachex
-Version: 0.5.0
+Version: 0.5.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

{fastapi_cachex-0.5.0 → fastapi_cachex-0.5.1}/fastapi_cachex/__init__.py

@@ -16,10 +16,14 @@ 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 BackendUnavailableError as BackendUnavailableError
 from .exceptions import CacheXError as CacheXError
+from .exceptions import InvalidTTLError as InvalidTTLError
 from .exceptions import LockTimeoutError as LockTimeoutError
 from .exceptions import ProxyNotSetError as ProxyNotSetError
 from .exceptions import RequestNotFoundError as RequestNotFoundError
+from .exceptions import TTLTypeError as TTLTypeError
+from .exceptions import TTLValueError as TTLValueError
 from .lock import CacheLock as CacheLock
 from .manager import CacheManager as CacheManager
 from .manager_proxy import CacheManagerProxy as CacheManagerProxy
@@ -52,6 +56,7 @@ __all__ = [
     "AppCache",
     "BackendNotFoundError",
     "BackendProxy",
+    "BackendUnavailableError",
     "CacheBackend",
     "CacheKey",
     "CacheKeyBuilder",
@@ -60,9 +65,12 @@ __all__ = [
     "CacheManagerProxy",
     "CacheXError",
     "CachedFunction",
+    "InvalidTTLError",
     "LockTimeoutError",
     "ProxyNotSetError",
     "RequestNotFoundError",
+    "TTLTypeError",
+    "TTLValueError",
     "__version__",
     "add_routes",
     "build_cache_key",

fastapi_cachex-0.5.1/fastapi_cachex/backends/_unavailable.py

@@ -0,0 +1,100 @@
+"""Turn a network backend's transport failures into ``BackendUnavailableError``.
+
+The Redis and Memcached clients each raise their own exceptions when the
+server cannot be reached: ``redis.exceptions.ConnectionError`` and
+``TimeoutError``, socket errors, pymemcache's "All servers seem to be down".
+A caller that only wants to know "the cache is down" would have to know which
+backend is configured and import that client's exceptions (#260).
+
+The backends' methods are wrapped so that such an error is raised again as a
+``BackendUnavailableError`` chained to the original. The class raised is
+built per original type and inherits from both, so it is also the original
+type: an ``except redis.exceptions.ConnectionError`` or ``except OSError``
+written before keeps catching it, and ``except BackendUnavailableError`` now
+works on every backend.
+"""
+
+import functools
+from collections.abc import Callable
+from collections.abc import Coroutine
+from typing import Any
+from typing import ParamSpec
+from typing import TypeVar
+from typing import cast
+
+from fastapi_cachex.exceptions import BackendUnavailableError
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+_SUBCLASSES: dict[type[Exception], type[BackendUnavailableError]] = {}
+
+
+def _rebuild(error_type: type[Exception], args: tuple[Any, ...]) -> Exception:
+    """Unpickle a translated error: pickle cannot import a runtime class."""
+    return _subclass_for(error_type)(*args)
+
+
+def _reduce(self: BaseException) -> tuple[Any, ...]:
+    return _rebuild, (type(self).__bases__[1], self.args), self.__dict__ or None
+
+
+def _subclass_for(error_type: type[Exception]) -> type[BackendUnavailableError]:
+    """The ``BackendUnavailableError`` that is also an ``error_type``."""
+    subclass = _SUBCLASSES.get(error_type)
+    if subclass is None:
+        # Named like its base, so a traceback reads BackendUnavailableError;
+        # the chained original below it names the client's own exception.
+        subclass = cast(
+            "type[BackendUnavailableError]",
+            type(
+                "BackendUnavailableError",
+                (BackendUnavailableError, error_type),
+                {
+                    "__module__": BackendUnavailableError.__module__,
+                    "__qualname__": BackendUnavailableError.__qualname__,
+                    "__doc__": BackendUnavailableError.__doc__,
+                    "__reduce__": _reduce,
+                },
+            ),
+        )
+        _SUBCLASSES[error_type] = subclass
+    return subclass
+
+
+def as_unavailable(error: Exception) -> BackendUnavailableError:
+    """``error`` as a ``BackendUnavailableError`` that is also its own type."""
+    subclass = _subclass_for(type(error))
+    try:
+        translated = subclass(*error.args)
+    except Exception:  # noqa: BLE001 - a constructor that wants other arguments
+        translated = subclass(str(error))
+    translated.__dict__.update(error.__dict__)
+    return translated
+
+
+def translate_unavailable(
+    is_unavailable: Callable[[Exception], bool],
+) -> Callable[
+    [Callable[P, Coroutine[Any, Any, R]]], Callable[P, Coroutine[Any, Any, R]]
+]:
+    """A decorator raising the errors ``is_unavailable`` accepts as unavailable."""
+
+    def decorator(
+        func: Callable[P, Coroutine[Any, Any, R]],
+    ) -> Callable[P, Coroutine[Any, Any, R]]:
+        @functools.wraps(func)
+        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            try:
+                return await func(*args, **kwargs)
+            except BackendUnavailableError:
+                # Already translated by a wrapped method this one called.
+                raise
+            except Exception as e:
+                if not is_unavailable(e):
+                    raise
+                raise as_unavailable(e) from e
+
+        return wrapper
+
+    return decorator

{fastapi_cachex-0.5.0 → fastapi_cachex-0.5.1}/fastapi_cachex/backends/base.py

@@ -11,6 +11,8 @@ from typing import Any
 from typing import overload
 
 from fastapi_cachex.exceptions import CacheXError
+from fastapi_cachex.exceptions import TTLTypeError
+from fastapi_cachex.exceptions import TTLValueError
 from fastapi_cachex.types import CACHE_KEY_SEPARATOR
 from fastapi_cachex.types import HTTP_KEY_FORMAT_TAG
 from fastapi_cachex.types import CacheEntry
@@ -75,10 +77,11 @@ def validate_ttl(ttl: int | timedelta | None) -> int | None:
     backend stores.
 
     Raises:
-        TypeError: If ``ttl`` is not an ``int`` or a ``timedelta`` (``bool``
-            included)
-        ValueError: If ``ttl`` is zero, negative, larger than ``MAX_TTL`` or
-            a ``timedelta`` that is not a whole number of seconds
+        TTLTypeError: If ``ttl`` is not an ``int`` or a ``timedelta``
+            (``bool`` included); also a ``TypeError``
+        TTLValueError: If ``ttl`` is zero, negative, larger than ``MAX_TTL``
+            or a ``timedelta`` that is not a whole number of seconds; also a
+            ``ValueError``
     """
     if ttl is None:
         return None
@@ -89,13 +92,13 @@ def validate_ttl(ttl: int | timedelta | None) -> int | None:
             "ttl must be an int number of seconds, a timedelta or None, "
             f"got {type(ttl).__name__}"
         )
-        raise TypeError(msg)
+        raise TTLTypeError(msg)
     if ttl <= 0:
         msg = f"ttl must be a positive number of seconds or None, got {ttl!r}"
-        raise ValueError(msg)
+        raise TTLValueError(msg)
     if ttl > MAX_TTL:
         msg = f"ttl must be at most {MAX_TTL} seconds (about 68 years)"
-        raise ValueError(msg)
+        raise TTLValueError(msg)
     return ttl
 
 
@@ -103,11 +106,11 @@ def _whole_seconds(value: timedelta, name: str) -> int:
     """The whole number of seconds in ``value``.
 
     Raises:
-        ValueError: If ``value`` has a fraction of a second
+        TTLValueError: If ``value`` has a fraction of a second
     """
     if value.microseconds:
         msg = f"{name} must be a whole number of seconds, got {value!r}"
-        raise ValueError(msg)
+        raise TTLValueError(msg)
     return int(value.total_seconds())
 
 

{fastapi_cachex-0.5.0 → fastapi_cachex-0.5.1}/fastapi_cachex/backends/memcached.py

@@ -12,14 +12,38 @@ from fastapi_cachex._warnings import caller_stacklevel
 from fastapi_cachex.backends.codec import decode_entry
 from fastapi_cachex.backends.codec import encode_entry
 from fastapi_cachex.exceptions import CacheXError
+from fastapi_cachex.exceptions import TTLValueError
 from fastapi_cachex.types import CacheEntry
 
+from ._unavailable import translate_unavailable
 from .base import BaseCacheBackend
 from .base import validate_delta
 from .base import validate_ttl
 
 logger = logging.getLogger(__name__)
 
+# What pymemcache's HashClient raises while every server is out of rotation.
+_ALL_SERVERS_DOWN = "All servers seem to be down"
+
+
+def _is_unavailable(error: Exception) -> bool:
+    """Whether ``error`` means no Memcached server could be reached.
+
+    A socket error (refused, reset, timed out), a connection the server
+    closed mid-reply, and pymemcache's "All servers seem to be down" while a
+    failed server is out of rotation. A ``MemcacheClientError`` (bad input,
+    an item over the size limit) is not about availability and is left as is.
+    """
+    from pymemcache.exceptions import MemcacheError
+    from pymemcache.exceptions import MemcacheUnexpectedCloseError
+
+    if isinstance(error, (OSError, MemcacheUnexpectedCloseError)):
+        return True
+    return type(error) is MemcacheError and _ALL_SERVERS_DOWN in str(error)
+
+
+_unavailable = translate_unavailable(_is_unavailable)
+
 # Default Memcached key prefix for fastapi-cachex
 DEFAULT_MEMCACHE_PREFIX = "fastapi_cachex:"
 
@@ -88,8 +112,9 @@ def _expiry(ttl: int | None) -> int:
     in 1970 and expire the entry immediately. ``None`` means no expiry.
 
     Raises:
-        ValueError: If the expiry would fall after 2038-01-19, which Memcached
-            cannot represent: it would accept the write and drop the item.
+        TTLValueError: If the expiry would fall after 2038-01-19, which
+            Memcached cannot represent: it would accept the write and drop the
+            item. Also a ``ValueError``.
     """
     if ttl is None:
         return 0
@@ -100,7 +125,7 @@ def _expiry(ttl: int | None) -> int:
                 f"ttl {ttl!r} expires after 2038-01-19, which Memcached cannot "
                 "store; use a shorter ttl or None"
             )
-            raise ValueError(msg)
+            raise TTLValueError(msg)
         return expires_at
     return ttl
 
@@ -200,6 +225,7 @@ class MemcachedBackend(BaseCacheBackend):
         logger.debug("Memcached key hashed; key=%s digest=%s", key, digest)
         return f"{self.key_prefix}{digest}"
 
+    @_unavailable
     async def get(self, key: str) -> CacheEntry | None:
         """Get value from cache.
 
@@ -219,6 +245,7 @@ class MemcachedBackend(BaseCacheBackend):
             logger.debug("Memcached HIT; key=%s", key)
         return value
 
+    @_unavailable
     async def set(
         self, key: str, value: CacheEntry, ttl: int | timedelta | None = None
     ) -> None:
@@ -235,6 +262,7 @@ class MemcachedBackend(BaseCacheBackend):
         )
         logger.debug("Memcached SET; key=%s ttl=%s", key, ttl)
 
+    @_unavailable
     async def get_and_delete(self, key: str) -> CacheEntry | None:
         """Atomically retrieve and remove a cached entry (see base class).
 
@@ -273,6 +301,7 @@ class MemcachedBackend(BaseCacheBackend):
         msg = f"Memcached get_and_delete exceeded {_CAS_MAX_RETRIES} attempts on key {key!r}"
         raise CacheXError(msg)
 
+    @_unavailable
     async def set_if_absent(
         self, key: str, value: CacheEntry, ttl: int | timedelta | None = None
     ) -> bool:
@@ -296,6 +325,7 @@ class MemcachedBackend(BaseCacheBackend):
         )
         return bool(stored)
 
+    @_unavailable
     async def delete_if_equals(self, key: str, expected: CacheEntry) -> bool:
         """Atomically remove ``key`` while it holds ``expected`` (see base class).
 
@@ -321,6 +351,7 @@ class MemcachedBackend(BaseCacheBackend):
         )
         return bool(deleted)
 
+    @_unavailable
     async def expire_if_equals(
         self, key: str, expected: CacheEntry, ttl: int | timedelta
     ) -> bool:
@@ -354,6 +385,7 @@ class MemcachedBackend(BaseCacheBackend):
         )
         return bool(updated)
 
+    @_unavailable
     async def set_if_equals(
         self,
         key: str,
@@ -449,6 +481,7 @@ class MemcachedBackend(BaseCacheBackend):
             logger.debug("Memcached INCREMENT RETRY; key=%s", prefixed_key)
         return None
 
+    @_unavailable
     async def increment(
         self, key: str, delta: int = 1, ttl: int | timedelta | None = None
     ) -> int:
@@ -489,6 +522,7 @@ class MemcachedBackend(BaseCacheBackend):
         logger.debug("Memcached INCREMENT; key=%s value=%s ttl=%s", key, value, ttl)
         return value
 
+    @_unavailable
     async def delete(self, key: str) -> bool:
         """Delete value from cache.
 
@@ -505,6 +539,7 @@ class MemcachedBackend(BaseCacheBackend):
         logger.debug("Memcached DELETE; key=%s removed=%s", key, removed)
         return removed
 
+    @_unavailable
     async def delete_many(self, keys: Iterable[str]) -> int:
         """Remove every key in ``keys`` in one worker call; returns how many existed.
 
@@ -529,6 +564,7 @@ class MemcachedBackend(BaseCacheBackend):
             bool(self.client.delete(key, noreply=False)) for key in prefixed_keys
         )
 
+    @_unavailable
     async def clear(self) -> None:
         """Clear all values from cache.
 
@@ -548,6 +584,7 @@ class MemcachedBackend(BaseCacheBackend):
         await asyncio.to_thread(self.client.flush_all)
         logger.debug("Memcached CLEAR; flush_all issued")
 
+    @_unavailable
     async def clear_path(self, path: str, include_params: bool = False) -> int:
         """Delete the key that is exactly ``path``; warns on every call.
 
@@ -586,6 +623,7 @@ class MemcachedBackend(BaseCacheBackend):
         )
         return removed
 
+    @_unavailable
     async def clear_pattern(self, pattern: str) -> int:
         """Clear cached responses matching a pattern.
 
@@ -609,6 +647,7 @@ class MemcachedBackend(BaseCacheBackend):
         logger.debug("Memcached CLEAR_PATTERN unsupported; pattern=%s", pattern)
         return 0
 
+    @_unavailable
     async def get_all_keys(self) -> list[str]:
         """Get all cache keys in the backend.
 
@@ -631,6 +670,7 @@ class MemcachedBackend(BaseCacheBackend):
         logger.debug("Memcached GET_ALL_KEYS unsupported; returning empty list")
         return []
 
+    @_unavailable
     async def get_cache_data(self) -> dict[str, tuple[CacheEntry, float | None]]:
         """Get all cache data with expiry information.
 

{fastapi_cachex-0.5.0 → fastapi_cachex-0.5.1}/fastapi_cachex/backends/redis.py

@@ -17,6 +17,7 @@ from fastapi_cachex.cache_key import escape_glob
 from fastapi_cachex.exceptions import CacheXError
 from fastapi_cachex.types import CacheEntry
 
+from ._unavailable import translate_unavailable
 from .base import BaseCacheBackend
 from .base import validate_delta
 from .base import validate_ttl
@@ -27,6 +28,21 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
+
+def _is_unavailable(error: Exception) -> bool:
+    """Whether ``error`` means the Redis server could not be reached.
+
+    redis-py's ``ConnectionError`` (its subclasses included) and
+    ``TimeoutError``, and a socket error that reaches the caller unwrapped.
+    """
+    from redis.exceptions import ConnectionError as RedisConnectionError
+    from redis.exceptions import TimeoutError as RedisTimeoutError
+
+    return isinstance(error, (RedisConnectionError, RedisTimeoutError, OSError))
+
+
+_unavailable = translate_unavailable(_is_unavailable)
+
 # PTTL replies that are not a remaining lifetime.
 _PTTL_NO_EXPIRY = -1
 _PTTL_MISSING = -2
@@ -300,12 +316,14 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
             deleted += await self.client.delete(*keys[i : i + _BATCH_SIZE])
         return deleted
 
+    @_unavailable
     async def get(self, key: str) -> CacheEntry | None:
         """Retrieve a cached response."""
         value = decode_entry(await self.client.get(self._make_key(key)))
         logger.debug("Redis %s; key=%s", "HIT" if value else "MISS", key)
         return value
 
+    @_unavailable
     async def set(
         self, key: str, value: CacheEntry, ttl: int | timedelta | None = None
     ) -> None:
@@ -314,18 +332,21 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         await self.client.set(self._make_key(key), encode_entry(value), ex=ttl)
         logger.debug("Redis SET; key=%s ttl=%s", key, ttl)
 
+    @_unavailable
     async def delete(self, key: str) -> bool:
         """Remove a response from the cache; returns whether the key existed."""
         removed = bool(await self.client.delete(self._make_key(key)))
         logger.debug("Redis DELETE; key=%s removed=%s", key, removed)
         return removed
 
+    @_unavailable
     async def delete_many(self, keys: Iterable[str]) -> int:
         """Remove every key in ``keys`` with batched DELs; returns how many existed."""
         removed = await self._delete_keys([self._make_key(key) for key in keys])
         logger.debug("Redis DELETE_MANY; removed=%s", removed)
         return removed
 
+    @_unavailable
     async def get_and_delete(self, key: str) -> CacheEntry | None:
         """Atomically retrieve and remove a cached entry (see base class).
 
@@ -335,6 +356,7 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         logger.debug("Redis GETDEL %s; key=%s", "HIT" if value else "MISS", key)
         return value
 
+    @_unavailable
     async def set_if_absent(
         self, key: str, value: CacheEntry, ttl: int | timedelta | None = None
     ) -> bool:
@@ -354,6 +376,7 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         )
         return bool(stored)
 
+    @_unavailable
     async def delete_if_equals(self, key: str, expected: CacheEntry) -> bool:
         """Atomically remove ``key`` while it holds ``expected`` (see base class).
 
@@ -372,6 +395,7 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         )
         return bool(deleted)
 
+    @_unavailable
     async def expire_if_equals(
         self, key: str, expected: CacheEntry, ttl: int | timedelta
     ) -> bool:
@@ -398,6 +422,7 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         )
         return bool(updated)
 
+    @_unavailable
     async def set_if_equals(
         self,
         key: str,
@@ -428,6 +453,7 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         )
         return bool(stored)
 
+    @_unavailable
     async def increment(
         self, key: str, delta: int = 1, ttl: int | timedelta | None = None
     ) -> int:
@@ -455,6 +481,7 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         logger.debug("Redis INCREMENT; key=%s value=%s ttl=%s", key, value, ttl)
         return int(value)
 
+    @_unavailable
     async def clear(self) -> None:
         """Clear all cached responses for this namespace.
 
@@ -463,6 +490,7 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         removed = await self._delete_matching(f"{self._prefix_pattern}*")
         logger.debug("Redis CLEAR; removed=%s", removed)
 
+    @_unavailable
     async def clear_path(self, path: str, include_params: bool = False) -> int:
         """Clear cached responses for a specific path.
 
@@ -501,6 +529,7 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         )
         return cleared_count
 
+    @_unavailable
     async def clear_pattern(self, pattern: str) -> int:
         """Clear cached responses matching a pattern.
 
@@ -524,6 +553,7 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         )
         return cleared_count
 
+    @_unavailable
     async def get_all_keys(self) -> list[str]:
         """Get all cache keys in the backend.
 
@@ -535,6 +565,7 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         logger.debug("Redis GET_ALL_KEYS; count=%s", len(logical_keys))
         return logical_keys
 
+    @_unavailable
     async def get_cache_data(self) -> dict[str, tuple[CacheEntry, float | None]]:
         """Get all cache data with expiry information.
 

{fastapi_cachex-0.5.0 → fastapi_cachex-0.5.1}/fastapi_cachex/cache.py

@@ -58,6 +58,8 @@ from .directives import DirectiveType
 from .exceptions import BackendNotFoundError
 from .exceptions import CacheXError
 from .exceptions import RequestNotFoundError
+from .exceptions import TTLTypeError
+from .exceptions import TTLValueError
 from .headers import add_vary
 from .proxy import BackendProxy
 from .proxy import get_backend_or_fallback
@@ -378,16 +380,19 @@ def _seconds(name: str, value: int | timedelta | None) -> int | None:
     does not use ``validate_ttl``; the type and range rules are the same.
 
     Raises:
-        CacheXError: If ``value`` is not an ``int`` or a ``timedelta``, is
-            negative, is larger than ``MAX_TTL`` or is a ``timedelta`` that
-            is not a whole number of seconds
+        TTLTypeError: If ``value`` is not an ``int`` or a ``timedelta``
+        TTLValueError: If ``value`` is negative, is larger than ``MAX_TTL`` or
+            is a ``timedelta`` that is not a whole number of seconds
+
+    Both are ``CacheXError`` subclasses, which ``@cache`` raised before, and
+    the same classes the backends raise (#337).
     """
     if value is None:
         return None
     if isinstance(value, timedelta):
         if value.microseconds:
             msg = f"{name} must be a whole number of seconds, got {value!r}"
-            raise CacheXError(msg)
+            raise TTLValueError(msg)
         value = int(value.total_seconds())
     elif isinstance(value, bool) or not isinstance(value, int):
         # Checked here: at request time the backend would reject it, and
@@ -396,13 +401,13 @@ def _seconds(name: str, value: int | timedelta | None) -> int | None:
             f"{name} must be an int number of seconds or a timedelta, "
             f"got {type(value).__name__}"
         )
-        raise CacheXError(msg)
+        raise TTLTypeError(msg)
     if value < 0:
         msg = f"{name} must not be negative"
-        raise CacheXError(msg)
+        raise TTLValueError(msg)
     if value > MAX_TTL:
         msg = f"{name} must be at most {MAX_TTL} seconds"
-        raise CacheXError(msg)
+        raise TTLValueError(msg)
     return value
 
 

{fastapi_cachex-0.5.0 → fastapi_cachex-0.5.1}/fastapi_cachex/cached.py

@@ -232,12 +232,13 @@ def cached(
         A decorator turning the function into a ``CachedFunction``
 
     Raises:
-        TypeError: When the decorator is applied, if ``ttl`` is not an
-            ``int``, a ``timedelta`` or ``None``, or ``lock`` is not a
-            ``bool`` or ``None``
-        ValueError: When the decorator is applied, if ``ttl`` is zero,
+        TTLTypeError: When the decorator is applied, if ``ttl`` is not an
+            ``int``, a ``timedelta`` or ``None`` (also a ``TypeError``)
+        TTLValueError: When the decorator is applied, if ``ttl`` is zero,
             negative, larger than ``MAX_TTL`` or not a whole number of
-            seconds
+            seconds (also a ``ValueError``)
+        TypeError: When the decorator is applied, if ``lock`` is not a
+            ``bool`` or ``None``
         CacheXError: When the decorator is applied, if ``key`` is not a
             ``str``, a callable or ``None``; and when the function is
             called, if the key cannot be built (see ``cache_key``)

fastapi_cachex-0.5.1/fastapi_cachex/exceptions.py

@@ -0,0 +1,64 @@
+"""Custom exception classes for FastAPI-CacheX."""
+
+
+class CacheXError(Exception):
+    """Base class for all exceptions in FastAPI-CacheX."""
+
+
+class BackendNotFoundError(CacheXError):
+    """Exception raised when a cache backend is not found."""
+
+
+class ProxyNotSetError(BackendNotFoundError):
+    """Exception raised when a manager proxy has no instance set.
+
+    Raised by ``CacheManagerProxy``. It subclasses ``BackendNotFoundError``,
+    which the manager proxies raised before 0.3.8, so existing handlers keep
+    catching it.
+    """
+
+
+class RequestNotFoundError(CacheXError):
+    """Exception raised when a request is not found."""
+
+
+class BackendUnavailableError(CacheXError):
+    """The cache backend's server could not be reached.
+
+    Raised by the Redis and Memcached backends for a transport failure: a
+    refused or reset connection, a timeout, or a server out of rotation. It is
+    chained to the client's own exception (``raise ... from``). The instance
+    raised is also of that exception's type, so an ``except`` clause naming
+    the client's exception (``redis.exceptions.ConnectionError``,
+    ``OSError``) keeps catching it (#260). The memory backend never raises it.
+    """
+
+
+class InvalidTTLError(CacheXError):
+    """An invalid ``ttl``, wherever it is passed.
+
+    Raised for a ``ttl`` (or ``stale_ttl``, ``default_ttl``, ``lock_ttl``)
+    that ``@cache``, ``@cached``, a backend, ``CacheManager`` or ``CacheLock``
+    refuses. Catch this class to handle all of them; the subclasses keep the
+    built-in exception each place raised before (#337).
+    """
+
+
+class TTLTypeError(InvalidTTLError, TypeError):
+    """A ``ttl`` that is not an ``int`` or a ``timedelta`` (``bool`` included).
+
+    Also a ``TypeError``, which the backends, ``CacheManager`` and
+    ``CacheLock`` raised before 0.5.1.
+    """
+
+
+class TTLValueError(InvalidTTLError, ValueError):
+    """A ``ttl`` out of range, or a ``timedelta`` with a fraction of a second.
+
+    Also a ``ValueError``, which the backends, ``CacheManager`` and
+    ``CacheLock`` raised before 0.5.1.
+    """
+
+
+class LockTimeoutError(CacheXError, TimeoutError):
+    """Exception raised when acquiring a lock or waiting for stampede protection times out."""

{fastapi_cachex-0.5.0 → fastapi_cachex-0.5.1}/fastapi_cachex/lock.py

@@ -48,9 +48,10 @@ class CacheLock:
         key_prefix: Prefix for lock keys (default: "lock:")
 
     Raises:
-        TypeError: If ``ttl`` is not an ``int`` or a ``timedelta``
-        ValueError: If ``ttl`` is zero, negative, larger than ``MAX_TTL`` or
-            not a whole number of seconds
+        TTLTypeError: If ``ttl`` is not an ``int`` or a ``timedelta`` (also
+            a ``TypeError``)
+        TTLValueError: If ``ttl`` is zero, negative, larger than ``MAX_TTL``
+            or not a whole number of seconds (also a ``ValueError``)
     """
 
     def __init__(

{fastapi_cachex-0.5.0 → fastapi_cachex-0.5.1}/fastapi_cachex/routes.py

@@ -5,8 +5,11 @@ from collections.abc import Sequence
 from dataclasses import dataclass
 from dataclasses import field
 from typing import TYPE_CHECKING
+from typing import Annotated
 from typing import Any
 
+from pydantic import Field
+
 from .cache_key import CacheKey
 from .exceptions import BackendNotFoundError
 from .proxy import BackendProxy
@@ -42,19 +45,42 @@ class CacheHitSummary:
     cached_paths: list[str]
 
 
+# Why the ``*_hits`` fields are deprecated, shown in the OpenAPI schema.
+_HITS_DEPRECATED = (
+    "Counts cache entries, not hits; use {0} instead. Deprecated in 0.5.1, "
+    "removed in 0.6.0 (#336)."
+)
+
+
 @dataclass
 class CacheHitsResponse:
     """Response for the ``/cached-hits`` endpoint.
 
-    The ``*_hits`` fields count cached entries, not requests served from them.
+    ``entries``, ``total_entries``, ``valid_entries`` and ``expired_entries``
+    list and count the cached route entries. The ``cached_hits`` and
+    ``*_hits`` fields hold the same values under names that suggested
+    requests served from the cache; they are deprecated (marked so in the
+    OpenAPI schema) and removed in 0.6.0 (#336).
     """
 
-    cached_hits: list[CacheHitRecord]
-    total_hits: int
-    valid_hits: int
-    expired_hits: int
+    entries: list[CacheHitRecord]
+    total_entries: int
+    valid_entries: int
+    expired_entries: int
     unique_routes: int
     summary: CacheHitSummary
+    cached_hits: Annotated[
+        list[CacheHitRecord], Field(deprecated=_HITS_DEPRECATED.format("entries"))
+    ]
+    total_hits: Annotated[
+        int, Field(deprecated=_HITS_DEPRECATED.format("total_entries"))
+    ]
+    valid_hits: Annotated[
+        int, Field(deprecated=_HITS_DEPRECATED.format("valid_entries"))
+    ]
+    expired_hits: Annotated[
+        int, Field(deprecated=_HITS_DEPRECATED.format("expired_entries"))
+    ]
 
 
 @dataclass
@@ -174,17 +200,23 @@ def _cached_hits(entries: list[_Entry]) -> CacheHitsResponse:
     valid_hits = [h for h in cached_hits if not h.is_expired]
     routes_hit = {h.path for h in valid_hits}
 
+    total = len(cached_hits)
+    valid = len(valid_hits)
     return CacheHitsResponse(
-        cached_hits=cached_hits,
-        total_hits=len(cached_hits),
-        valid_hits=len(valid_hits),
-        expired_hits=len(cached_hits) - len(valid_hits),
+        entries=cached_hits,
+        total_entries=total,
+        valid_entries=valid,
+        expired_entries=total - valid,
         unique_routes=len(routes_hit),
         summary=CacheHitSummary(
-            total_cached_entries=len(cached_hits),
-            active_entries=len(valid_hits),
+            total_cached_entries=total,
+            active_entries=valid,
             cached_paths=sorted(routes_hit),
         ),
+        cached_hits=cached_hits,
+        total_hits=total,
+        valid_hits=valid,
+        expired_hits=total - valid,
     )
 
 

{fastapi_cachex-0.5.0 → fastapi_cachex-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-cachex"
-version = "0.5.0"
+version = "0.5.1"
 description = "A caching library for FastAPI with support for Cache-Control, ETag, and multiple backends."
 readme = "README.md"
 requires-python = ">=3.10"

{fastapi_cachex-0.5.0 → fastapi_cachex-0.5.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-cachex"
-version = "0.5.0"
+version = "0.5.1"
 description = "A caching library for FastAPI with support for Cache-Control, ETag, and multiple backends."
 readme = "README.md"
 requires-python = ">=3.10"

fastapi_cachex-0.5.0/fastapi_cachex/exceptions.py

@@ -1,26 +0,0 @@
-"""Custom exception classes for FastAPI-CacheX."""
-
-
-class CacheXError(Exception):
-    """Base class for all exceptions in FastAPI-CacheX."""
-
-
-class BackendNotFoundError(CacheXError):
-    """Exception raised when a cache backend is not found."""
-
-
-class ProxyNotSetError(BackendNotFoundError):
-    """Exception raised when a manager proxy has no instance set.
-
-    Raised by ``CacheManagerProxy``. It subclasses ``BackendNotFoundError``,
-    which the manager proxies raised before 0.3.8, so existing handlers keep
-    catching it.
-    """
-
-
-class RequestNotFoundError(CacheXError):
-    """Exception raised when a request is not found."""
-
-
-class LockTimeoutError(CacheXError, TimeoutError):
-    """Exception raised when acquiring a lock or waiting for stampede protection times out."""