redis-py

redis-py is the official Python client library for Redis, maintained by Redis Inc. It implements the full Redis command surface for strings, hashes, sets, sorted sets, streams, and pub/sub, alongside module command mixins for RedisJSON, RediSearch, TimeSeries, Bloom filters, and vector sets.

It ships both a synchronous, threading-based client and an asyncio-native client under redis.asyncio that share the same API, plus dedicated RedisCluster and Sentinel classes for sharded and high-availability deployments. Connection pooling, pipelining, Lua scripting, client-side caching, and configurable RESP2/RESP3 wire protocol support round out the package.

What You Get

• Full command coverage — every core Redis command (strings, hashes, sets, sorted sets, streams, pub/sub, scripting) plus JSON, Search, TimeSeries, Bloom, and vector-set module commands.
• Sync and async clients — a threading-based redis.Redis client and an asyncio-native redis.asyncio.Redis client sharing the same API surface.
• Cluster and Sentinel support — RedisCluster for sharded deployments with MOVED/ASK redirection, and Sentinel for automatic primary discovery and failover.
• Connection pooling and pipelining — configurable ConnectionPool/BlockingConnectionPool, MULTI/EXEC pipelines, and optional hiredis-accelerated response parsing.
• RESP3 and client-side caching — opt-in RESP3 protocol support with built-in client-side caching and a documented migration path away from legacy RESP2 response shapes.

Common Use Cases

• Caching layer for a web application - store computed API responses or session data in Redis with TTLs to cut database load.
• Distributed locks and rate limiting - use redis-py’s Lock primitive and atomic command support to coordinate work across multiple app instances.
• Pub/Sub messaging between services - fan out real-time events to subscribers over Redis channels without standing up a separate message broker.
• Vector search and RAG pipelines - use the vector-set and RediSearch command mixins to store embeddings and run similarity queries directly against Redis.

Under The Hood

Architecture: redis-py structures the client around a small set of composable layers: redis/connection.py (3,868 lines) implements Connection, ConnectionPool, and BlockingConnectionPool, handling socket/TLS setup, RESP2/RESP3 parsing via _parsers/, and reconnection/backoff logic from redis/retry.py and redis/backoff.py. redis/client.py (2,279 lines) defines Redis/StrictRedis, which mix in command implementations from redis/commands/core.py (12,500+ lines) plus module-specific mixins under redis/commands/{json,search,bf,timeseries,vectorset}/. redis/cluster.py (5,000+ lines) reimplements slot-aware routing and MOVED/ASK redirection on top of the same connection layer, and redis/sentinel.py adds Sentinel-based primary discovery. The entire sync surface is mirrored under redis/asyncio/ with asyncio-native connection and client classes sharing the same command mixins, so switching between sync and async code paths requires minimal application-level changes.

Tech Stack: The library targets Python 3.10+ (per pyproject.toml) and ships as a pure-Python package built with hatchling; runtime dependencies are minimal — only async-timeout on older Python versions — with everything else (hiredis for compiled response parsing, xxhash, cryptography/pyopenssl/requests for OCSP, PyJWT, pybreaker, OpenTelemetry) declared as optional extras (e.g. pip install redis[hiredis]), keeping the core install lightweight. Type checking is configured via .mypy.ini, and the package ships a py.typed marker for downstream type checkers.

Code Quality: Test coverage is substantial: tests/ contains 147 files and roughly 2,769 test functions covering standalone, cluster, Sentinel, asyncio, and module (JSON/Search/TimeSeries) command paths, run via pytest with markers like fixed_client to control fixture reuse. Error handling is centralized in redis/exceptions.py, which defines a typed RedisError hierarchy (ConnectionError, TimeoutError, AuthenticationError, etc.) carrying a categorical error_type and optional status_code, giving callers a consistent way to distinguish network, TLS, auth, and server errors. CI under .github/workflows/ (including a dedicated integration.yaml) runs the suite against real Redis server versions.

API Design: The public API mirrors Redis’s own command vocabulary directly (r.set, r.hset, r.ft().search()), so developers already familiar with Redis need little translation; a basic Redis(host=..., port=..., db=...) call after pip install redis is enough to get started, with ConnectionPool and pipeline() available but not required. Recent releases introduced a deliberate migration path — legacy_responses and protocol=3 flags let existing applications keep RESP2-shaped Python responses while opting into RESP3 wire behavior gradually, documented explicitly in the README rather than forced as a breaking change. The tradeoff is real surface-area complexity: client.py and cluster.py are each thousands of lines, and changes like the client-side default search dialect are called out as needing care when upgrading.