redis-client-kit 0.1.4__tar.gz → 0.2.0__tar.gz

{redis_client_kit-0.1.4 → redis_client_kit-0.2.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.2.0](https://github.com/bedrock-python/redis-client-kit/compare/redis-client-kit-v0.1.5...redis-client-kit-v0.2.0) (2026-09-07)
+
+
+### Features
+
+* add an opt-in write probe to the health checks ([#32](https://github.com/bedrock-python/redis-client-kit/issues/32)) ([aabafd1](https://github.com/bedrock-python/redis-client-kit/commit/aabafd1922e3e0cf1b525570f98cdf0f71a2856e))
+
+## [0.1.5](https://github.com/bedrock-python/redis-client-kit/compare/redis-client-kit-v0.1.4...redis-client-kit-v0.1.5) (2026-09-07)
+
+
+### Bug Fixes
+
+* hand redis.asyncio.Redis the async Retry, not the sync one ([#29](https://github.com/bedrock-python/redis-client-kit/issues/29)) ([e8ee302](https://github.com/bedrock-python/redis-client-kit/commit/e8ee3024b8e402cdb80c531b9284d513111116ea))
+
 ## [0.1.4](https://github.com/bedrock-python/redis-client-kit/compare/redis-client-kit-v0.1.3...redis-client-kit-v0.1.4) (2026-09-07)
 
 

{redis_client_kit-0.1.4 → redis_client_kit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: redis-client-kit
-Version: 0.1.4
+Version: 0.2.0
 Summary: Redis client with optional Pydantic, Prometheus, and Dishka support
 Project-URL: Repository, https://github.com/bedrock-python/redis-client-kit
 Project-URL: Documentation, https://bedrock-python.github.io/redis-client-kit/
@@ -491,6 +491,11 @@ from redis_client_kit import check_async_redis_health
 is_healthy = await check_async_redis_health(client)
 if is_healthy:
     print("Redis is ready!")
+
+# PING alone says healthy for a read-only replica and for a primary that is out of memory
+# under noeviction. write_key adds a SET <key> 1 EX 60 after the ping, for a service that
+# needs Redis for more than reads.
+is_healthy = await check_async_redis_health(client, write_key="myapp:health")
 ```
 
 ### Graceful Shutdown

{redis_client_kit-0.1.4 → redis_client_kit-0.2.0}/README.md

@@ -251,6 +251,11 @@ from redis_client_kit import check_async_redis_health
 is_healthy = await check_async_redis_health(client)
 if is_healthy:
     print("Redis is ready!")
+
+# PING alone says healthy for a read-only replica and for a primary that is out of memory
+# under noeviction. write_key adds a SET <key> 1 EX 60 after the ping, for a service that
+# needs Redis for more than reads.
+is_healthy = await check_async_redis_health(client, write_key="myapp:health")
 ```
 
 ### Graceful Shutdown

{redis_client_kit-0.1.4 → redis_client_kit-0.2.0}/redis_client_kit/__init__.py

@@ -24,7 +24,7 @@ from .utils import build_base_redis_kwargs, build_redis_retry, parse_redis_url_n
 try:
     __version__ = version("redis-client-kit")
 except PackageNotFoundError:  # pragma: no cover
-    __version__ = "0.1.4"
+    __version__ = "0.2.0"
 
 # ruff: noqa: RUF022
 __all__ = [

redis_client_kit-0.2.0/redis_client_kit/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

{redis_client_kit-0.1.4 → redis_client_kit-0.2.0}/redis_client_kit/aio/factory.py

@@ -50,7 +50,7 @@ def _create_async_single_client(
         extra={"host": settings.connection.host, "port": settings.connection.port},
     )
 
-    client_kwargs: dict[str, Any] = build_base_redis_kwargs(settings)
+    client_kwargs: dict[str, Any] = build_base_redis_kwargs(settings, asyncio=True)
     client_kwargs.update(
         {
             "host": settings.connection.host,
@@ -87,7 +87,7 @@ def _create_async_cluster_client(
         },
     )
 
-    cluster_kwargs: dict[str, Any] = build_base_redis_kwargs(settings)
+    cluster_kwargs: dict[str, Any] = build_base_redis_kwargs(settings, asyncio=True)
     cluster_kwargs.update(
         {
             "startup_nodes": startup_nodes,

{redis_client_kit-0.1.4 → redis_client_kit-0.2.0}/redis_client_kit/aio/lifecycle.py

@@ -8,6 +8,7 @@ from typing import Any
 
 from redis.exceptions import RedisClusterException, RedisError
 
+from ..utils import WRITE_PROBE_TTL_S
 from .types import AsyncRedisClient
 
 logger = logging.getLogger(__name__)
@@ -36,11 +37,19 @@ async def close_async_redis_client(client: AsyncRedisClient) -> None:
         logger.info("Closed Redis client")
 
 
-async def check_async_redis_health(client: AsyncRedisClient) -> bool:
+async def check_async_redis_health(client: AsyncRedisClient, *, write_key: str | None = None) -> bool:
     """Check async Redis connection health.
 
+    Pings the server, and with ``write_key`` writes that key as well. A ping alone is a
+    liveness answer: a read-only replica and a server at ``maxmemory`` under ``noeviction``
+    both reply PONG and refuse every write. The write probe turns that into a readiness
+    answer for a service that needs Redis for more than reads.
+
     Args:
         client: Redis client (single or cluster) to check
+        write_key: Key to ``SET`` after the ping, expiring after ``WRITE_PROBE_TTL_S``
+            seconds. None, the default, pings only. Prefix it yourself; this package
+            applies no key prefix.
 
     Returns:
         True if Redis is healthy, False otherwise
@@ -50,9 +59,12 @@ async def check_async_redis_health(client: AsyncRedisClient) -> bool:
 
         # Redis Cluster ping returns dict[str, bool] (node_id -> success); single node returns bool.
         if isinstance(result, dict) and result and all(isinstance(k, str) for k in result):
-            return all(bool(v) for v in result.values())
+            healthy = all(bool(v) for v in result.values())
+        else:
+            healthy = bool(result)
 
-        return bool(result)
+        if healthy and write_key is not None:
+            healthy = bool(await client.set(write_key, "1", ex=WRITE_PROBE_TTL_S))
     except (RedisError, RedisClusterException, OSError, ConnectionError, TimeoutError) as e:
         logger.warning(
             "Async Redis health check failed",
@@ -66,6 +78,8 @@ async def check_async_redis_health(client: AsyncRedisClient) -> bool:
         # We return False to indicate unhealthy state but log the full exception for debugging.
         logger.exception("Unexpected error during Redis health check")
         return False
+    else:
+        return healthy
 
 
 __all__ = ["check_async_redis_health", "close_async_redis_client"]

{redis_client_kit-0.1.4 → redis_client_kit-0.2.0}/redis_client_kit/sync/lifecycle.py

@@ -7,6 +7,7 @@ from typing import Any
 
 from redis.exceptions import RedisClusterException, RedisError
 
+from ..utils import WRITE_PROBE_TTL_S
 from .types import SyncRedisClient
 
 logger = logging.getLogger(__name__)
@@ -28,11 +29,19 @@ def close_redis_client(client: SyncRedisClient) -> None:
         logger.info("Closed Redis client")
 
 
-def check_redis_health(client: SyncRedisClient) -> bool:
+def check_redis_health(client: SyncRedisClient, *, write_key: str | None = None) -> bool:
     """Check sync Redis connection health.
 
+    Pings the server, and with ``write_key`` writes that key as well. A ping alone is a
+    liveness answer: a read-only replica and a server at ``maxmemory`` under ``noeviction``
+    both reply PONG and refuse every write. The write probe turns that into a readiness
+    answer for a service that needs Redis for more than reads.
+
     Args:
         client: Redis client (single or cluster) to check
+        write_key: Key to ``SET`` after the ping, expiring after ``WRITE_PROBE_TTL_S``
+            seconds. None, the default, pings only. Prefix it yourself; this package
+            applies no key prefix.
 
     Returns:
         True if Redis is healthy, False otherwise
@@ -42,9 +51,12 @@ def check_redis_health(client: SyncRedisClient) -> bool:
 
         # Redis Cluster ping returns dict[str, bool] (node_id -> success); single node returns bool.
         if isinstance(result, dict) and result and all(isinstance(k, str) for k in result):
-            return all(bool(v) for v in result.values())
+            healthy = all(bool(v) for v in result.values())
+        else:
+            healthy = bool(result)
 
-        return bool(result)
+        if healthy and write_key is not None:
+            healthy = bool(client.set(write_key, "1", ex=WRITE_PROBE_TTL_S))
     except (RedisError, RedisClusterException, OSError, ConnectionError, TimeoutError) as e:
         logger.warning(
             "Redis health check failed",
@@ -58,6 +70,8 @@ def check_redis_health(client: SyncRedisClient) -> bool:
         # We return False to indicate unhealthy state but log the full exception for debugging.
         logger.exception("Unexpected error during Redis health check")
         return False
+    else:
+        return healthy
 
 
 __all__ = ["check_redis_health", "close_redis_client"]

{redis_client_kit-0.1.4 → redis_client_kit-0.2.0}/redis_client_kit/utils.py

@@ -3,13 +3,17 @@
 import base64
 import binascii
 from pathlib import Path
+from typing import Literal, overload
 from urllib.parse import urlparse
 
+from redis.asyncio.retry import Retry as AsyncRetry
 from redis.backoff import ExponentialBackoff, NoBackoff
 from redis.retry import Retry
 
 from .config import RedisSettingsProtocol
 
+WRITE_PROBE_TTL_S = 60
+
 
 def parse_redis_url_node(node: str) -> tuple[str, int]:
     """Parse Redis node from host:port, [ipv6]:port or redis:// URL string."""
@@ -34,8 +38,12 @@ def parse_redis_url_node(node: str) -> tuple[str, int]:
     return host, port
 
 
-def build_base_redis_kwargs(settings: RedisSettingsProtocol) -> dict[str, object]:
-    """Build base Redis client keyword arguments."""
+def build_base_redis_kwargs(settings: RedisSettingsProtocol, *, asyncio: bool = False) -> dict[str, object]:
+    """Build base Redis client keyword arguments.
+
+    ``asyncio=True`` builds them for a ``redis.asyncio`` client, whose ``retry`` has to be
+    ``redis.asyncio.retry.Retry``.
+    """
     if settings.ssl.enabled:
         if settings.ssl.ca_certs:
             _validate_pem_format(settings.ssl.ca_certs, "CERTIFICATE")
@@ -52,7 +60,7 @@ def build_base_redis_kwargs(settings: RedisSettingsProtocol) -> dict[str, object
         "socket_keepalive": settings.pool.socket_keepalive,
         "socket_keepalive_options": settings.pool.socket_keepalive_options,
         "health_check_interval": settings.health_check_interval,
-        "retry": build_redis_retry(settings),
+        "retry": build_redis_retry(settings, asyncio=asyncio),
         "decode_responses": settings.response.decode_responses,
         "encoding": settings.response.encoding,
         "client_name": settings.connection.client_name,
@@ -72,22 +80,39 @@ def build_base_redis_kwargs(settings: RedisSettingsProtocol) -> dict[str, object
     return kwargs
 
 
-def build_redis_retry(settings: RedisSettingsProtocol) -> Retry:
+@overload
+def build_redis_retry(settings: RedisSettingsProtocol, *, asyncio: Literal[False] = ...) -> Retry: ...
+
+
+@overload
+def build_redis_retry(settings: RedisSettingsProtocol, *, asyncio: Literal[True]) -> AsyncRetry: ...
+
+
+@overload
+def build_redis_retry(settings: RedisSettingsProtocol, *, asyncio: bool) -> Retry | AsyncRetry: ...
+
+
+def build_redis_retry(settings: RedisSettingsProtocol, *, asyncio: bool = False) -> Retry | AsyncRetry:
     """Build Redis Retry object from settings.
 
     Retries are off unless both ``retry.enabled`` and ``retry.max_attempts`` are set. Off is
     still a ``Retry``, with zero retries: handed nothing, redis-py retries on its own (three
     times since 6.0, ten since 8.0, with jittered backoff).
+
+    ``asyncio=True`` builds ``redis.asyncio.retry.Retry``, the one a ``redis.asyncio`` client
+    needs: the sync class's ``call_with_retry`` does not await, so on an async client it
+    never retries.
     """
+    retry_class = AsyncRetry if asyncio else Retry
     if settings.retry.enabled and settings.retry.max_attempts:
-        return Retry(
+        return retry_class(
             backoff=ExponentialBackoff(
                 cap=settings.retry.backoff_cap,
                 base=settings.retry.backoff_base,
             ),
             retries=settings.retry.max_attempts,
         )
-    return Retry(backoff=NoBackoff(), retries=0)
+    return retry_class(backoff=NoBackoff(), retries=0)
 
 
 def _validate_pem_format(path: str | Path, file_type: str) -> None:
@@ -120,6 +145,7 @@ def mask_redis_kwargs(kwargs: dict[str, object]) -> dict[str, object]:
 
 
 __all__ = [
+    "WRITE_PROBE_TTL_S",
     "build_base_redis_kwargs",
     "build_redis_retry",
     "mask_redis_kwargs",

redis_client_kit-0.1.4/redis_client_kit/__version__.py

@@ -1 +0,0 @@
-__version__ = "0.1.4"