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
orMapping
.Pure tokens used as flags are mapped to boolean arguments
One of
arguments accepting pure tokens are collapsed and accept aPureToken
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
Miscellaneous
“Pretty complete” Type Annotations for public API
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
& 7.4.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.9
3.10
3.11
3.12
3.13
PyPy 3.9
PyPy 3.10
Support for Redis API compatible 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
andKeyDBCluster
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
to2
.
Compatibility tests for the above are included in the continuous integration test matrix here.