RedisJSON Python Client
Deprecation notice
As of redis-py 4.0.0 this library is deprecated. It's features have been merged into redis-py. Please either install it from pypy or the repo.
rejson-py is a package that allows storing, updating and querying objects as JSON documents in a Redis database that is extended with the ReJSON module. The package extends redis-py's interface with ReJSON's API, and performs on-the-fly serialization/deserialization of objects to/from JSON.
Installation
$ pip install rejsonDevelopment
- Create a virtualenv to manage your python dependencies, and ensure it's active.
virtualenv -v venv - Install pypoetry to manage your dependencies.
pip install --user poetry - Install dependencies.
poetry install
tox runs all tests as its default target. Running tox by itself will run unit tests. Ensure you have a running redis, with the module loaded.
Usage example
from rejson import Client, Path
rj = Client(host='localhost', port=6379, decode_responses=True)
# Set the key `obj` to some object
obj = {
'answer': 42,
'arr': [None, True, 3.14],
'truth': {
'coord': 'out there'
}
}
rj.jsonset('obj', Path.rootPath(), obj)
# Get something
print 'Is there anybody... {}?'.format(
rj.jsonget('obj', Path('.truth.coord'))
)
# Delete something (or perhaps nothing), append something and pop it
rj.jsondel('obj', Path('.arr[0]'))
rj.jsonarrappend('obj', Path('.arr'), 'something')
print '{} popped!'.format(rj.jsonarrpop('obj', Path('.arr')))
# Update something else
rj.jsonset('obj', Path('.answer'), 2.17)
# And use just like the regular redis-py client
jp = rj.pipeline()
jp.set('foo', 'bar')
jp.jsonset('baz', Path.rootPath(), 'qaz')
jp.execute()
# If you use non-ascii character in your JSON data, you can add the no_escape flag to JSON.GET command
obj_non_ascii = {
'non_ascii_string': 'hyvää'
}
rj.jsonset('non-ascii', Path.rootPath(), obj_non_ascii)
print '{} is a non-ascii string'.format(rj.jsonget('non-ascii', Path('.non_ascii_string'), no_escape=True))Encoding/Decoding
rejson-py uses Python's json. The client can be set to use custom encoders/decoders at creation, or by calling explicitly the setEncoder() and setDecoder() methods, respectively.
The following shows how to use this for a custom class that's stored as a JSON string for example:
from json import JSONEncoder, JSONDecoder
from rejson import Client
class CustomClass(object):
"Some non-JSON-serializable"
def __init__(self, s=None):
if s is not None:
# deserialize the instance from the serialization
if s.startswith('CustomClass:'):
...
else:
raise Exception('unknown format')
else:
# initialize the instance
...
def __str__(self):
_str = 'CustomClass:'
# append the instance's state to the serialization
...
return _str
...
class CustomEncoder(JSONEncoder):
"A custom encoder for the custom class"
def default(self, obj):
if isinstance(obj, CustomClass):
return str(obj)
return json.JSONEncoder.encode(self, obj)
class TestDecoder(JSONDecoder):
"A custom decoder for the custom class"
def decode(self, obj):
d = json.JSONDecoder.decode(self, obj)
if isinstance(d, basestring) and d.startswith('CustomClass:'):
return CustomClass(d)
return d
# Create a new instance of CustomClass
obj = CustomClass()
# Create a new client with the custom encoder and decoder
rj = Client(encoder=CustomEncoder(), decoder=CustomDecoder())
# Store the object
rj.jsonset('custom', Path.rootPath(), obj))
# Retrieve it
obj = rj.jsonget('custom', Path.rootPath())API
As rejson-py exposes the same methods as redis-py, it can be used as a drop-in replacement. On top of Redis' core commands, the client also adds ReJSON's vocabulary and a couple of helper methods. These are documented in the API.md file, which can be generated by running:
$ python gendoc rejson > API.mdFor complete documentation about ReJSON's commands, refer to ReJSON's website.