mirror of
https://github.com/ultrajson/ultrajson.git
synced 2024-11-23 20:53:30 +01:00
192 lines
9.4 KiB
ReStructuredText
192 lines
9.4 KiB
ReStructuredText
UltraJSON
|
|
=============
|
|
.. image:: https://travis-ci.org/esnme/ultrajson.svg?branch=master
|
|
:target: https://travis-ci.org/esnme/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'
|
|
|
|
escape_forward_slashes
|
|
----------------------
|
|
Controls whether forward slashes (``/``) are escaped. Default is True::
|
|
|
|
>>> ujson.dumps("http://esn.me")
|
|
'"http:\/\/esn.me"'
|
|
>>> ujson.dumps("http://esn.me", escape_forward_slashes=False)
|
|
'"http://esn.me"'
|
|
|
|
indent
|
|
----------------------
|
|
Controls whether indention ("pretty output") is enabled. Default is 0 (disabled)::
|
|
|
|
>>> ujson.dumps({"foo": "bar"})
|
|
'{"foo":"bar"}'
|
|
>>> ujson.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::
|
|
|
|
>>> 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 |
|
|
+-----------------------------------------+--------+------------+--------+---------+
|