aioredis-py

aioredis is a Python client for Redis built directly on top of asyncio, giving applications a fully async interface to Redis commands, pipelines, transactions, pub/sub channels, and Sentinel-managed deployments. It exposes both a high-level Redis client with typed command methods mirroring the Redis command set, and lower-level Connection/ConnectionPool primitives for applications that need direct control over connection lifecycle and transport.

The library supports both a pure-Python RESP parser and an optional hiredis C-accelerated parser, connection pooling (including blocking pools that wait for an available connection under load), SSL and Unix domain socket transports, and a distributed Lock implementation with token-based ownership and safe extend/release semantics via Lua scripts.

Development on aioredis effectively ended in 2022 when its maintainer joined the Redis-py team and folded its functionality directly into redis-py as the redis.asyncio module (available from redis>=4.2.0rc1). The package remains widely referenced in older codebases and tutorials, and its API is close enough to redis.asyncio that most consumers migrate with an import change rather than a rewrite.

What You Get

• A Redis client class exposing async methods for the full Redis command surface (strings, hashes, sets, sorted sets, streams, scripting)
• Pipeline and MULTI/EXEC transaction support via Redis.pipeline() for batching commands into one round trip
• Pub/Sub support through a dedicated PubSub class with async iteration over published messages
• Sentinel client (aioredis.sentinel) for connecting to Redis deployments managed by Redis Sentinel for automatic failover
• Connection pooling, including BlockingConnectionPool, plus SSL and Unix domain socket connection classes
• A distributed Lock primitive with Lua-script-backed acquire/extend/release semantics for safe cross-process locking

Common Use Cases

• Caching query results or computed values from an async web service (FastAPI, aiohttp, Sanic) without blocking the event loop
• Implementing pub/sub messaging or lightweight event fan-out between asyncio services
• Coordinating distributed locks across multiple async worker processes sharing a Redis instance
• Connecting to a Sentinel-managed Redis cluster for automatic primary/replica failover in async applications
• Batching bulk reads/writes through pipelines to cut round-trip latency in high-throughput async workloads

Under The Hood

Architecture The library centers on a large Redis class in aioredis/client.py (roughly 4,800 lines) that mixes in per-command-group implementations directly as methods, backed by a ConnectionPool in aioredis/connection.py that owns the actual socket/transport layer (TCP, SSL, or Unix domain socket) and RESP encoding/decoding. Pipelines and transactions are implemented as a Pipeline subclass of Redis that queues commands and flushes them in one round trip via execute(). Pub/Sub and Monitor are separate classes that borrow a connection from the pool for the duration of a subscription. aioredis/sentinel.py layers Sentinel-aware primary/replica discovery on top of the same connection-pool abstraction, and aioredis/lock.py implements distributed locking using Lua scripts executed via EVALSHA for atomic acquire/extend/release. This is a fairly flat, single-package architecture: nearly all public behavior lives in client.py and connection.py, so changes to the core Connection/ConnectionPool contract would ripple through the client, pub/sub, sentinel, and lock modules alike.

Tech Stack aioredis is pure Python targeting asyncio (Python 3.6+), with async-timeout and typing-extensions as its only hard runtime dependencies, plus an optional hiredis extra for a faster C-based RESP parser (falling back to a pure-Python parser otherwise). It has no web framework or ORM dependency — it’s a standalone client library — and ships type stubs (py.typed) for static type checking by consumers. Builds and releases go through standard setuptools/setup.py, with towncrier managing the changelog and GitHub Actions running CI.

Code Quality The project has a substantial tests/ directory (test_commands.py, test_connection.py, test_connection_pool.py, test_pubsub.py, test_sentinel.py, test_lock.py, test_scripting.py, and more) using pytest, with explicit markers distinguishing hiredis_parser vs python_parser and pooled vs single-connection test runs — indicating the test suite deliberately exercises multiple parser and connection-pooling code paths. Errors are modeled through a dedicated exception hierarchy in exceptions.py (RedisError as the base, with typed subclasses like ConnectionError, ResponseError, WatchError, and LockError) rather than generic exceptions, and CI configuration (.github/workflows/ci.yml) runs the suite automatically. Naming is consistent with the official Redis command reference. Development activity has been effectively dormant since early 2023, which the repo’s own README explains: the maintainer folded the codebase into redis-py.

What Makes It Unique aioredis’s main technical distinction was being one of the first mature, asyncio-native Redis clients with a comprehensive command surface, Sentinel support, and a Lua-script-backed distributed lock — at a time when most Redis clients in the Python ecosystem were synchronous. It doesn’t introduce novel wire-protocol or algorithmic techniques beyond what Redis itself defines; its main historical significance is that its design and codebase were adopted almost wholesale into redis-py’s redis.asyncio module, effectively becoming the reference implementation for async Redis access in Python rather than a competing alternative to it.