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

async def connect_tcp():
    conn = await aioredis.create_connection(
        ('localhost', 6379))
    val = await conn.execute('GET', 'my-key')

async def connect_unixsocket():
    conn = await aioredis.create_connection(
        '/path/to/redis/socket')
    val = await conn.execute('GET', 'my-key')

asyncio.get_event_loop().run_until_complete(connect_tcp())
asyncio.get_event_loop().run_until_complete(connect_unixsocket())
coroutine aioredis.create_connection(address, *, db=0, password=None, ssl=None, encoding=None, loop=None, timeout=None)

Creates Redis connection.

Changed in version v0.3.1: timeout argument added.

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.
  • ssl (ssl.SSLContext or True or None) – SSL context that is passed through to asyncio.BaseEventLoop.create_connection().
  • 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).
  • timeout (float greater than 0 or None) – Max time used to open a connection, otherwise raise asyncio.TimeoutError exception. None by default
Returns:

RedisConnection instance.

class aioredis.RedisConnection

Bases: abc.AbcConnection

Redis connection interface.

address

Redis server address; either IP-port tuple or unix socket str (read-only). IP is either IPv4 or IPv6 depending on resolved host part in initial address.

New in version v0.2.8.

db

Current database index (read-only).

encoding

Current codec for response decoding (read-only).

closed

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

in_transaction

Set to True when MULTI command was issued (read-only).

pubsub_channels

Read-only dict with subscribed channels. Keys are bytes, values are Channel instances.

pubsub_patterns

Read-only dict with subscribed patterns. Keys are bytes, values are Channel instances.

in_pubsub

Indicates that connection is in PUB/SUB mode. Provides the number of subscribed channels. Read-only.

execute(command, *args, encoding=_NOTSET)

Execute Redis command.

The method is not a coroutine itself but instead it writes to underlying transport and returns a asyncio.Future waiting for result.

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)

execute_pubsub(command, *channels_or_patterns)

Method to execute Pub/Sub commands. The method is not a coroutine itself but returns a asyncio.gather() coroutine. Method also accept aioredis.Channel instances as command arguments:

>>> ch1 = Channel('A', is_pattern=False, loop=loop)
>>> await conn.execute_pubsub('subscribe', ch1)
[[b'subscribe', b'A', 1]]

Changed in version v0.3: The method accept Channel instances.

Parameters:
  • command (str, bytes, bytearray) – One of the following Pub/Sub commands: subscribe, unsubscribe, psubscribe, punsubscribe.
  • *channels_or_patterns – Channels or patterns to subscribe connection to or unsubscribe from. At least one channel/pattern is required.
Returns:

Returns a list of subscribe/unsubscribe messages, ex:

>>> await conn.execute_pubsub('subscribe', 'A', 'B')
[[b'subscribe', b'A', 1], [b'subscribe', b'B', 2]]

close()

Closes connection.

Mark connection as closed and schedule cleanup procedure.

wait_closed()

Coroutine waiting for connection to get closed.

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’.

Connections Pool

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

import asyncio
import aioredis

async def sample_pool():
    pool = await aioredis.create_pool(('localhost', 6379))
    val = await pool.execute('get', 'my-key')
aioredis.create_pool(address, *, db=0, password=None, ssl=None, encoding=None, minsize=1, maxsize=10, commands_factory=_NOTSET, loop=None)

A coroutine that instantiates a pool of RedisConnection.

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

Changed in version v0.2.7: minsize default value changed from 10 to 1.

Changed in version v0.2.8: Disallow arbitrary RedisPool maxsize.

Deprecated since version v0.2.9: commands_factory argument is deprecated and will be removed in v0.3.

Changed in version v0.3.1: create_connection_timeout argument added.

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.
  • ssl (ssl.SSLContext or True or None) – SSL context that is passed through to asyncio.BaseEventLoop.create_connection().
  • encoding (str or None) – Codec to use for response decoding.
  • minsize (int) – Minimum number of free connection to create in pool. 1 by default.
  • maxsize (int) – Maximum number of connection to keep in pool. 10 by default. Must be greater then 0. None is disallowed.
  • commands_factory (callable) – A factory to be passed to create_redis call. Redis by default. Deprecated since v0.2.8
  • loop (EventLoop) – An optional event loop instance (uses asyncio.get_event_loop() if not specified).
  • create_connection_timeout (float greater than 0 or None) – Max time used to open a connection, otherwise raise an asyncio.TimeoutError. None by default.
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).

closed

True if pool is closed.

New in version v0.2.8.

coroutine clear()

Closes and removes all free connections in the pool.

coroutine select(db)

Changes db index for all free connections in the pool.

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

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

Raises:aioredis.PoolClosedError – if pool is already closed
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 (aioredis.RedisConnection) – A RedisConnection instance.
close()

Close all free and in-progress connections and mark pool as closed.

New in version v0.2.8.

coroutine wait_closed()

Wait until pool gets closed (when all connections are closed).

New in version v0.2.8.


Pub/Sub Channel object

Channel object is a wrapper around queue for storing received pub/sub messages.

class aioredis.Channel(name, is_pattern, loop=None)

Bases: abc.AbcChannel

Object representing Pub/Sub messages queue. It’s basically a wrapper around asyncio.Queue.

name

Holds encoded channel/pattern name.

is_pattern

Set to True for pattern channels.

is_active

Set to True if there are messages in queue and connection is still subscribed to this channel.

coroutine get(*, encoding=None, decoder=None)

Coroutine that waits for and returns a message.

Return value is message received or None signifying that channel has been unsubscribed and no more messages will be received.

Parameters:
  • encoding (str) – If not None used to decode resulting bytes message.
  • decoder (callable) – If specified used to decode message, ex. json.loads()
Raises:

aioredis.ChannelClosedError – If channel is unsubscribed and has no more messages.

get_json(*, encoding="utf-8")

Shortcut to get(encoding="utf-8", decoder=json.loads)

coroutine wait_message()

Waits for message to become available in channel.

Main idea is to use it in loops:

>>> ch = redis.channels['channel:1']
>>> while await ch.wait_message():
...     msg = await ch.get()
coroutine async-for iter()

Same as get() method but it is a native coroutine.

Usage example:

>>> async for msg in ch.iter():
...     print(msg)

New in version 0.2.5: Available for Python 3.5 only


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.ConnectionClosedError

Raised if connection to server was lost/closed.

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.

exception aioredis.WatchVariableError

Raised if watched variable changed (EXEC returns None). Subclass of MultiExecError.

exception aioredis.ChannelClosedError

Raised from aioredis.Channel.get() when Pub/Sub channel is unsubscribed and messages queue is empty.

exception aioredis.PoolClosedError

Raised from aioredis.RedisPool.acquire() when pool is already closed.

Exceptions Hierarchy

Exception
   RedisError
      ProtocolError
      ReplyError
         PipelineError
            MultiExecError
               WatchVariableError
      ChannelClosedError
      ConnectionClosedError
      PoolClosedError

Commands Interface

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

coroutine aioredis.create_redis(address, *, db=0, password=None, ssl=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.
  • ssl (ssl.SSLContext or True or None) – SSL context that is passed through to asyncio.BaseEventLoop.create_connection().
  • 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).
coroutine aioredis.create_reconnecting_redis(address, *, db=0, password=None, ssl=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.