aioredis — API Reference

Connection

Redis Connection is the core function of the library. Connection instances can be used as is or through pool or high-level API.

Connection usage is as simple as:

import asyncio
import aioredis

@asyncio.coroutine
def connection_example():
    conn = yield from aioredis.create_connection(
        ('localhost', 6379))
    # connecting to socket
    # conn = yiled from aioredis.create_connection(
    #     '/path/to/redis/socket')
    val = yield from conn.execute('GET', 'my-key')

asyncio.get_event_loop().run_until_complete(connection_example())
aioredis.create_connection(address, *, db=0, password=None, encoding=None, loop=None)

Creates Redis connection.

This is a coroutine function.

Parameters:
  • address (tuple or str) – An address where to connect. Can be a (host, port) tuple or unix domain socket path string.
  • db (int) – Redis database index to switch to when connected.
  • password (str or None) – Password to use if redis server instance requires authorization.
  • encoding (str or None) – Codec to use for response decoding.
  • loop (EventLoop) – An optional event loop instance (uses asyncio.get_event_loop() if not specified).
Returns:

RedisConnection instance.
class aioredis.RedisConnection

Redis connection interface.

db

Current database index (read-only).

encoding

Current codec for response decoding (read-only).

closed

Set to True if connection is closed (read-only).

execute(command, *args, encoding=_NOTSET)

A coroutine function to execute Redis command.

Parameters:
  • command (str, bytes, bytearray) – Command to execute
  • encoding (str or None) – Keyword-only argument for overriding response decoding. By default will use connection-wide encoding. May be set to None to skip response decoding.
Raises:
Returns:

Returns bytes or int reply (or str if encoding was set)
close()

Closes connection.

select(db)

Changes current db index to new one.

Parameters:

db (int) – New redis database index.
Raises:
Return True:

Always returns True or raises exception.
auth(password)

Send AUTH command.

Parameters:password (str) – Plain-text password
Return bool:True if redis replied with ‘OK’.

Pool

The library provides connections pool. The basic usage is as follows:

import asyncio
import aioredis

@asyncio.coroutine
def test_pool():
    pool = yield from aioredis.create_pool(('localhost', 6379))
    with (yield from pool) as redis:
        val = yield from redis.get('my-key')
aioredis.create_pool(address, *, db=0, password=None, encoding=None, minsize=10, maxsize=10, commands_factory=Redis, loop=None)

A coroutine that creates Redis connections pool.

By default it creates pool of commands_factory instances, but it is also possible to create plain connections pool by passing lambda conn: conn as commands_factory.

Parameters:
  • address (tuple or str) – An address where to connect. Can be a (host, port) tuple or unix domain socket path string.
  • db (int) – Redis database index to switch to when connected.
  • password (str or None) – Password to use if redis server instance requires authorization.
  • encoding (str or None) – Codec to use for response decoding.
  • minsize (int) – Minimum number of free connection to create in pool. 10 by default.
  • maxsize (int) – Maximum number of connection to keep in pool. 10 by default.
  • commands_factory (callable) – A factory to be passed to create_redis call. Redis by default.
  • loop (EventLoop) – An optional event loop instance (uses asyncio.get_event_loop() if not specified).
Returns:

RedisPool instance.
class aioredis.RedisPool

Redis connections pool.

minsize

A minimum size of the pool (read-only).

maxsize

A maximum size of the pool (read-only).

size

Current pool size — number of free and used connections (read-only).

freesize

Current number of free connections (read-only).

db

Currently selected db index (read-only).

encoding

Current codec for response decoding (read-only).

clear()

Closes and removes all free connections in the pool.

select(db)

Changes db index for all free connections in the pool.

This method is a coroutine.

Parameters:db (int) – New database index.
acquire()

Acquires a connection from free pool. Creates new connection if needed.

This method is a coroutine.

release(conn)

Returns used connection back into pool.

When returned connection has db index that differs from one in pool the connection will be dropped. When queue of free connections is full the connection will be dropped.

Note

This method is NOT a coroutine.

Parameters:conn – A RedisCommand instance.

Exceptions

exception aioredis.RedisError

Base exception class for aioredis exceptions.

exception aioredis.ProtocolError

Raised when protocol error occurs. When this type of exception is raised connection must be considered broken and must be closed.

exception aioredis.ReplyError

Raised for Redis error replies.

exception aioredis.PipelineError

Raised from pipeline() if any pipelined command raised error.

exception aioredis.MultiExecError

Same as PipelineError but raised when executing multi_exec block.

Commands Interface

The library provides high-level API implementing simple interface to Redis commands.

aioredis.create_redis(address, *, db=0, password=None, encoding=None, commands_factory=Redis, loop=None)

This coroutine creates high-level Redis interface instance.

Parameters:
  • address (tuple or str) – An address where to connect. Can be a (host, port) tuple or unix domain socket path string.
  • db (int) – Redis database index to switch to when connected.
  • password (str or None) – Password to use if redis server instance requires authorization.
  • encoding (str or None) – Codec to use for response decoding.
  • commands_factory (callable) – A factory accepting single parameter – RedisConnection instance and returning an object providing high-level interface to Redis. Redis by default.
  • loop (EventLoop) – An optional event loop instance (uses asyncio.get_event_loop() if not specified).
aioredis.create_reconnecting_redis(address, *, db=0, password=None, encoding=None, commands_factory=Redis, loop=None)

Like create_redis() this coroutine creates high-level Redis interface instance that may reconnect to redis server between requests. Accepts same arguments as create_redis().

The reconnect process is done at most once, at the start of the request. So if your request is broken in the middle of sending or receiving reply, it will not be repeated but an exception is raised.

Note

There are two important differences between create_redis() and create_reconnecting_redis():

  1. The create_reconnecting_redis() does not establish connection “right now”, it defers connection establishing to the first request.
  2. Methods of Redis() factory returned do not buffer commands until you yield from it. I.e. they are real coroutines not the functions returning future. It may impact your pipelining.
class aioredis.Redis(connection)

High-level Redis commands interface.

For details see mixins reference.