`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_uri():
    conn = await aioredis.create_connection(
        'redis://localhost/0')
    val = await conn.execute('GET', 'my-key')

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')
    # or uri 'unix:///path/to/redis/socket?db=1'
    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, parser=None, loop=None, timeout=None)¶

Creates Redis connection.

Changed in version v0.3.1: timeout argument added.

Changed in version v1.0: parser argument added.

Parameters:

address (tuple or str) –
An address where to connect. Can be one of the following:
- a Redis URI — "redis://host:6379/0?encoding=utf-8";
- a (host, port) tuple — ('localhost', 6379);
- or a unix domain socket path string — "/path/to/redis.sock".
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.
parser (callable or None) – Protocol parser class. Can be used to set custom protocol reader; expected same interface as hiredis.Reader.
loop (EventLoop) – An optional event loop instance (uses asyncio.get_event_loop() if not specified).
timeout (float greater than 0 or None) – Max time 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:	TypeError – When any of arguments is None or can not be encoded as bytes. aioredis.ReplyError – For redis error replies. aioredis.ProtocolError – When response can not be decoded and/or connection is broken.
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.

All pending commands will be canceled with ConnectionForcedCloseError.

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:	TypeError – When `db` parameter is not int. ValueError – When `db` parameter is less then 0.
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 aioredis

async def sample_pool():
    pool = await aioredis.create_pool('redis://localhost')
    val = await pool.execute('get', 'my-key')

aioredis.create_pool(address, *, db=0, password=None, ssl=None, encoding=None, minsize=1, maxsize=10, parser=None, loop=None, create_connection_timeout=None, pool_cls=None, connection_cls=None)¶

A coroutine that instantiates a pool of RedisConnection.

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

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

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

Changed in version v0.3.2: create_connection_timeout argument added.

New in version v1.0: parser, pool_cls and connection_cls arguments added.

Parameters:

address (tuple or str) –
An address where to connect. Can be one of the following:
- a Redis URI — "redis://host:6379/0?encoding=utf-8";
- a (host, port) tuple — ('localhost', 6379);
- or a unix domain socket path string — "/path/to/redis.sock".
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.
parser (callable or None) – Protocol parser class. Can be used to set custom protocol reader; expected same interface as hiredis.Reader.
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 to open a connection, otherwise raise an asyncio.TimeoutError. None by default.
pool_cls (aioredis.abc.AbcPool) – Can be used to instantiate custom pool class. This argument must be a subclass of AbcPool.
connection_cls (aioredis.abc.AbcConnection) – Can be used to make pool instantiate custom connection classes. This argument must be a subclass of AbcConnection.

Returns:

ConnectionsPool instance.

class aioredis.ConnectionsPool¶

Bases: abc.AbcPool

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.

execute(command, *args, **kwargs)¶

Execute Redis command in a free connection and return asyncio.Future waiting for result.

This method tries to pick a free connection from pool and send command through it at once (keeping pipelining feature provided by aioredis.RedisConnection.execute()). If no connection is found — returns coroutine waiting for free connection to execute command.

New in version v1.0.

execute_pubsub(command, *channels)¶

Execute Redis (p)subscribe/(p)unsubscribe command.

ConnectionsPool picks separate free connection for pub/sub and uses it until pool is closed or connection is disconnected (unsubscribing from all channels/pattern will leave connection locked for pub/sub use).

There is no auto-reconnect for Pub/Sub connection as this will hide from user messages loss.

Has similar to execute() behavior, ie: tries to pick free connection from pool and switch it to pub/sub mode; or fallback to coroutine waiting for free connection and repeating operation.

New in version v1.0.

get_connection(command, args=())¶

Gets free connection from pool returning tuple of (connection, address).

If no free connection is found – None is returned in place of connection.

Return type:	tuple(`RedisConnection` or None, str)

New in version v1.0.

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(command=None, args=())¶

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

Parameters:	command – reserved for future. args – reserved for future.
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¶

Bases:	`Exception`

Base exception class for aioredis exceptions.

exception aioredis.ProtocolError¶

Bases:	`RedisError`

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

exception aioredis.ReplyError¶

Bases:	`RedisError`

Raised for Redis error replies.

exception aioredis.MaxClientsError¶

Bases:	`ReplyError`

Raised when maximum number of clients has been reached (Redis server configured value).

exception aioredis.AuthError¶

Bases:	`ReplyError`

Raised when authentication errors occur.

exception aioredis.ConnectionClosedError¶

Bases:	`RedisError`

Raised if connection to server was lost/closed.

exception aioredis.ConnectionForcedCloseError¶

Bases:	`ConnectionClosedError`

Raised if connection was closed with RedisConnection.close() method.

exception aioredis.PipelineError¶

Bases:	`RedisError`

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

exception aioredis.MultiExecError¶

Bases:	`PipelineError`

Same as PipelineError but raised when executing multi_exec block.

exception aioredis.WatchVariableError¶

Bases:	`MultiExecError`

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

exception aioredis.ChannelClosedError¶

Bases:	`RedisError`

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

exception aioredis.PoolClosedError¶

Bases:	`RedisError`

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

exception aioredis.ReadOnlyError¶

Bases:	`RedisError`

Raised from slave when read-only mode is enabled.

exception aioredis.MasterNotFoundError¶

Bases:	`RedisError`

Raised by Sentinel client if it can not find requested master.

exception aioredis.SlaveNotFoundError¶

Bases:	`RedisError`

Raised by Sentinel client if it can not find requested slave.

exception aioredis.MasterReplyError¶

Bases:	`RedisError`

Raised if establishing connection to master failed with RedisError, for instance because of required or wrong authentication.

exception aioredis.SlaveReplyError¶

Bases:	`RedisError`

Raised if establishing connection to slave failed with RedisError, for instance because of required or wrong authentication.

Exceptions Hierarchy¶

Exception
   RedisError
      ProtocolError
      ReplyError
         MaxClientsError
         AuthError
      PipelineError
         MultiExecError
            WatchVariableError
      ChannelClosedError
      ConnectionClosedError
         ConnectionForcedCloseError
      PoolClosedError
      ReadOnlyError
      MasterNotFoundError
      SlaveNotFoundError
      MasterReplyError
      SlaveReplyError

Commands Interface¶

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

The usage is as simple as:

import aioredis

# Create Redis client bound to single non-reconnecting connection.
async def single_connection():
   redis = await aioredis.create_redis(
      'redis://localhost')
   val = await redis.get('my-key')

# Create Redis client bound to connections pool.
async def pool_of_connections():
   redis = await aioredis.create_redis_pool(
      'redis://localhost')
   val = await redis.get('my-key')

   # we can also use pub/sub as underlying pool
   #  has several free connections:
   ch1, ch2 = await redis.subscribe('chan:1', 'chan:2')
   # publish using free connection
   await redis.publish('chan:1', 'Hello')
   await ch1.get()

For commands reference — see commands mixins reference.

coroutine aioredis.create_redis(address, *, db=0, password=None, ssl=None, encoding=None, commands_factory=Redis, parser=None, timeout=None, connection_cls=None, loop=None)¶

This coroutine creates high-level Redis interface instance bound to single Redis connection (without auto-reconnect).

New in version v1.0: parser, timeout and connection_cls arguments added.

See also RedisConnection for parameters description.

Parameters:

address (tuple or str) – An address where to connect. Can be a (host, port) tuple, unix domain socket path string or a Redis URI string.
db (int) – Redis database index to switch to when connected.
password (str or bytes 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 – object implementing AbcConnection and returning an instance providing high-level interface to Redis. Redis by default.
parser (callable or None) – Protocol parser class. Can be used to set custom protocol reader; expected same interface as hiredis.Reader.
timeout (float greater than 0 or None) – Max time to open a connection, otherwise raise asyncio.TimeoutError exception. None by default
connection_cls (aioredis.abc.AbcConnection) – Can be used to instantiate custom connection class. This argument must be a subclass of AbcConnection.
loop (EventLoop) – An optional event loop instance (uses asyncio.get_event_loop() if not specified).

Returns:

Redis client (result of commands_factory call), Redis by default.

coroutine aioredis.create_redis_pool(address, *, db=0, password=None, ssl=None, encoding=None, commands_factory=Redis, minsize=1, maxsize=10, parser=None, timeout=None, pool_cls=None, connection_cls=None, loop=None)¶

This coroutine create high-level Redis client instance bound to connections pool (this allows auto-reconnect and simple pub/sub use).

See also ConnectionsPool for parameters description.

Changed in version v1.0: parser, timeout, pool_cls and connection_cls arguments added.

Parameters:

address (tuple or str) – An address where to connect. Can be a (host, port) tuple, unix domain socket path string or a Redis URI string.
db (int) – Redis database index to switch to when connected.
password (str or bytes 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 – object implementing AbcConnection interface and returning an instance providing high-level interface to Redis. Redis by default.
minsize (int) – Minimum number of connections to initialize and keep in pool. Default is 1.
maxsize (int) – Maximum number of connections that can be created in pool. Default is 10.
parser (callable or None) – Protocol parser class. Can be used to set custom protocol reader; expected same interface as hiredis.Reader.
timeout (float greater than 0 or None) – Max time to open a connection, otherwise raise asyncio.TimeoutError exception. None by default
pool_cls (aioredis.abc.AbcPool) – Can be used to instantiate custom pool class. This argument must be a subclass of AbcPool.
connection_cls (aioredis.abc.AbcConnection) – Can be used to make pool instantiate custom connection classes. This argument must be a subclass of AbcConnection.
loop (EventLoop) – An optional event loop instance (uses asyncio.get_event_loop() if not specified).

Returns:

Redis client (result of commands_factory call), Redis by default.

aioredis — API Reference¶

Connection¶

Connections Pool¶

Pub/Sub Channel object¶

Exceptions¶

Exceptions Hierarchy¶

Commands Interface¶

`aioredis` — API Reference¶