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

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: fastapi-cachex
-Version: 0.5.1
+Version: 0.5.3
 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
 Author-email: allen0099 <s96016641@gmail.com>
 License-Expression: Apache-2.0
 License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
@@ -50,11 +50,11 @@ Description-Content-Type: text/markdown
 [![PyPI version](https://img.shields.io/pypi/v/fastapi-cachex.svg?logo=pypi&logoColor=gold&label=PyPI)](https://pypi.org/project/fastapi-cachex)
 [![Python Versions](https://img.shields.io/pypi/pyversions/fastapi-cachex.svg?logo=python&label=Python&logoColor=gold)](https://pypi.org/project/fastapi-cachex/)
 
-[English](https://fastapi-cachex.readthedocs.io/en/latest/) | [繁體中文](https://fastapi-cachex.readthedocs.io/zh-tw/latest/)
+[English](https://fastapi-cachex.readthedocs.io/en/stable/) | [繁體中文](https://fastapi-cachex.readthedocs.io/zh-tw/stable/)
 
 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.
+**Documentation:** <https://fastapi-cachex.readthedocs.io/en/stable/> — guides and the full API reference.
 
 ## Features
 
@@ -115,7 +115,7 @@ async def report(cache: AppCache):
 > 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)).
+> (see [Decorator order](https://fastapi-cachex.readthedocs.io/en/stable/HTTP_CACHING/#decorator-order)).
 >
 > ```python
 > @app.get("/items")  # ✅ route decorator first,
@@ -132,7 +132,7 @@ async def report(cache: AppCache):
 > with `private=True` or a per-user key builder plus `cache_authorized=True`
 > (requests with `Authorization` or non-empty `request.session` data otherwise
 > bypass the backend) — see
-> [Authenticated endpoints](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/#authenticated-endpoints).
+> [Authenticated endpoints](https://fastapi-cachex.readthedocs.io/en/stable/HTTP_CACHING/#authenticated-endpoints).
 
 ## Documentation
 
@@ -141,18 +141,19 @@ a code block that includes one of the runnable examples renders on the site,
 while GitHub shows only its `--8<--` include line (the sentence before each
 block links the example file).
 
-- [Migrating to 0.5.0](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_0_5/) — what 0.5.0 removes and how to upgrade from 0.4.x
-- [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
-- [Migrating from fastapi-cache2](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_FROM_FASTAPI_CACHE2/) — its API mapped onto this one, and the behaviour that differs
-- [When to use it](https://fastapi-cachex.readthedocs.io/en/latest/COMPARISON/) — how it compares with fastapi-cache2, cashews, aiocache and a CDN, and when another one fits better
-- [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
-- [Cache flow](https://fastapi-cachex.readthedocs.io/en/latest/CACHE_FLOW/) — what happens inside a cached request
+- [Migrating to 0.6.0](https://fastapi-cachex.readthedocs.io/en/stable/MIGRATING_0_6/) — what 0.6.0 will change, starting with the end of Python 3.10 support
+- [Migrating to 0.5.0](https://fastapi-cachex.readthedocs.io/en/stable/MIGRATING_0_5/) — what 0.5.0 removes and how to upgrade from 0.4.x
+- [Migrating to 0.4.0](https://fastapi-cachex.readthedocs.io/en/stable/MIGRATING_0_4/) — what 0.4.0 changes and how to upgrade from 0.3.x
+- [Migrating from fastapi-cache2](https://fastapi-cachex.readthedocs.io/en/stable/MIGRATING_FROM_FASTAPI_CACHE2/) — its API mapped onto this one, and the behaviour that differs
+- [When to use it](https://fastapi-cachex.readthedocs.io/en/stable/COMPARISON/) — how it compares with fastapi-cache2, cashews, aiocache and a CDN, and when another one fits better
+- [HTTP caching](https://fastapi-cachex.readthedocs.io/en/stable/HTTP_CACHING/) — the `@cache` decorator, Cache-Control directives, cache keys, invalidation and monitoring routes
+- [Application cache](https://fastapi-cachex.readthedocs.io/en/stable/APP_CACHE/) — `CacheManager`
+- [Backends](https://fastapi-cachex.readthedocs.io/en/stable/BACKENDS/) — choosing and configuring a backend, atomic primitives
+- [Distributed lock](https://fastapi-cachex.readthedocs.io/en/stable/LOCK/) — `CacheLock` for multi-process mutual exclusion
+- [Cache flow](https://fastapi-cachex.readthedocs.io/en/stable/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/) · [Security policy](https://github.com/allen0099/FastAPI-CacheX/blob/master/SECURITY.md) — report vulnerabilities privately, not in public issues
+- [API reference](https://fastapi-cachex.readthedocs.io/en/stable/api/http-caching/)
+- [Development guide](https://fastapi-cachex.readthedocs.io/en/stable/DEVELOPMENT/) and [contributing](https://fastapi-cachex.readthedocs.io/en/stable/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.5.1 → fastapi_cachex-0.5.3}/README.md

@@ -12,11 +12,11 @@
 [![PyPI version](https://img.shields.io/pypi/v/fastapi-cachex.svg?logo=pypi&logoColor=gold&label=PyPI)](https://pypi.org/project/fastapi-cachex)
 [![Python Versions](https://img.shields.io/pypi/pyversions/fastapi-cachex.svg?logo=python&label=Python&logoColor=gold)](https://pypi.org/project/fastapi-cachex/)
 
-[English](https://fastapi-cachex.readthedocs.io/en/latest/) | [繁體中文](https://fastapi-cachex.readthedocs.io/zh-tw/latest/)
+[English](https://fastapi-cachex.readthedocs.io/en/stable/) | [繁體中文](https://fastapi-cachex.readthedocs.io/zh-tw/stable/)
 
 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.
+**Documentation:** <https://fastapi-cachex.readthedocs.io/en/stable/> — guides and the full API reference.
 
 ## Features
 
@@ -77,7 +77,7 @@ async def report(cache: AppCache):
 > 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)).
+> (see [Decorator order](https://fastapi-cachex.readthedocs.io/en/stable/HTTP_CACHING/#decorator-order)).
 >
 > ```python
 > @app.get("/items")  # ✅ route decorator first,
@@ -94,7 +94,7 @@ async def report(cache: AppCache):
 > with `private=True` or a per-user key builder plus `cache_authorized=True`
 > (requests with `Authorization` or non-empty `request.session` data otherwise
 > bypass the backend) — see
-> [Authenticated endpoints](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/#authenticated-endpoints).
+> [Authenticated endpoints](https://fastapi-cachex.readthedocs.io/en/stable/HTTP_CACHING/#authenticated-endpoints).
 
 ## Documentation
 
@@ -103,18 +103,19 @@ a code block that includes one of the runnable examples renders on the site,
 while GitHub shows only its `--8<--` include line (the sentence before each
 block links the example file).
 
-- [Migrating to 0.5.0](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_0_5/) — what 0.5.0 removes and how to upgrade from 0.4.x
-- [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
-- [Migrating from fastapi-cache2](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_FROM_FASTAPI_CACHE2/) — its API mapped onto this one, and the behaviour that differs
-- [When to use it](https://fastapi-cachex.readthedocs.io/en/latest/COMPARISON/) — how it compares with fastapi-cache2, cashews, aiocache and a CDN, and when another one fits better
-- [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
-- [Cache flow](https://fastapi-cachex.readthedocs.io/en/latest/CACHE_FLOW/) — what happens inside a cached request
+- [Migrating to 0.6.0](https://fastapi-cachex.readthedocs.io/en/stable/MIGRATING_0_6/) — what 0.6.0 will change, starting with the end of Python 3.10 support
+- [Migrating to 0.5.0](https://fastapi-cachex.readthedocs.io/en/stable/MIGRATING_0_5/) — what 0.5.0 removes and how to upgrade from 0.4.x
+- [Migrating to 0.4.0](https://fastapi-cachex.readthedocs.io/en/stable/MIGRATING_0_4/) — what 0.4.0 changes and how to upgrade from 0.3.x
+- [Migrating from fastapi-cache2](https://fastapi-cachex.readthedocs.io/en/stable/MIGRATING_FROM_FASTAPI_CACHE2/) — its API mapped onto this one, and the behaviour that differs
+- [When to use it](https://fastapi-cachex.readthedocs.io/en/stable/COMPARISON/) — how it compares with fastapi-cache2, cashews, aiocache and a CDN, and when another one fits better
+- [HTTP caching](https://fastapi-cachex.readthedocs.io/en/stable/HTTP_CACHING/) — the `@cache` decorator, Cache-Control directives, cache keys, invalidation and monitoring routes
+- [Application cache](https://fastapi-cachex.readthedocs.io/en/stable/APP_CACHE/) — `CacheManager`
+- [Backends](https://fastapi-cachex.readthedocs.io/en/stable/BACKENDS/) — choosing and configuring a backend, atomic primitives
+- [Distributed lock](https://fastapi-cachex.readthedocs.io/en/stable/LOCK/) — `CacheLock` for multi-process mutual exclusion
+- [Cache flow](https://fastapi-cachex.readthedocs.io/en/stable/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/) · [Security policy](https://github.com/allen0099/FastAPI-CacheX/blob/master/SECURITY.md) — report vulnerabilities privately, not in public issues
+- [API reference](https://fastapi-cachex.readthedocs.io/en/stable/api/http-caching/)
+- [Development guide](https://fastapi-cachex.readthedocs.io/en/stable/DEVELOPMENT/) and [contributing](https://fastapi-cachex.readthedocs.io/en/stable/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.5.1 → fastapi_cachex-0.5.3}/fastapi_cachex/__init__.py

@@ -1,6 +1,8 @@
 """FastAPI-CacheX: A powerful and flexible caching extension for FastAPI."""
 
 import logging
+import sys
+import warnings
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version
 
@@ -47,6 +49,28 @@ def _read_version() -> str:
 
 __version__ = _read_version()
 
+_PYTHON_310_NOTICE = (
+    "fastapi-cachex 0.6.0 will require Python 3.11 or later; Python 3.10 "
+    "reached its end of life in October 2026. Upgrade Python; see "
+    "https://fastapi-cachex.readthedocs.io/en/stable/MIGRATING_0_6/#python-311"
+)
+
+
+def _warn_python_310(python: tuple[int, int] = sys.version_info[:2]) -> None:
+    """Warn on import under Python 3.10, which 0.6.0 drops (#491).
+
+    ``FutureWarning``, not ``DeprecationWarning``: it is shown by default.
+    ``stacklevel=3`` skips this function and the package module; ``warnings``
+    skips the import machinery's frames itself, so the warning names the line
+    that imported ``fastapi_cachex`` (for ``importlib.import_module()`` it
+    names ``importlib/__init__.py``; 3.10 has no ``skip_file_prefixes``).
+    """
+    if python < (3, 11):
+        warnings.warn(_PYTHON_310_NOTICE, FutureWarning, stacklevel=3)
+
+
+_warn_python_310()
+
 _package_logger = logging.getLogger("fastapi_cachex")
 _package_logger.addHandler(
     logging.NullHandler()

{fastapi_cachex-0.5.1 → fastapi_cachex-0.5.3}/fastapi_cachex/_stored_response.py

@@ -121,7 +121,9 @@ def _get_response_body(response: Response) -> bytes | None:
 
 
 def _etag_for(body: bytes) -> str:
-    return f'W/"{hashlib.md5(body).hexdigest()}"'  # noqa: S324
+    # A validator, not a security control: say so, or a FIPS-mode OpenSSL
+    # refuses MD5 and every render fails (#496).
+    return f'W/"{hashlib.md5(body, usedforsecurity=False).hexdigest()}"'
 
 
 def _weak_etag(etag: str) -> str:

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

@@ -7,7 +7,6 @@ from collections.abc import Iterable
 from datetime import timedelta
 from types import TracebackType
 from typing import TYPE_CHECKING
-from typing import Any
 from typing import overload
 
 from fastapi_cachex.exceptions import CacheXError
@@ -102,6 +101,24 @@ def validate_ttl(ttl: int | timedelta | None) -> int | None:
     return ttl
 
 
+def require_ttl(ttl: int | timedelta) -> int:
+    """``validate_ttl`` for a TTL that must be given, such as a lock lease.
+
+    ``expire_if_equals`` renews a lease; "no expiry" there would make a lock
+    permanent, and each backend used to read ``None`` its own way (#499).
+
+    Raises:
+        TTLTypeError: If ``ttl`` is ``None``, or anything ``validate_ttl``
+            refuses with it
+        TTLValueError: As ``validate_ttl``
+    """
+    if ttl is None:
+        # Unreachable for type checkers; guards untyped callers.
+        msg = "ttl must be an int number of seconds or a timedelta, got None"  # type: ignore[unreachable]
+        raise TTLTypeError(msg)
+    return validate_ttl(ttl)
+
+
 def _whole_seconds(value: timedelta, name: str) -> int:
     """The whole number of seconds in ``value``.
 
@@ -305,12 +322,18 @@ class BaseCacheBackend(ABC):
         Args:
             key: Cache key to update expiry for
             expected: The entry the caller stored (compared with ``==``)
-            ttl: Time to live in seconds
+            ttl: Time to live in seconds or as a ``timedelta``; required
 
         Returns:
             Whether the expiry was updated
+
+        Raises:
+            TTLTypeError: If ``ttl`` is ``None`` or not an ``int`` or a
+                ``timedelta``
+            TTLValueError: If ``ttl`` is zero, negative or larger than
+                ``MAX_TTL``
         """
-        ttl = validate_ttl(ttl)
+        ttl = require_ttl(ttl)
         if await self.get(key) != expected:
             return False
         await self.set(key, expected, ttl=ttl)
@@ -442,7 +465,7 @@ class BaseCacheBackend(ABC):
         """
 
     @abstractmethod
-    async def get_cache_data(self) -> dict[str, tuple[Any, float | None]]:
+    async def get_cache_data(self) -> dict[str, tuple[CacheEntry, float | None]]:
         """Get all cache data with expiry information.
 
         This method is primarily used for cache monitoring and statistics.

{fastapi_cachex-0.5.1 → fastapi_cachex-0.5.3}/fastapi_cachex/backends/codec.py

@@ -22,8 +22,10 @@ except ImportError:  # pragma: no cover - import-time, environment dependent
 
 # ``json.loads`` (either implementation) raises ``ValueError`` subclasses for bad
 # JSON; ``KeyError``/``TypeError``/``AttributeError`` cover documents whose shape
-# is not the one ``encode_entry`` writes (missing fields, non-string content).
-_DECODE_ERRORS = (ValueError, KeyError, TypeError, AttributeError)
+# is not the one ``encode_entry`` writes (missing fields, non-string content);
+# fields of another type are checked in ``decode_entry``.
+# The standard library parser raises ``RecursionError`` on deep nesting.
+_DECODE_ERRORS = (ValueError, KeyError, TypeError, AttributeError, RecursionError)
 
 
 def encode_entry(entry: CacheEntry) -> bytes:
@@ -54,6 +56,11 @@ def encode_entry(entry: CacheEntry) -> bytes:
     return serialized if isinstance(serialized, bytes) else serialized.encode("utf-8")
 
 
+# The status codes HTTP defines; anything else cannot be replayed.
+_MIN_STATUS = 100
+_MAX_STATUS = 599
+
+
 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)):
@@ -66,8 +73,8 @@ def decode_entry(raw: str | bytes | None) -> CacheEntry | None:
 
     A bare integer (what the server-side ``INCR`` family leaves behind for
     ``increment``) becomes a counter entry. Anything else that is not a document
-    written by ``encode_entry`` (corrupt JSON, missing fields, non-string
-    content) yields ``None``, so callers can treat every malformed value as a
+    written by ``encode_entry`` (corrupt JSON, missing fields, a field of the
+    wrong type, a status code outside 100-599) yields ``None``, so callers can treat every malformed value as a
     cache miss.
 
     Documents written before entries carried a status code and headers simply
@@ -83,11 +90,22 @@ def decode_entry(raw: str | bytes | None) -> CacheEntry | None:
         return counter_entry(counter)
     try:
         data = json.loads(raw)
+        fingerprint = data["fingerprint"]
+        media_type = data.get("media_type")
+        status_code = data.get("status_code", DEFAULT_STATUS_CODE)
+        if (
+            not isinstance(fingerprint, str)
+            or not isinstance(media_type, (str, type(None)))
+            or isinstance(status_code, bool)
+            or not isinstance(status_code, int)
+            or not _MIN_STATUS <= status_code <= _MAX_STATUS
+        ):
+            return None
         return CacheEntry(
-            fingerprint=data["fingerprint"],
+            fingerprint=fingerprint,
             content=data["content"].encode("latin-1"),
-            media_type=data.get("media_type"),
-            status_code=data.get("status_code", DEFAULT_STATUS_CODE),
+            media_type=media_type,
+            status_code=status_code,
             headers=data.get("headers"),
             stored_at=_stored_at(data.get("stored_at")),
         )

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

@@ -5,6 +5,7 @@ import hashlib
 import logging
 import time
 import warnings
+from collections.abc import Callable
 from collections.abc import Iterable
 from datetime import timedelta
 
@@ -14,9 +15,11 @@ 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 fastapi_cachex.types import log_ref
 
 from ._unavailable import translate_unavailable
 from .base import BaseCacheBackend
+from .base import require_ttl
 from .base import validate_delta
 from .base import validate_ttl
 
@@ -57,6 +60,32 @@ _LEGAL_KEY_BYTES = frozenset(range(0x21, 0x7F))
 _MAX_PREFIX_BYTES = _MAX_KEY_BYTES - 64
 
 
+# What `connect_timeout` and `timeout` are while they are not passed. 0.6.0
+# makes it 1 second, as on the Redis backend (#516).
+_DEFAULT_TIMEOUT = 5.0
+
+_TIMEOUT_DEFAULT_NOTICE = (
+    "MemcachedBackend timeouts will default to 1 second in fastapi-cachex "
+    "0.6.0; they default to 5 seconds now. Pass connect_timeout and timeout "
+    "to choose the values and silence this warning; see "
+    "https://fastapi-cachex.readthedocs.io/en/stable/MIGRATING_0_6/#memcached-timeouts"
+)
+
+
+def _validate_timeout(name: str, value: float) -> None:
+    """Reject a timeout that is not a positive, finite number of seconds.
+
+    Zero would make the sockets non-blocking, and pymemcache reports a
+    negative one only when the first command connects.
+    """
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        msg = f"{name} must be a number of seconds, got {type(value).__name__}"
+        raise TypeError(msg)
+    if not 0 < value < float("inf"):
+        msg = f"{name} must be greater than zero and finite, got {value!r}"
+        raise ValueError(msg)
+
+
 def _validate_key_prefix(key_prefix: str) -> None:
     """Reject a ``key_prefix`` that would make keys Memcached refuses (#239).
 
@@ -153,19 +182,48 @@ class MemcachedBackend(BaseCacheBackend):
         self,
         servers: list[str],
         key_prefix: str = DEFAULT_MEMCACHE_PREFIX,
+        *,
+        connect_timeout: float | None = None,
+        timeout: float | None = None,
     ) -> None:
         """Initialize the Memcached backend.
 
         Args:
             servers: List of Memcached servers in format ["host:port", ...]
             key_prefix: Prefix for all cache keys (default: 'fastapi_cachex:')
+            connect_timeout: Seconds to wait for a connection to a server.
+                ``None`` (not passed) is 5 seconds, and 1 second from 0.6.0;
+                it does not disable the timeout.
+            timeout: Seconds to wait for each reply from a server. ``None``
+                (not passed) is 5 seconds, and 1 second from 0.6.0; it does
+                not disable the timeout. Every
+                call runs in a worker thread of the default executor and
+                holds it until it is answered or times out, so while a
+                server is unreachable a lower value frees those threads
+                sooner.
+
+        Warns:
+            FutureWarning: If ``connect_timeout`` or ``timeout`` is not
+                passed, since their default changes in 0.6.0 (#516).
 
         Raises:
             CacheXError: If pymemcache is not installed
+            TypeError: If ``connect_timeout`` or ``timeout`` is not a number
             ValueError: If ``key_prefix`` holds whitespace, control
-                characters or non-ASCII, or is 250 bytes or longer
+                characters or non-ASCII, or is 250 bytes or longer, or if
+                ``connect_timeout`` or ``timeout`` is not greater than zero
         """
         _validate_key_prefix(key_prefix)
+        if connect_timeout is None or timeout is None:
+            warnings.warn(
+                _TIMEOUT_DEFAULT_NOTICE, FutureWarning, stacklevel=caller_stacklevel()
+            )
+        connect_timeout = (
+            _DEFAULT_TIMEOUT if connect_timeout is None else connect_timeout
+        )
+        timeout = _DEFAULT_TIMEOUT if timeout is None else timeout
+        _validate_timeout("connect_timeout", connect_timeout)
+        _validate_timeout("timeout", timeout)
         try:
             from pymemcache import HashClient
         except ImportError as exc:
@@ -185,8 +243,8 @@ class MemcachedBackend(BaseCacheBackend):
         # ``_DEAD_TIMEOUT`` seconds.
         self.client = HashClient(
             servers,
-            connect_timeout=5,
-            timeout=5,
+            connect_timeout=connect_timeout,
+            timeout=timeout,
             use_pooling=True,
             default_noreply=False,
             retry_attempts=0,
@@ -298,7 +356,15 @@ class MemcachedBackend(BaseCacheBackend):
                 return None
             logger.debug("Memcached GET_AND_DELETE RETRY; key=%s", key)
 
-        msg = f"Memcached get_and_delete exceeded {_CAS_MAX_RETRIES} attempts on key {key!r}"
+        # The message reaches error logs and trackers: a digest, not the key.
+        key_ref = log_ref(key)
+        logger.debug(
+            "Memcached GET_AND_DELETE GAVE UP; key_ref=%s key=%s", key_ref, key
+        )
+        msg = (
+            f"Memcached get_and_delete exceeded {_CAS_MAX_RETRIES} attempts "
+            f"(key_ref={key_ref})"
+        )
         raise CacheXError(msg)
 
     @_unavailable
@@ -325,31 +391,45 @@ 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).
+    def _cas_if_equals(
+        self,
+        operation: str,
+        key: str,
+        expected: CacheEntry,
+        new: Callable[[bytes], bytes],
+        exptime: int,
+    ) -> bool:
+        """GETS, compare and CAS in one worker thread.
 
-        The classic protocol's DELETE takes no CAS token, so the release is a
-        CAS write with a negative exptime, which Memcached treats as "expired
-        immediately": it succeeds only if nothing wrote the key since ``GETS``
-        read the value that was compared.
+        Writes ``new(raw)``, given the bytes just read, with ``exptime`` only
+        if the key holds ``expected`` and nothing wrote or deleted it since
+        ``GETS`` read the value that was compared. ``new`` is called only once
+        the comparison has passed.
         """
-        return await asyncio.to_thread(self._delete_if_equals, key, expected)
-
-    def _delete_if_equals(self, key: str, expected: CacheEntry) -> bool:
-        """Run ``delete_if_equals``'s GETS, compare and CAS in one worker thread."""
         prefixed_key = self._make_key(key)
         raw, cas_token = self.client.gets(prefixed_key)
         if raw is None or decode_entry(raw) != expected:
-            logger.debug("Memcached DELETE_IF_EQUALS MISMATCH; key=%s", key)
+            logger.debug("Memcached %s MISMATCH; key=%s", operation, key)
             return False
-        deleted = self.client.cas(prefixed_key, b"", cas_token, -1, noreply=False)
+        done = self.client.cas(
+            prefixed_key, new(raw), cas_token, exptime, noreply=False
+        )
         logger.debug(
-            "Memcached DELETE_IF_EQUALS %s; key=%s",
-            "HIT" if deleted else "LOST RACE",
-            key,
+            "Memcached %s %s; key=%s", operation, "HIT" if done else "LOST RACE", key
+        )
+        return bool(done)
+
+    @_unavailable
+    async def delete_if_equals(self, key: str, expected: CacheEntry) -> bool:
+        """Atomically remove ``key`` while it holds ``expected`` (see base class).
+
+        The classic protocol's DELETE takes no CAS token, so the release is a
+        CAS write with a negative exptime, which Memcached treats as "expired
+        immediately".
+        """
+        return await asyncio.to_thread(
+            self._cas_if_equals, "DELETE_IF_EQUALS", key, expected, lambda _: b"", -1
         )
-        return bool(deleted)
 
     @_unavailable
     async def expire_if_equals(
@@ -360,30 +440,16 @@ class MemcachedBackend(BaseCacheBackend):
         TOUCH in the Memcached protocol takes no CAS token, so the renewal is a
         CAS write with the same bytes read by GETS and the new exptime.
         """
-        ttl = validate_ttl(ttl)
         # Converted up front so a ttl Memcached cannot store fails before I/O.
-        exptime = _expiry(ttl)
+        exptime = _expiry(require_ttl(ttl))
         return await asyncio.to_thread(
-            self._expire_if_equals, key, expected, ttl, exptime
-        )
-
-    def _expire_if_equals(
-        self, key: str, expected: CacheEntry, ttl: int, exptime: int
-    ) -> bool:
-        """Run ``expire_if_equals``'s GETS, compare and CAS in one worker thread."""
-        prefixed_key = self._make_key(key)
-        raw, cas_token = self.client.gets(prefixed_key)
-        if raw is None or decode_entry(raw) != expected:
-            logger.debug("Memcached EXPIRE_IF_EQUALS MISMATCH; key=%s", key)
-            return False
-        updated = self.client.cas(prefixed_key, raw, cas_token, exptime, noreply=False)
-        logger.debug(
-            "Memcached EXPIRE_IF_EQUALS %s; key=%s ttl=%s",
-            "HIT" if updated else "LOST RACE",
+            self._cas_if_equals,
+            "EXPIRE_IF_EQUALS",
             key,
-            ttl,
+            expected,
+            lambda raw: raw,
+            exptime,
         )
-        return bool(updated)
 
     @_unavailable
     async def set_if_equals(
@@ -393,42 +459,17 @@ class MemcachedBackend(BaseCacheBackend):
         value: CacheEntry,
         ttl: int | timedelta | None = None,
     ) -> bool:
-        """Atomically store ``value`` while ``key`` holds ``expected`` (see base class).
-
-        GETS reads the value to compare along with its CAS token, and the CAS
-        write succeeds only if nothing wrote or deleted the key since.
-        """
-        ttl = validate_ttl(ttl)
+        """Atomically store ``value`` while ``key`` holds ``expected`` (see base class)."""
         # Converted up front so a ttl Memcached cannot store fails before I/O.
-        exptime = _expiry(ttl)
+        exptime = _expiry(validate_ttl(ttl))
         return await asyncio.to_thread(
-            self._set_if_equals, key, expected, value, ttl, exptime
-        )
-
-    def _set_if_equals(
-        self,
-        key: str,
-        expected: CacheEntry,
-        value: CacheEntry,
-        ttl: int | None,
-        exptime: int,
-    ) -> bool:
-        """Run ``set_if_equals``'s GETS, compare and CAS in one worker thread."""
-        prefixed_key = self._make_key(key)
-        raw, cas_token = self.client.gets(prefixed_key)
-        if raw is None or decode_entry(raw) != expected:
-            logger.debug("Memcached SET_IF_EQUALS MISMATCH; key=%s", key)
-            return False
-        stored = self.client.cas(
-            prefixed_key, encode_entry(value), cas_token, exptime, noreply=False
-        )
-        logger.debug(
-            "Memcached SET_IF_EQUALS %s; key=%s ttl=%s",
-            "HIT" if stored else "LOST RACE",
+            self._cas_if_equals,
+            "SET_IF_EQUALS",
             key,
-            ttl,
+            expected,
+            lambda _: encode_entry(value),
+            exptime,
         )
-        return bool(stored)
 
     def _add_delta(self, prefixed_key: str, delta: int) -> int | None:
         """Apply ``delta`` with INCR/DECR; ``None`` when the key does not exist.
@@ -623,7 +664,6 @@ class MemcachedBackend(BaseCacheBackend):
         )
         return removed
 
-    @_unavailable
     async def clear_pattern(self, pattern: str) -> int:
         """Clear cached responses matching a pattern.
 
@@ -647,7 +687,6 @@ 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.
 
@@ -670,7 +709,6 @@ 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.