API Reference

exception siderpy.SiderPyError

Bases: Exception

Base error

exception siderpy.RedisError

Bases: siderpy.SiderPyError

Redis error

exception siderpy.QueueClosedError

Bases: siderpy.SiderPyError

Closed PubSub queue error

class siderpy.Redis(url: str = 'redis://localhost:6379/0', connect_timeout: Union[float, int] = None, timeout: Union[float, tuple, list] = None, ssl_ctx: ssl.SSLContext = None, encoding=None, errors=None, pubsub_queue_maxsize=None)

Bases: object

Class representing a single connection to a Redis server. Connection to the server is established automatically during first request.

Examples

>>> import siderpy
>>> redis = siderpy.Redis('redis://username:password@localhost:6379/0')
>>> await redis.ping()
>>> ...
>>> await redis.close()
__init__(url: str = 'redis://localhost:6379/0', connect_timeout: Union[float, int] = None, timeout: Union[float, tuple, list] = None, ssl_ctx: ssl.SSLContext = None, encoding=None, errors=None, pubsub_queue_maxsize=None)
Parameters

  • url (str, optional) –

    The Redis server url and settings to connect as uri:

    • redis://[USERNAME][:PASSWORD@]HOST[:PORT]/[DATABASE]

    • redis+unix://[USERNAME][:PASSWORD@]SOCKET_PATH[?db=DATABASE]

    • redis-socket://[USERNAME][:PASSWORD@]SOCKET_PATH[?db=DATABASE]

    default: redis://localhost:6379/0

  • connect_timeout (float, optional) – Timeout used to get initialized Redis instance and as ssl_handshake_timeout argument for asyncio.open_connection call.

  • timeout (float, optional) –

    Timeout used for read and write operations. It is possibly to specify separately values for read and write.

    Example

    >>> Redis(timeout=(read_timeout, write_timeout))

    If common or read timeout is specified it will affect all Redis blocking read commands such as blpop, etc. For example, this code will raise asyncio.TimeoutError after one second though a timeout of zero for blpop command can be used to block indefinitely.

    >>> redis = siderpy.Redis(timeout=1)
>>> await redis.blpop('empty_list', 0)  # asyncio.TimeoutError exception
>>>                                     # will occur here after 1 second

    To avoid this situation set read timeout to None.

    >>> redis = siderpy.Redis(timeout=(None, 15))
>>> await redis.blpop('empty_list', 0)  # will block indefinitely

  • encoding (str, optional) – Encoding with which to decode raw data(bytes) from Redis.

  • errors (str, optional) – Error handling scheme to use for handling of decoding errors.

  • ssl_ctx (ssl.SSLContext, optional) – SSL context object to enable SSL(TLS).

async close()

Close established connection

async delete(*args)

Redis del command

async execute()

Redis exec command

async execute_cmd(cmd_name: str, *args)

Execute Redis command

Parameters

cmd_name (str, optional) – Redis command name.

Example

>>> result = await redis.execute_cmd('get', 'key')
classmethod parse_url(url: str) → dict
pipeline()

Pipeline mode contextmanager

Example

>>> with redis.pipeline():
>>>     await redis.set('key1', 'value2')
>>>     await redis.set('key2', 'value2')
>>>     await redis.mget('key1', 'key2')
>>> result = await redis.pipeline_execute()

Also it’s possible to resume or execute pipeline later, for example:

>>> with redis.pipeline():
>>>     await redis.set('key1', 'value2')
>>> # pause pipeline, do other stuff
>>> ...
>>> # continue with pipeline
>>> with redis.pipeline():
>>>     await redis.set('key2', 'value2')
>>> result = await redis.pipeline_execute()
pipeline_clear()

Clear internal pipeline buffer

async pipeline_execute()

Execute pipeline buffer

pipeline_off()

Disable pipeline mode

pipeline_on()

Enable pipeline mode. In this mode, all commands are saved to the internal pipeline buffer until pipeline_off() method is invoked directly. To execute stored buffer call pipeline_execute()

property pubsub_queue

Instance of PubSubQueue class. Holds incomming messages.

class siderpy.RedisPool(url: str = 'redis://localhost:6379/0', connect_timeout: float = None, timeout: Union[float, tuple, list] = None, size: int = 4, pool_cls=<class 'siderpy.Pool'>, ssl_ctx: ssl.SSLContext = None)

Bases: object

Class representing a pool of connections to a Redis server

>>> import siderpy
>>> pool = siderpy.RedisPool('redis://localhost:6379/0', size=10)
>>> await pool.ping()
>>> await pool.get('key')
>>> ...
>>> await pool.close()

Pool doesn’t implement multi/exec and pub/sub commands. For performance reasons it’s better to use Redis instance as command executor instead of pool itself. For example:

>>> with pool.get_redis() as redis:
>>>     await redis.set(...)
>>>     await redis.get(...)
>>>     ...
__init__(url: str = 'redis://localhost:6379/0', connect_timeout: float = None, timeout: Union[float, tuple, list] = None, size: int = 4, pool_cls=<class 'siderpy.Pool'>, ssl_ctx: ssl.SSLContext = None)
Parameters

  • url (str, optional) – same as url argument for Redis.

  • connect_timeout (float, optional) – same as connect_timeout argument for Redis.

  • timeout (float, optional) – same as timeout argument for Redis.

  • size (int, optional) – Pool size.

  • ssl_ctx (ssl.SSLContext, optional) – same as ssl_ctx argument for Redis.

async close()

Close all established connections

async delete(*args)

Redis del command

get_redis(timeout: float = None)

Context manager for getting Redis instance

Parameters

timeout (float) – Timeout to get Redis instance

>>> async with pool.get_redis() as redis:
>>>     await redis.ping()