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: - 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)
-
close
()¶ Closes connection.
-
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
-
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 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.