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 toasyncio.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: 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 acceptaioredis.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: 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: - TypeError – When
db
parameter is not int. - ValueError – When
db
parameter is less then 0.
Return True: Always returns True or raises exception.
- TypeError – When
-
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 passinglambda 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 toasyncio.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 then0
.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()
-
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 toasyncio.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 ascreate_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()
andcreate_reconnecting_redis()
:- The
create_reconnecting_redis()
does not establish connection “right now”, it defers connection establishing to the first request. - 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.
- The
-
class
aioredis.
Redis
(connection) High-level Redis commands interface.
For details see mixins reference.