UltraJSON
=========

.. image:: https://img.shields.io/pypi/v/ujson.svg
    :alt: PyPI version
    :target: https://pypi.python.org/pypi/ujson

.. image:: https://img.shields.io/pypi/pyversions/ujson.svg
    :alt: Supported Python versions
    :target: https://pypi.python.org/pypi/ujson

.. image:: https://img.shields.io/pypi/dm/ujson.svg
    :alt: PyPI downloads
    :target: https://pypistats.org/packages/ujson

.. image:: https://github.com/ultrajson/ultrajson/workflows/Test/badge.svg
    :alt: GitHub Actions status
    :target: https://github.com/ultrajson/ultrajson/actions?query=workflow%3ATest

.. image:: https://travis-ci.com/ultrajson/ultrajson.svg?branch=master
    :alt: Travis CI status
    :target: https://travis-ci.com/ultrajson/ultrajson

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :alt: Code style: Black
    :target: https://github.com/psf/black

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

To install it just run pip as usual:

.. code-block:: sh

    $ pip install ujson

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

.. code-block:: 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``:

.. code-block:: python

    >>> 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:

.. code-block:: python

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

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

.. code-block:: python

    >>> 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):

.. code-block:: python

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

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

~~~~~~~~~~~~~
Test machine:
~~~~~~~~~~~~~

Linux 3.13.0-66-generic x86_64 #108-Ubuntu SMP Wed Oct 7 15:20:27 UTC 2015

~~~~~~~~~
Versions:
~~~~~~~~~

- CPython 2.7.6 (default, Jun 22 2015, 17:58:13) [GCC 4.8.2]
- blist     : 1.3.6
- simplejson: 3.8.1
- ujson     : 1.34 (0c52200eb4e2d97e548a765d5f089858c41967b0)
- yajl      : 0.3.5

+-------------------------------------------------------------------------------+------------+------------+------------+------------+
|                                                                               | ujson      | yajl       | simplejson | json       |
+===============================================================================+============+============+============+============+
| Array with 256 doubles                                                        |            |            |            |            |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| encode                                                                        |    3508.19 |    5742.00 |    3232.38 |    3309.09 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| decode                                                                        |   25103.37 |   11257.83 |   11696.26 |   11871.04 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| Array with 256 UTF-8 strings                                                  |            |            |            |            |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| encode                                                                        |    3189.71 |    2717.14 |    2006.38 |    2961.72 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| decode                                                                        |    1354.94 |     630.54 |     356.35 |     344.05 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| Array with 256 strings                                                        |            |            |            |            |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| encode                                                                        |   18127.47 |   12537.39 |   12541.23 |   20001.00 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| decode                                                                        |   23264.70 |   12788.85 |   25427.88 |    9352.36 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| Medium complex object                                                         |            |            |            |            |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| encode                                                                        |   10519.38 |    5021.29 |    3686.86 |    4643.47 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| decode                                                                        |    9676.53 |    5326.79 |    8515.77 |    3017.30 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| Array with 256 True values                                                    |            |            |            |            |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| encode                                                                        |  105998.03 |  102067.28 |   44758.51 |   60424.80 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| decode                                                                        |  163869.96 |   78341.57 |  110859.36 |  115013.90 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| Array with 256 dict{string, int} pairs                                        |            |            |            |            |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| encode                                                                        |   13471.32 |   12109.09 |    3876.40 |    8833.92 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| decode                                                                        |   16890.63 |    8946.07 |   12218.55 |    3350.72 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| Dict with 256 arrays with 256 dict{string, int} pairs                         |            |            |            |            |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| encode                                                                        |      50.25 |      46.45 |      13.82 |      29.28 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| decode                                                                        |      33.27 |      22.10 |      27.91 |      10.43 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| Dict with 256 arrays with 256 dict{string, int} pairs, outputting sorted keys |            |            |            |            |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| encode                                                                        |      27.19 |            |       7.75 |       2.39 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| Complex object                                                                |            |            |            |            |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| encode                                                                        |     577.98 |            |     387.81 |     470.02 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| decode                                                                        |     496.73 |     234.44 |     151.00 |     145.16 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+

~~~~~~~~~
Versions:
~~~~~~~~~

- CPython 3.4.3 (default, Oct 14 2015, 20:28:29) [GCC 4.8.4]
- blist     : 1.3.6
- simplejson: 3.8.1
- ujson     : 1.34 (0c52200eb4e2d97e548a765d5f089858c41967b0)
- yajl      : 0.3.5

+-------------------------------------------------------------------------------+------------+------------+------------+------------+
|                                                                               | ujson      | yajl       | simplejson | json       |
+===============================================================================+============+============+============+============+
| Array with 256 doubles                                                        |            |            |            |            |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| encode                                                                        |    3477.15 |    5732.24 |    3016.76 |    3071.99 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| decode                                                                        |   23625.20 |    9731.45 |    9501.57 |    9901.92 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| Array with 256 UTF-8 strings                                                  |            |            |            |            |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| encode                                                                        |    1995.89 |    2151.61 |    1771.98 |    1817.20 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| decode                                                                        |    1425.04 |     625.38 |     327.14 |     305.95 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| Array with 256 strings                                                        |            |            |            |            |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| encode                                                                        |   25461.75 |   12188.64 |   13054.76 |   14429.81 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| decode                                                                        |   21981.31 |   17014.22 |   23869.48 |   22483.58 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| Medium complex object                                                         |            |            |            |            |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| encode                                                                        |   10821.46 |    4837.04 |    3114.04 |    4254.46 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| decode                                                                        |    7887.77 |    5126.67 |    4934.60 |    6204.97 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| Array with 256 True values                                                    |            |            |            |            |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| encode                                                                        |  100452.86 |   94639.42 |   46657.63 |   60358.63 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| decode                                                                        |  148312.69 |   75485.90 |   88434.91 |  116395.51 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| Array with 256 dict{string, int} pairs                                        |            |            |            |            |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| encode                                                                        |   11698.13 |    8886.96 |    3043.69 |    6302.35 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| decode                                                                        |   10686.40 |    7061.77 |    5646.80 |    7702.29 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| Dict with 256 arrays with 256 dict{string, int} pairs                         |            |            |            |            |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| encode                                                                        |      44.26 |      34.43 |      10.40 |      21.97 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| decode                                                                        |      28.46 |      23.95 |      18.70 |      22.83 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| Dict with 256 arrays with 256 dict{string, int} pairs, outputting sorted keys |            |            |            |            |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| encode                                                                        |      33.60 |            |       6.94 |      22.34 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| Complex object                                                                |            |            |            |            |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| encode                                                                        |     432.30 |            |     351.47 |     379.34 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+
| decode                                                                        |     434.40 |     221.97 |     149.57 |     147.79 |
+-------------------------------------------------------------------------------+------------+------------+------------+------------+