ultrajson/README.rst

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"'

~~~~~~~~~~~~~~~~
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 |
+-----------------------------------------+--------+------------+--------+---------+