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

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

@@ -1,5 +1,12 @@
 # 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)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: redis-client-kit
-Version: 0.1.5
+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.5 → 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.5 → 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.5"
+    __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.5 → 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.5 → 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.5 → redis_client_kit-0.2.0}/redis_client_kit/utils.py

@@ -12,6 +12,8 @@ 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."""
@@ -143,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.5/redis_client_kit/__version__.py

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