coredis#

coredis is an async redis client with support for redis server, cluster & sentinel. The client API uses the specifications in the Redis command documentation to define the API by using the following conventions:

The coredis Clients use the specifications in the Redis command documentation to define the API by using the following conventions:

Arguments retain naming from redis as much as possible
Only optional variadic arguments are mapped to position or keyword variadic arguments. When the variable length arguments are not optional the expected argument is an iterable of type Parameters or Mapping.
Pure tokens used as flags are mapped to boolean arguments
One of arguments accepting pure tokens are collapsed and accept a PureToken
Responses are mapped as closely from RESP <-> python types as possible.

For higher level concepts such as Pipelines, LUA Scripts, PubSub abstractions are provided to encapsulate recommended patterns.

Warning

The command API does NOT mirror the official python redis client. For details about the high level differences refer to Divergence from aredis & redis-py

Feature Summary#

Clients for different topologies
Application patterns
Server side scripting
- LUA Scripts
- Library Functions
Redis Modules

Miscellaneous

“Pretty complete” Type Annotations for public API

$ PYTHONPATH=$(pwd) pyright --verifytypes=coredis 2>&1 | grep completeness
Type completeness score: 92.9%

Runtime Type checking

Installation#

Released versions of coredis published on pypi contain precompiled native extensions for various architectures that provide significant performance improvements especially when dealing with large bulk responses.

$ pip install coredis

Getting started#

Single Node or Cluster client#

import asyncio
from coredis import Redis, RedisCluster

async def example():
    client = Redis(host='127.0.0.1', port=6379, db=0)
    # or with redis cluster
    # client = RedisCluster(startup_nodes=[{"host": "127.0.01", "port": 7001}])
    await client.flushdb()
    await client.set('foo', 1)
    assert await client.exists(['foo']) == 1
    assert await client.incr('foo') == 2
    assert await client.incrby('foo', increment=100) == 102
    assert int(await client.get('foo')) == 102

    assert await client.expire('foo', 1)
    await asyncio.sleep(0.1)
    assert await client.ttl('foo') == 1
    assert await client.pttl('foo') < 1000
    await asyncio.sleep(1)
    assert not await client.exists(['foo'])

asyncio.run(example())

Sentinel#

import asyncio
from coredis.sentinel import Sentinel

async def example():
    sentinel = Sentinel(sentinels=[("localhost", 26379)])
    primary = sentinel.primary_for("myservice")
    replica = sentinel.replica_for("myservice")

    assert await primary.set("fubar", 1)
    assert int(await replica.get("fubar")) == 1

asyncio.run(example())

Compatibility#

coredis is tested against redis versions 6.2.x, 7.0.x & 7.2.x. The test matrix status can be reviewed here

Note

Though coredis officially only supports Redis version: 6.0.0 and above it is known to work with lower versions.

A known compatibility issue with older redis versions is the lack of support for RESP3 and the HELLO command. The default Redis and RedisCluster clients do not work in this scenario as the HELLO command is used for initial handshaking to confirm that the default RESP3 protocol version can be used and to perform authentication if necessary.

This can be worked around by passing 2 to coredis.Redis.protocol_version to downgrade to RESP (see Redis Response).

When using RESP coredis will also fall back to the legacy AUTH command if the HELLO is not supported.

coredis is additionally tested against:

uvloop >= 0.15.0.

Supported python versions#

3.8
3.9
3.10
3.11
PyPy 3.8
PyPy 3.9

Support for Redis-“like” databases#

coredis is known to work with the following databases that have redis protocol compatibility:

KeyDB

KeyDB exposes a few commands that don’t exist in redis and these are exposed by the KeyDB and KeyDBCluster clients respectively.

Dragonfly

Dragonfly currently has compatibility with redis 6.2, though there is increasing support for commands from higher versions. For up to date details please refer to the dragonfly api status documentation.

To see which functionality of coredis is tested against dragonfly, checkout a copy of coredis and run the following:

pytest --collect-only -m dragonfly

Warning

Since dragonfly does not yet support RESP3 (which is the default protocol version for coredis) connecting to a dragonfly instance requires setting coredis.Redis.protocol_version to 2.

Compatibility tests for the above are included in the continuous integration test matrix here.