Skip to main content

ReJSON Python Client

Project description

https://travis-ci.org/RedisLabs/rejson-py.svg?branch=master https://coveralls.io/repos/github/RedisLabs/rejson-py/badge.svg?branch=master https://img.shields.io/pypi/pyversions/rejson.svg

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

Usage example

from rejson import Client, Path

rj = Client(host='localhost', port=6379)

# 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.

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](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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
rejson-0.2.1.tar.gz (7.5 kB) Copy SHA256 hash SHA256 Source None Jun 5, 2017

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page