python-rapidjson

Python wrapper around RapidJSON

Authors:	Ken Robbins <ken@kenrobbins.com> Lele Gaifax <lele@metapensiero.it>
License:	MIT License
Status:

RapidJSON is an extremely fast C++ JSON parser and serialization library: this module wraps it into a Python 3 extension, exposing its serialization/deserialization (to/from either bytes, str or file-like instances) and JSON Schema validation capabilities.

Latest version documentation is automatically rendered by Read the Docs.

Getting Started

First install python-rapidjson:

$ pip install python-rapidjson

or, if you prefer Conda:

$ conda install -c conda-forge python-rapidjson

Basic usage looks like this:

>>> import rapidjson
>>> data = {'foo': 100, 'bar': 'baz'}
>>> rapidjson.dumps(data)
'{"bar":"baz","foo":100}'
>>> rapidjson.loads('{"bar":"baz","foo":100}')
{'bar': 'baz', 'foo': 100}
>>>
>>> class Stream:
...   def write(self, data):
...      print("Chunk:", data)
...
>>> rapidjson.dump(data, Stream(), chunk_size=5)
Chunk: b'{"foo'
Chunk: b'":100'
Chunk: b',"bar'
Chunk: b'":"ba'
Chunk: b'z"}'

Development

If you want to install the development version (maybe to contribute fixes or enhancements) you may clone the repository:

$ git clone --recursive https://github.com/python-rapidjson/python-rapidjson.git

$ python3 setup.py build --rj-include-dir=/usr/include/rapidjson

A set of makefiles implement most common operations, such as build, check and release; see make help output for a list of available targets.

Performance

python-rapidjson tries to be as performant as possible while staying compatible with the json module.

See the this section in the documentation for a comparison with other JSON libraries.

Incompatibility

Here are things in the standard json library supports that we have decided not to support:

separators argument

This is mostly used for pretty printing and not supported by RapidJSON so it isn't a high priority. We do support indent kwarg that would get you nice looking JSON anyways.

Coercing keys when dumping

json will stringify a True dictionary key as "true" if you dump it out but when you load it back in it'll still be a string. We want the dump and load to return the exact same objects so we have decided not to do this coercion.

Arbitrary encodings

json.loads() accepts an encoding kwarg determining the encoding of its input, when that is a bytes or bytearray instance. Although RapidJSON is able to cope with several different encodings, we currently support only the recommended one, UTF-8.