RedisJSON / redisjson-py

An extension to redis-py for using Redis' ReJSON module
https://redisjson.io
BSD 2-Clause "Simplified" License
160 stars 34 forks source link
json python redis rejson

license pypi PyVersions GitHub issues Codecov Known Vulnerabilities

RedisJSON Python Client

Forum Discord

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 rejson

Development

  1. Create a virtualenv to manage your python dependencies, and ensure it's active. virtualenv -v venv
  2. Install pypoetry to manage your dependencies. pip install --user poetry
  3. 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.md

For complete documentation about ReJSON's commands, refer to ReJSON's website.

License

BSD 2-Clause