Repository: redis/redis-py
Stars: 13523
README.md
redis-py
The Python interface to the Redis key-value store.
Installation | Usage | Advanced Topics | Contributing
---------------------------------------------
Note: redis-py 5.0 is the last version of redis-py that supports Python 3.7, as it has reached end of life. redis-py 5.1 supports Python 3.8+.<br>
Note: redis-py 6.1.0 is the last version of redis-py that supports Python 3.8, as it has reached end of life. redis-py 6.2.0 supports Python 3.9+.
---------------------------------------------
How do I Redis?
Learn for free at Redis University
Installation
Start a redis via docker (for Redis versions >= 8.0):
`` The most recent version of this library supports Redis version 7.2, 7.4, 8.0 and 8.2. The table below highlights version compatibility of the most-recent library versions and redis versions. | Library version | Supported redis versions | By default, redis-py uses a connection pool to manage connections. Each instance of a Redis class receives its own connection pool. You can however define your own redis.ConnectionPool. There is built-in support for all of the out-of-the-box Redis commands. They are exposed using the raw Redis command names ( The official Redis command documentation - MULTI/EXEC: These are implemented as part of the Pipeline class. - SUBSCRIBE/LISTEN: Similar to pipelines, PubSub is implemented as For more details, please see the documentation on advanced topics page. The following is a basic example of a Redis pipeline, a method to optimize round-trip calls, by batching Redis commands, and receiving their results as a list. The following example shows how to utilize Redis Pub/Sub to subscribe to specific channels. Release 6.0.0 introduces a client-side default dialect for Redis’ search and query capabilities. Important: Be aware that the query dialect may impact the results returned. If needed, you can revert to a different dialect version by configuring the client accordingly. bash
docker run -p 6379:6379 -it redis:latestStart a redis via docker (for Redis versions < 8.0):
docker run -p 6379:6379 -it redis/redis-stack:latestTo install redis-py, simply:
$ pip install redisFor faster performance, install redis with hiredis support, this provides a compiled response parser, and for most cases requires zero code changes.
By default, if hiredis >= 1.0 is available, redis-py will attempt to use it for response parsing.
$ pip install "redis[hiredis]"Looking for a high-level library to handle object mapping? See redis-om-python!Supported Redis Versions
|-----------------|-------------------|
| 3.5.3 | <= 6.2 Family of releases |
| >= 4.5.0 | Version 5.0 to 7.0 |
| >= 5.0.0 | Version 5.0 to 7.4 |
| >= 6.0.0 | Version 7.2 to current |Usage
Basic Example
>>> import redis
>>> r = redis.Redis(host='localhost', port=6379, db=0)
>>> r.set('foo', 'bar')
True
>>> r.get('foo')
b'bar'The above code connects to localhost on port 6379, sets a value in Redis, and retrieves it. All responses are returned as bytes in Python, to receive decoded strings, set decode_responses=True. For this, and more connection options, see these examples.
#### RESP3 Support
RESP3 is the default protocol used by the client.
To use support for RESP3, ensure you have at least version 5.0 of the client.
>>> import redis
>>> r = redis.Redis(host='localhost', port=6379, db=0, protocol=3)#### RESP2 Support
To use support for RESP2, ensure you provide protocol=2 when creating the client.
>>> import redis
>>> r = redis.Redis(host='localhost', port=6379, db=0, protocol=2)Connection Pools
>>> pool = redis.ConnectionPool(host='localhost', port=6379, db=0)
>>> r = redis.Redis(connection_pool=pool)Alternatively, you might want to look at Async connections, or Cluster connections, or even Async Cluster connections.HSETRedis Commands
, HGETALL, etc.) except where a word (i.e. del) is reserved by the language. The complete set of commands can be found here, or the documentation.Advanced Topics
does a great job of explaining each command in detail. redis-py attempts
to adhere to the official command syntax. There are a few exceptions:
The pipeline is wrapped with the MULTI and EXEC statements by
default when it is executed, which can be disabled by specifying
transaction=False. See more about Pipelines below.
a separate class as it places the underlying connection in a state
where it can\'t execute non-pubsub commands. Calling the pubsub
method from the Redis client will return a PubSub instance where you
can subscribe to channels and listen for messages. You can only call
PUBLISH from the Redis client (see this comment on issue
#151
for details).Pipelines
>>> pipe = r.pipeline()
>>> pipe.set('foo', 5)
>>> pipe.set('bar', 18.5)
>>> pipe.set('blee', "hello world!")
>>> pipe.execute()
[True, True, True]PubSub
>>> r = redis.Redis(...)
>>> p = r.pubsub()
>>> p.subscribe('my-first-channel', 'my-second-channel', ...)
>>> p.get_message()
{'pattern': None, 'type': 'subscribe', 'channel': b'my-second-channel', 'data': 1}Redis’ search and query capabilities default dialect
By default, the client now overrides the server-side dialect with version 2, automatically appending DIALECT 2 to commands like FT.AGGREGATE and FT.SEARCH.
>>> from redis.commands.search.field import TextField
>>> from redis.commands.search.query import Query
>>> from redis.commands.search.index_definition import IndexDefinition
>>> import redis
>>> r = redis.Redis(host='localhost', port=6379, db=0)
>>> r.ft().create_index(
>>> (TextField("name"), TextField("lastname")),
>>> definition=IndexDefinition(prefix=["test:"]),
>>> )
>>> r.hset("test:1", "name", "James")
>>> r.hset("test:1", "lastname", "Brown")
>>> # Query with default DIALECT 2
>>> query = "@name: James Brown"
>>> q = Query(query)
>>> res = r.ft().search(q)
>>> # Query with explicit DIALECT 1
>>> query = "@name: James Brown"
>>> q = Query(query).dialect(1)
>>> res = r.ft().search(q)
``
You can find further details in the query dialect documentation.
Multi-database client (Active-Active)
The multi-database client allows your application to connect to multiple Redis databases, which are typically replicas of each other. It is designed to work with Redis Software and Redis Cloud Active-Active setups. The client continuously monitors database health, detects failures, and automatically fails over to the next healthy database using a configurable strategy. When the original database becomes healthy again, the client can automatically switch back to it.<br>
This is useful when:
1. You have more than one Redis deployment. This might include two independent Redis servers or two or more Redis databases replicated across multiple active-active Redis Enterprise clusters.
2. You want your application to connect to one deployment at a time and to fail over to the next available deployment if the first deployment becomes unavailable.
For the complete failover configuration options and examples, see the Multi-database client docs.
---------------------------------------------
Author
redis-py is developed and maintained by Redis Inc. It can be found here, or downloaded from pypi.
Special thanks to:
- Andy McCurdy (<[email protected]>) the original author of redis-py.
- Ludovico Magnocavallo, author of the original Python Redis client,
from which some of the socket code is still used.
- Alexander Solovyov for ideas on the generic response callback
system.
- Paul Hubbard for initial packaging support.
