Skip to content
This repository has been archived by the owner on Feb 21, 2023. It is now read-only.

Latest commit

 

History

History
839 lines (529 loc) · 24.3 KB

api_reference.rst

File metadata and controls

839 lines (529 loc) · 24.3 KB
Raw

aioredis --- API Reference

python3

aioredis

Connection

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

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())

create_connection(address, *, db=0, password=None, ssl=None,encoding=None, parser=None,timeout=None, connection_cls=None)

Creates Redis connection.

v0.3.1 timeout argument added.

v1.0 parser argument added.

v1.3.1 loop argument deprecated for Python 3.8 compatibility.

param address

An address where to connect. Can be one of the following:

  • a Redis URI --- "redis://host:6379/0?encoding=utf-8"; "redis://:password@host:6379/0?encoding=utf-8";
  • a (host, port) tuple --- ('localhost', 6379);
  • or a unix domain socket path string --- "/path/to/redis.sock".
type address

tuple or str

param int db

Redis database index to switch to when connected.

param password

Password to use if redis server instance requires authorization.

type password

str or None

param ssl

SSL context that is passed through to asyncio.BaseEventLoop.create_connection.

type ssl

ssl.SSLContext or True or None

param encoding

Codec to use for response decoding.

type encoding

str or None

param parser

Protocol parser class. Can be used to set custom protocol reader; expected same interface as hiredis.Reader.

type parser

callable or None

param timeout

Max time to open a connection, otherwise raise asyncio.TimeoutError exception. None by default

type timeout

float greater than 0 or None

param connection_cls

Custom connection class. None by default.

type connection_cls

abc.AbcConnection or None

return

RedisConnection instance.

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.

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 ~aioredis.Channel instances.

pubsub_patterns

Read-only dict with subscribed patterns. Keys are bytes, values are ~aioredis.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.

param command

Command to execute

type command

str, bytes, bytearray

param encoding

Keyword-only argument for overriding response decoding. By default will use connection-wide encoding. May be set to None to skip response decoding.

type encoding

str or None

raise TypeError

When any of arguments is None or can not be encoded as bytes.

raise aioredis.ReplyError

For redis error replies.

raise aioredis.ProtocolError

When response can not be decoded and/or connection is broken.

return

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)
>>> await conn.execute_pubsub('subscribe', ch1)
[[b'subscribe', b'A', 1]]

v0.3 The method accept ~aioredis.Channel instances.

param command

One of the following Pub/Sub commands: subscribe, unsubscribe, psubscribe, punsubscribe.

type command

str, bytes, bytearray

param *channels_or_patterns

Channels or patterns to subscribe connection to or unsubscribe from. At least one channel/pattern is required.

return

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.

param int db

New redis database index.

raise TypeError

When db parameter is not int.

raise ValueError

When db parameter is less than 0.

return True

Always returns True or raises exception.

auth(password)

Send AUTH command.

param str password

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')

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

A coroutine<coroutine> that instantiates a pool of ~.RedisConnection.

v0.2.7 minsize default value changed from 10 to 1.

v0.2.8 Disallow arbitrary ConnectionsPool maxsize.

v0.2.9 commands_factory argument is deprecated and will be removed in v1.0.

v0.3.2 create_connection_timeout argument added.

v1.0 parser, pool_cls and connection_cls arguments added.

v1.3.1 loop argument deprecated for Python 3.8 compatibility.

param address

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".
type address

tuple or str

param int db

Redis database index to switch to when connected.

param password

Password to use if redis server instance requires authorization.

type password

str or None

param ssl

SSL context that is passed through to asyncio.BaseEventLoop.create_connection.

type ssl

ssl.SSLContext or True or None

param encoding

Codec to use for response decoding.

type encoding

str or None

param int minsize

Minimum number of free connection to create in pool. 1 by default.

param int maxsize

Maximum number of connection to keep in pool. 10 by default. Must be greater than 0. None is disallowed.

param parser

Protocol parser class. Can be used to set custom protocol reader; expected same interface as hiredis.Reader.

type parser

callable or None

param create_connection_timeout

Max time to open a connection, otherwise raise an asyncio.TimeoutError. None by default.

type create_connection_timeout

float greater than 0 or None

param pool_cls

Can be used to instantiate custom pool class. This argument must be a subclass of ~aioredis.abc.AbcPool.

type pool_cls

aioredis.abc.AbcPool

param connection_cls

Can be used to make pool instantiate custom connection classes. This argument must be a subclass of ~aioredis.abc.AbcConnection.

type connection_cls

aioredis.abc.AbcConnection

return

ConnectionsPool instance.

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.

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.

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.

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.

rtype

tuple(RedisConnection or None, str)

v1.0

clear()

Closes and removes all free connections in the pool.

select(db)

Changes db index for all free connections in the pool.

param int db

New database index.

acquire(command=None, args=())

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

param command

reserved for future.

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

param aioredis.RedisConnection conn

A RedisConnection instance.

