UltraJSON

UltraJSON is an ultra fast JSON encoder and decoder written in pure C with bindings for Python 2.5+ and 3.

For a more painless day to day C/C++ JSON decoder experience please checkout ultrajson4c, based on UltraJSON.

Please checkout the rest of the projects in the Ultra series:

http://github.com/esnme/ultramemcache

http://github.com/esnme/ultramysql

To install it just run Pip as usual:

$ pip install ultrajson

Usage

May be used as a drop in replacement for most other JSON parsers for Python:

>>> import ultrajson
>>> ultrajson.dumps([{"key": "value"}, 81, True])
'[{"key":"value"},81,true]'
>>> ultrajson.loads("""[{"key": "value"}, 81, true]""")
[{u'key': u'value'}, 81, True]

Encoder options

encode_html_chars

Used to enable special encoding of "unsafe" HTML characters into safer Unicode sequences. Default is false:

>>> ultrajson.dumps("<script>John&Doe", encode_html_chars=True)
'"\\u003cscript\\u003eJohn\\u0026Doe"'

ensure_ascii

Limits output to ASCII and escapes all extended characters above 127. Default is true. If your end format supports UTF-8 setting this option to false is highly recommended to save space:

>>> ultrajson.dumps(u"\xe5\xe4\xf6")
'"\\u00e5\\u00e4\\u00f6"'
>>> ultrajson.dumps(u"\xe5\xe4\xf6", ensure_ascii=False)
'"\xc3\xa5\xc3\xa4\xc3\xb6"'

double_precision

Controls how many decimals to encode for double or decimal values. Default is 9:

>>> ultrajson.dumps(math.pi)
'3.1415926536'
>>> ultrajson.dumps(math.pi, double_precision=1)
'3.1'
>>> ultrajson.dumps(math.pi, double_precision=0)
'3'
>>> ultrajson.dumps(math.pi, double_precision=4)
'3.1416'

escape_forward_slashes

Controls whether forward slashes (/) are escaped. Default is True:

>>> ultrajson.dumps("http://esn.me")
'"http:\/\/esn.me"'
>>> ultrajson.dumps("http://esn.me", escape_forward_slashes=False)
'"http://esn.me"'

indent

Controls whether indention ("pretty output") is enabled. Default is 0 (disabled):

>>> ultrajson.dumps({"foo": "bar"})
'{"foo":"bar"}'
>>> ultrajson.dumps({"foo": "bar"}, indent=4)
{
    "foo":"bar"
}

Decoders options

precise_float

Set to enable usage of higher precision (strtod) function when decoding string to double values. Default is to use fast but less precise builtin functionality:

>>> ultrajson.loads("4.56")
4.5600000000000005
>>> ultrajson.loads("4.56", precise_float=True)
4.5599999999999996

Benchmarks

UltraJSON calls/sec compared to three other popular JSON parsers with performance gain specified below each.

Test machine:

Linux version 2.6.32-131.0.15.el6.x86_64

Versions:

• ultrajson: 1.21
• simplejson: 2.6.2
• cjson: 1.05
• yajl: 0.3.5
• Python: Python 2.6.6 (r266:84292, Jul 20 2011, 10:22:43)