aioredis

Warnings

• breaking Version 2.0.0 of aioredis is a complete rewrite and introduces significant backward-incompatible API changes. It now closely follows the `redis-py` API, so existing code from v1.x will break.
  Fix: Refer to the official 'Migrating to v2.0' documentation. Key changes include connection methods, connection pool behavior, and command arguments.
• breaking Factory functions like `aioredis.create_redis()`, `aioredis.create_redis_pool()`, and `aioredis.create_pool()` are no longer available in v2.x.
  Fix: Use `aioredis.from_url()` to get a client with a connection pool, or `aioredis.Redis()` with an explicit `ConnectionPool` instance.
• breaking The `loop` argument for specifying an `asyncio` event loop has been deprecated in v1.3.1 for Python 3.8+ and effectively removed in v2.x. `aioredis` now relies on the implicit event loop of `asyncio`.
  Fix: Remove the `loop` argument from all `aioredis` function calls. Code should run in the current running event loop.
• breaking In v2.x, connection pools are lazy-filled, meaning connections are created on demand, unlike v1.x where `minsize` pre-filled the pool.
  Fix: Understand that `minsize` will not immediately establish connections in v2.x. Adjust application startup logic if pre-established connections are critical for initial performance checks.
• breaking The `Channel` abstraction over PubSub, present in v1.x, has been removed in v2.x to align with `redis-py`'s API.
  Fix: Refactor PubSub code to use `redis.pubsub()` directly, similar to `redis-py`'s PubSub client.
• gotcha By default, `aioredis` returns bytes for most Redis commands. To automatically decode responses to strings, you must explicitly pass `decode_responses=True` during client initialization.
  Fix: Initialize your Redis client with `redis = aioredis.from_url('redis://localhost', decode_responses=True)` to get string responses automatically. Otherwise, manually decode byte strings using `.decode('utf-8')`.
• breaking Version 1.0.0 dropped support for Python 3.3 and 3.4. It also changed the return format for sorted set commands (with `withscores`) and `hscan` to lists of tuples instead of plain lists or mixed key-value lists.
  Fix: Ensure Python environment is 3.6+ and update code to handle the new return formats for affected commands.

Install

• pip install aioredis Standard Install
• pip install aioredis hiredis Recommended for Performance (with hiredis)

Imports

• from_url

  import aioredis
  redis = aioredis.from_url(...)

  As of v2.0.0, `create_redis_pool` and similar factory functions were removed. Use `aioredis.from_url` or `aioredis.Redis` directly.
• Redis

  from aioredis import Redis
  redis = Redis(connection_pool=...)

• ConnectionPool

  from aioredis import ConnectionPool
  pool = ConnectionPool.from_url(...)

Quickstart

This quickstart demonstrates connecting to Redis using `aioredis.from_url`, setting and retrieving a key, and using a transaction pipeline. It emphasizes graceful connection shutdown and the recommended `decode_responses` parameter for automatic string decoding.

import asyncio
import aioredis
import os

async def main():
    # Connect to Redis using a URL. For production, use environment variables.
    # decode_responses=True decodes bytes to strings automatically.
    redis_url = os.environ.get('REDIS_URL', 'redis://localhost')
    redis = aioredis.from_url(
        redis_url,
        encoding="utf-8",
        decode_responses=True
    )

    try:
        await redis.set("my-key", "value")
        val = await redis.get("my-key")
        print(f"Retrieved value: {val}")

        # Example with a pipeline
        async with redis.pipeline(transaction=True) as pipe:
            result = await pipe.incr("counter").incr("counter").execute()
            print(f"Pipeline result: {result}")

    finally:
        # Ensure the connection pool is closed gracefully
        await redis.close()
        await redis.wait_closed()

if __name__ == "__main__":
    asyncio.run(main())