ReJSON Python Client
Project description
RedisJSON Python Client
.. image:: https://img.shields.io/github/license/RedisJSON/RedisJSON-py.svg :target: https://github.com/RedisJSON/RedisJSON-py-go
.. image:: https://travis-ci.org/RedisLabs/rejson-py.svg?branch=master :target: https://travis-ci.org/RedisLabs/rejson-py
.. image:: https://badge.fury.io/py/rejson.svg :target: https://badge.fury.io/py/rejson
.. image:: https://img.shields.io/pypi/pyversions/rejson.svg :target: https://github.com/RedisJSON/redisjson-py
.. image:: https://img.shields.io/github/release/RedisJSON/redisjson-py.svg :target: https://github.com/RedisJSON/redisjson-py/releases/latest
.. image:: https://coveralls.io/repos/github/RedisLabs/rejson-py/badge.svg?branch=master :target: https://coveralls.io/github/RedisLabs/rejson-py?branch=master
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.
.. _Redis
: https://redis.io
.. _ReJSON module
: https://github.com/redislabsmodules/rejson
.. _redis-py
: https://github.com/andymccurdy/redis-py
Installation
.. code-block:: bash
$ pip install rejson
Usage example
.. code-block:: python
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()
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.
.. _json: https://docs.python.org/2/library/json.html .. _setDecoder: ./API.md#setdecoder .. _setEncoder: ./API.md#setencoder
The following shows how to use this for a custom class that's stored as a JSON string for example:
.. code-block:: python
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:
.. code-block:: bash
$ python gendoc rejson > API.md
For complete documentation about ReJSON's commands, refer to ReJSON's website
_.
.. _ReJSON's website
: http://rejson.io
License
BSD 2-Clause
_
.. _BSD 2-Clause
: https://github.com/RedisLabs/rejson-py/blob/master/LICENSE
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.