close()

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

v0.2.8

wait_closed()

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

v0.2.8

Exceptions

RedisError

Bases

Exception

Base exception class for aioredis exceptions.

ProtocolError

Bases

RedisError

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

ReplyError

Bases

RedisError

Raised for Redis error replies.

MaxClientsError

Bases

ReplyError

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

AuthError

Bases

ReplyError

Raised when authentication errors occur.

ConnectionClosedError

Bases

RedisError

Raised if connection to server was lost/closed.

ConnectionForcedCloseError

Bases

ConnectionClosedError

Raised if connection was closed with RedisConnection.close method.

PipelineError

Bases

RedisError

Raised from ~.commands.TransactionsCommandsMixin.pipeline if any pipelined command raised error.

MultiExecError

Bases

PipelineError

Same as ~.PipelineError but raised when executing multi_exec block.

WatchVariableError

Bases

MultiExecError

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

ChannelClosedError

Bases

RedisError

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

PoolClosedError

Bases

RedisError

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

ReadOnlyError

Bases

RedisError

Raised from slave when read-only mode is enabled.

MasterNotFoundError

Bases

RedisError

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

SlaveNotFoundError

Bases

RedisError

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

MasterReplyError

Bases

RedisError

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

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

Pub/Sub Channel object

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

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.

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.

param str encoding

If not None used to decode resulting bytes message.

param callable decoder

If specified used to decode message, ex. json.loads()

raise 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)

wait_message()

Waits for message to become available in channel or channel is closed (unsubscribed).

Main idea is to use it in loops:

>>> ch = redis.channels['channel:1'] >>> while await ch.wait_message(): ... msg = await ch.get()

rtype

bool

iter(, *, encoding=None, decoder=None)

Same as ~.get method but it is a native coroutine.

Usage example:

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

0.2.5 Available for Python 3.5 only

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 <aioredis-commands>.

create_redis(address, *, db=0, password=None, ssl=None,encoding=None, commands_factory=Redis,parser=None, timeout=None,connection_cls=None)

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

v1.0 parser, timeout and connection_cls arguments added.

v1.3.1 loop argument deprecated for Python 3.8 compatibility.

See also ~aioredis.RedisConnection for parameters description.

param address

An address where to connect. Can be a (host, port) tuple, unix domain socket path string or a Redis URI string.

type address

tuple or str

param int db

Redis database index to switch to when connected.

param password

Password to use if Redis server instance requires authorization.

type password

str or bytes or None

param ssl

SSL context that is passed through to asyncio.BaseEventLoop.create_connection.

type ssl

ssl.SSLContext or True or None

param encoding

Codec to use for response decoding.

type encoding

str or None

param commands_factory

A factory accepting single parameter --object implementing ~abc.AbcConnection and returning an instance providing high-level interface to Redis. Redis by default.

type commands_factory

callable

param parser

Protocol parser class. Can be used to set custom protocol reader; expected same interface as hiredis.Reader.

type parser

callable or None

param timeout

Max time to open a connection, otherwise raise asyncio.TimeoutError exception. None by default

type timeout

float greater than 0 or None

param connection_cls

Can be used to instantiate custom connection class. This argument must be a subclass of ~aioredis.abc.AbcConnection.

type connection_cls

aioredis.abc.AbcConnection

returns

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

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,)

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

See also ~aioredis.ConnectionsPool for parameters description.

v1.0 parser, timeout, pool_cls and connection_cls arguments added.

v1.3.1 loop argument deprecated for Python 3.8 compatibility.

param address

An address where to connect. Can be a (host, port) tuple, unix domain socket path string or a Redis URI string.

type address

tuple or str

param int db

Redis database index to switch to when connected.

param password

Password to use if Redis server instance requires authorization.

type password

str or bytes or None

param ssl

SSL context that is passed through to asyncio.BaseEventLoop.create_connection.

type ssl

ssl.SSLContext or True or None

param encoding

Codec to use for response decoding.

type encoding

str or None

param commands_factory

A factory accepting single parameter --object implementing ~abc.AbcConnection interface and returning an instance providing high-level interface to Redis. Redis by default.

type commands_factory

callable

param int minsize

Minimum number of connections to initialize and keep in pool. Default is 1.

param int maxsize

Maximum number of connections that can be created in pool. Default is 10.

param parser

Protocol parser class. Can be used to set custom protocol reader; expected same interface as hiredis.Reader.

type parser

callable or None

param timeout

Max time to open a connection, otherwise raise asyncio.TimeoutError exception. None by default

type timeout

float greater than 0 or None

param pool_cls

Can be used to instantiate custom pool class. This argument must be a subclass of ~aioredis.abc.AbcPool.

type pool_cls

aioredis.abc.AbcPool

param connection_cls

Can be used to make pool instantiate custom connection classes. This argument must be a subclass of ~aioredis.abc.AbcConnection.

type connection_cls

aioredis.abc.AbcConnection

returns

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