●Change8

v8.0.0

Breaking Changes
📦 redis-pythonView on GitHub →
⚠ 4 breaking✨ 12 features🐛 8 fixes⚡ 3 deprecations🔧 25 symbols

Summary

This release introduces major features including full asyncio Cluster PubSub support and Redis Keyspace Notifications across sync/async modes, while defaulting to the RESP3 protocol. It also includes significant improvements to type hinting for static analysis and updates to default connection settings.

⚠️ Breaking Changes

  • Type hints were systematically updated using @overload across core, VectorSet, and module commands. Code relying on the old union return types (e.g., Union[Awaitable[Any], Any]) in type annotations for sync/async methods may need updates, although runtime behavior is unchanged.
  • The default protocol changed to RESP3. While default response shapes remain RESP2-compatible, explicitly setting `protocol=2` is required to force RESP2 on the wire.
  • ClusterPubSub now handles cluster slot migration (shard subscription reconciliation), which may affect custom subscription management logic.
  • Async reads in hiredis connections readiness checks now avoid zero-timeouts, replacing async's can_read_destructive with non-destructive can_read. This might affect low-level connection handling logic.

Migration Steps

  1. If using static analysis tools (mypy, Pyright), review return type annotations for core, VectorSet, and module commands, as they now return distinct sync/async types instead of a union.
  2. To maintain RESP2 wire protocol, explicitly set `protocol=2` if necessary, as RESP3 is now the default.
  3. To migrate to protocol-independent unified response shapes (where RESP2/RESP3 return the same Python structure), set `legacy_responses=False`.
  4. If using RESP3 natively without legacy responses, set `protocol=3`.
  5. Review code that relies on connection timeouts, as `socket_timeout` now defaults to 5 seconds and may cause `TimeoutError` for long-blocking commands.

✨ New Features

  • Full asyncio Cluster PubSub support introduced, enabling shard-channel capabilities (`SSUBSCRIBE`, `SUNSUBSCRIBE`, `SPUBLISH`) via the new `ClusterPubSub` class.
  • Redis Keyspace Notifications are now supported for standalone and cluster deployments in sync and async modes, introduced via `KeyspaceNotifications` and related classes.
  • Support for Redis Array commands (`AR*` family) for sparse, index-addressable sequences of strings.
  • RESP3 is now the default protocol, with an option (`legacy_responses=False`) to opt into protocol-independent unified response shapes.
  • Default connection settings updated: `socket_timeout` and `socket_connect_timeout` default to 5s, TCP keepalive enabled, socket read buffer set to 32 KB, connection pools default to `max_connections=100`, and retry defaults use 10 attempts with exponential jitter backoff.
  • Added random load balancing strategy allowing use of the primary node in cluster mode.
  • Added FPHA (floating-point homogeneous array) argument support to `SET`.
  • Added custom Claude command and `XNACK` command support.
  • Added Time Series Multiple Aggregators support.
  • Added support for the new `COUNT` aggregator for `ZINTER`, `ZINTERSTORE`, `ZUNION`, and `ZUNIONSTORE`.
  • Added support for the new `INCREX` command.
  • Added support for PubSub subscriptions with binary channel names and handlers.

🐛 Bug Fixes

  • Guard `disconnect()` against `RuntimeError` on Python 3.13+.
  • Fixed `CacheProxyConnection` hang when invalidation arrives on another connection.
  • Fixed `TypeError` in `CacheProxyConnection` when cached response is non-bytes.
  • Fixed async cluster connection cleanup on topology refresh.
  • Normalized scalar prefixes in `IndexDefinition`.
  • Handled scientific notation in `score_cast_func` for RESP2.
  • Preserved explicit `None` for client metadata configuration.
  • Fixed Sync `ClusterPubSub.disconnect()` potential `AttributeError`.

Affected Symbols

redis.asyncio.cluster.ClusterPubSubRedisCluster.pubsub()KeyspaceNotificationsClusterKeyspaceNotificationsAsyncKeyspaceNotificationsAsyncClusterKeyspaceNotificationssubscribe_keyspace()subscribe_keyevent()subscribe_subkeyspace()subscribe_subkeyevent()subscribe_subkeyspaceitem()subscribe_subkeyevent()core.pyVectorSet commandsSearch module commandsJSON module commandsTimeSeries module commandsBloom filter module commandsSyncClientProtocolAsyncClientProtocolLock.extendLock.reacquireClusterPubSub.disconnect()async's can_read_destructivehiredis connections readiness checks

⚡ Deprecations

  • Deprecation notice added to `setex()` method documentation.
  • Deprecation of `lib_name`/`lib_version` in async cluster contexts.
  • Avoidance of zero-timeout async reads in hiredis connections readiness checks and replacement of async's can_read_destructive with non-destructive can_read (related to breaking change).