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 ujson4c_, based on UltraJSON.
.. _ujson4c: http://github.com/esnme/ujson4c/
| 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 ujson
============
Usage
============
May be used as a drop in replacement for most other JSON parsers for Python::
>>> import ujson
>>> ujson.dumps([{"key": "value"}, 81, True])
'[{"key":"value"},81,true]'
>>> ujson.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::
>>> ujson.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::
>>> ujson.dumps(u"\xe5\xe4\xf6")
'"\\u00e5\\u00e4\\u00f6"'
>>> ujson.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::
>>> ujson.dumps(math.pi)
'3.1415926536'
>>> ujson.dumps(math.pi, double_precision=1)
'3.1'
>>> ujson.dumps(math.pi, double_precision=0)
'3'
>>> ujson.dumps(math.pi, double_precision=4)
'3.1416'
~~~~~~~~~~~~~~~~
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::
>>> ujson.loads("4.56")
4.5600000000000005
>>> ujson.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:
~~~~~~~~~
- ujson: 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)
+-----------------------------------------+--------+------------+--------+---------+
| | ujson | simplejson | cjson | yajl |
+=========================================+========+============+========+=========+
| Array with 256 utf-8 strings | | | | |
+-----------------------------------------+--------+------------+--------+---------+
| Encode | 4090,74| 899,39 |83,86 | 3189,86 |
+-----------------------------------------+--------+------------+--------+---------+
| | | 4,55 |48,78 | 1,28 |
+-----------------------------------------+--------+------------+--------+---------+
| Decode | 863,29 | 586,15 |201,61 | 352,48 |
+-----------------------------------------+--------+------------+--------+---------+
| | | 1,47 | 4,28 | 2,45 |
+-----------------------------------------+--------+------------+--------+---------+
| Medium complex object | | | | |
+-----------------------------------------+--------+------------+--------+---------+
| Encode | 9750,37| 1377,15 |1512,06 | 3341,91 |
+-----------------------------------------+--------+------------+--------+---------+
| | | 7,08 | 6,45 | 2,92 |
+-----------------------------------------+--------+------------+--------+---------+
| Decode | 5576,75| 4247,16 | 3587,83| 2850,13 |
+-----------------------------------------+--------+------------+--------+---------+
| | | 1,31| 1,55 | 1,96 |
+-----------------------------------------+--------+------------+--------+---------+
| Array with 256 strings | | | | |
+-----------------------------------------+--------+------------+--------+---------+
| Encode |17998,01| 12954,46 |8715,02 | 15924,35|
+-----------------------------------------+--------+------------+--------+---------+
| | | 1,39| 2,07| 1,13 |
+-----------------------------------------+--------+------------+--------+---------+
| Decode |14540,71| 19696,13 |14908,46| 9547,14 |
+-----------------------------------------+--------+------------+--------+---------+
| | | 0,74 | 0,98 | 1,52 |
+-----------------------------------------+--------+------------+--------+---------+
| Array with 256 doubles | | | | |
+-----------------------------------------+--------+------------+--------+---------+
| Encode | 2185,20| 1466,87 | 1956,99| 3421,10 |
+-----------------------------------------+--------+------------+--------+---------+
| | | 1,49| 1,12 | 0,64 |
+-----------------------------------------+--------+------------+--------+---------+
| Decode |16062,01| 8990,50 | 9743,40|8331,74 |
+-----------------------------------------+--------+------------+--------+---------+
| | | 1,79| 1,65| 1,93 |
+-----------------------------------------+--------+------------+--------+---------+
| Array with 256 True values | | | | |
+-----------------------------------------+--------+------------+--------+---------+
| Encode |69767,60| 25202,56 |41145,99|64330,76 |
+-----------------------------------------+--------+------------+--------+---------+
| | | 2,77 | 1,70 | 1,08 |
+-----------------------------------------+--------+------------+--------+---------+
|Decode |91416,02| 56439,97 |54918,09| 42786,02|
+-----------------------------------------+--------+------------+--------+---------+
| | | 1,62| 1,66 | 2,14 |
+-----------------------------------------+--------+------------+--------+---------+
| Array with 256 dict{string, int} pairs | | | | |
+-----------------------------------------+--------+------------+--------+---------+
| | | | | |
+-----------------------------------------+--------+------------+--------+---------+
| Encode |11307,54| 1830,45 | 2720,90| 7725,56 |
+-----------------------------------------+--------+------------+--------+---------+
| | | 6,18| 4,16 | 1,46 |
+-----------------------------------------+--------+------------+--------+---------+
| Decode |8695,94 | 7572,89 | 6076,71|5231,32 |
+-----------------------------------------+--------+------------+--------+---------+
| | | 1,15| 1,43| 1,66 |
+-----------------------------------------+--------+------------+--------+---------+
| Dict with 256 arrays with 256 dict | | | | |
+-----------------------------------------+--------+------------+--------+---------+
| Encode | 37,76 | 4,88 | 10,49 | 27,62 |
+-----------------------------------------+--------+------------+--------+---------+
| | | 7,74| 3,60| 1,37 |
+-----------------------------------------+--------+------------+--------+---------+
|Decode | 17,70 | 15,56 | 11,25 | 12,00 |
+-----------------------------------------+--------+------------+--------+---------+
| | | 1,14| 1,57| 1,47 |
+-----------------------------------------+--------+------------+--------+---------+