Disabled retries still retry: redis-py's default Retry(10) applies when the kit hands it nothing

[AlexeyShalaev]

Measured on 0.1.3 with redis-py 8.1.0, Redis 7 in a container that I paused so that connections neither succeed nor fail. One GET per client, with socket_timeout=0.5 and socket_connect_timeout=0.5 in the pool settings and the retry group left at its defaults, then with retry.enabled=False, max_attempts=0 spelled out:

bare redis-py, defaults                                    retry handed to redis-py: Retry retries=10 backoff=ExponentialWithJitterBackoff
bare redis-py, timeouts 0.5 + Retry(NoBackoff(), 0)        retry handed to redis-py: Retry retries=0  backoff=NoBackoff
kit, timeouts 0.5, retry settings default                  retry handed to redis-py: Retry retries=10 backoff=ExponentialWithJitterBackoff
kit, timeouts 0.5, retry.enabled=False explicitly          retry handed to redis-py: Retry retries=10 backoff=ExponentialWithJitterBackoff
--- Redis paused: one GET per client ---
bare redis-py, defaults                                    -> still waiting        20.00 s  (gave up watching)
bare redis-py, timeouts 0.5 + Retry(NoBackoff(), 0)        -> TimeoutError          0.50 s
kit, timeouts 0.5, retry settings default                  -> TimeoutError          9.93 s
kit, timeouts 0.5, retry.enabled=False explicitly          -> TimeoutError         17.90 s

Rule 5 on the agents page says that with no Retry handed to it redis-py does not retry at all. That was true once; redis-py now ships a default Retry(ExponentialWithJitterBackoff, retries=10) when retry is not given, and the kit hands nothing when retry.enabled is false, so a client configured to fail in half a second fails in ten to eighteen, jitter deciding which. For the use this post is about, a cache or an idempotency store that should fail open fast when Redis is gone, that is the difference between a request that degrades and a request that times out at the load balancer.

What I think it needs: when retries are disabled the factory should pass Retry(NoBackoff(), 0) explicitly, so "disabled" means what it says whatever redis-py's default is; when they are enabled, the kit's Retry is already explicit. Rule 5 and the retry section of the configuration guide follow. It may be worth a second look at whether the kit's own backoff should carry jitter now that redis-py's does, but that is a separate question from the default.

Scripts: retry_probe.py in https://github.com/bedrock-python/bedrock-python.github.io/tree/docs/production-python-series/docs/blog/lab/2026-09-07-when-should-redis-fail-open.

[AlexeyShalaev]

Checked this against redis-py's source rather than the changelog, one venv per version from 4.5.0 to 8.1.0. Redis and redis.asyncio.Redis had retry=None as the default through 5.3; 6.0.0 made it Retry(ExponentialWithJitterBackoff, retries=3), and 8.0.0 raised the count to 10. Below 6.0 the connection turned None into Retry(NoBackoff(), 0) itself, so passing that object explicitly is exactly what "nothing" used to mean, and retry= on all four client classes, NoBackoff and Retry(NoBackoff(), 0) in both flavours are all there at 4.5.0 already.

Plan: build_redis_retry always returns a Retry — the exponential one when enabled and max_attempts are both set, Retry(NoBackoff(), 0) otherwise — and build_base_redis_kwargs always carries it, so both factories and both cluster clients get it with no per-factory special case. Its return type narrows from Retry | None to Retry; a caller checking for None keeps working. I considered leaving the helper alone and substituting the zero-retry object only inside build_base_redis_kwargs, but anyone assembling kwargs from build_redis_retry by hand would keep the trap, so the helper is where it belongs.

Cluster clients: from 6.0 redis-py uses the object for its own cluster-level retry loop (cluster_error_retry_attempts is deprecated in its favour, with the same 3-then-10 default), so retries=0 stops those rounds as well. On 4.x and 5.x the object only reaches the node connections, where zero was the sync default anyway, and the cluster-level loop keeps its three attempts as it does today; the one place behaviour moves there is the async cluster, whose node connections defaulted to Retry(default_backoff(), 3) and now get zero, which is what "disabled" says.

Tests: unit tests on the kwargs for single and cluster, async and sync, plus an integration test with a paused container asserting a GET with socket_timeout=0.5 and retries off raises TimeoutError in under two seconds — it takes 10 to 18 s on master. Rule 5 and the build_redis_retry row on the agents page and the retry section of the configuration guide change in the same PR.

Jitter I'd keep out of this one: ExponentialWithJitterBackoff is not in redis-py 4.x, so it is not a one-line swap under redis>=4.5.0, and rule 6 currently promises the first retry waits exactly backoff_base. Worth its own issue.

The probe turned up one more thing while I was measuring. With retries enabled, the async factory hands redis.retry.Retry — the sync class — to redis.asyncio.Redis. Its call_with_retry is synchronous, so the client awaits whatever it returns and the retry loop never sees the failure: max_attempts=3, backoff_base=0.1, backoff_cap=1.0 on an async client fails in 0.50 s against the paused container, the same numbers with redis.asyncio.retry.Retry in 3.41 s. So on the async side "enabled" has never retried either, on any redis-py in the range. That is a separate fix with its own API question (the helpers have to know which flavour they are building), so I'll open it as its own issue rather than fold it in here.

[AlexeyShalaev]

#27 is up. build_redis_retry now always returns a Retry — the exponential one when both enabled and max_attempts are set, Retry(NoBackoff(), 0) otherwise — and build_base_redis_kwargs always carries it, so the async and sync factories and both cluster clients get it alike; its return type is Retry rather than Retry | None now. Your probe, unmodified, against the branch: the two kit rows hand redis-py retries=0 backoff=NoBackoff and fail in 0.50 s, same as the bare Retry(NoBackoff(), 0) row. An integration test with a paused container pins that at under two seconds, async and sync.

Nothing to change on your side; the defaults now do what the docs said, and rule 5 plus the retry section of the configuration guide explain redis-py's own default and why the kit hands it a zero-retry object instead of nothing. The sync-Retry-on-async finding is #26. Jitter I left open — it needs a decision about the 4.x floor and rule 6 first.