Metadata-Version: 2.0
Name: python-rapidjson
Version: 0.1.0b4
Summary: Python wrapper around rapidjson
Home-page: https://github.com/python-rapidjson/python-rapidjson
Author: Ken Robbins
Author-email: ken@kenrobbins.com
License: MIT License
Keywords: json rapidjson
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python
Requires-Python: >=3.4

==================
 python-rapidjson
==================

Python wrapper around RapidJSON
===============================

RapidJSON_ is an extremely fast C++ JSON serialization library.

We do not support legacy Python versions, you will need to upgrade to Python 3
to use this library.

Latest version documentation is automatically rendered by `Read the Docs`__.

__ http://python-rapidjson.readthedocs.io/en/latest/

.. image:: https://travis-ci.org/python-rapidjson/python-rapidjson.svg?branch=master
   :target: https://travis-ci.org/python-rapidjson/python-rapidjson
   :alt: Build status

.. image:: https://readthedocs.org/projects/python-rapidjson/badge/?version=latest
   :target: http://python-rapidjson.readthedocs.io/en/latest/?badge=latest
   :alt: Documentation status


Getting Started
---------------

First install ``python-rapidjson``:

.. code-block:: bash

    $ pip install python-rapidjson

RapidJSON tries to be compatible with the standard library ``json`` module so
it should be a drop in replacement. Basic usage looks like this:

.. code-block:: python

    >>> import rapidjson
    >>> data = {'foo': 100, 'bar': 'baz'}
    >>> rapidjson.dumps(data)
    '{"bar":"baz","foo":100}'
    >>> rapidjson.loads('{"bar":"baz","foo":100}')
    {'bar': 'baz', 'foo': 100}

If you want to install the development version (maybe to contribute fixes or
enhancements) you may clone the repository:

.. code-block:: bash

    $ git clone --recursive https://github.com/python-rapidjson/python-rapidjson.git

.. note:: The ``--recursive`` option is needed because we use a *submodule* to
          include RapidJSON_ sources. Alternatively you can do a plain
          ``clone`` immediately followed by a ``git submodule update --init``.

          Alternatively, if you already have (a *compatible* version of)
          RapidJSON includes around, you can compile the module specifying
          their location with the option ``--rj-include-dir``, for example:

          .. code-block:: shell

             $ python3 setup.py build --rj-include-dir=/usr/include/rapidjson


Performance
-----------

``python-rapidjson`` tries to be as performant as possible while staying
compatible with the ``json`` module.

The following tables show a comparison between this module and other libraries
with different data sets.  Last row (“overall”) is the total time taken by all
the benchmarks.

Each number show the factor between the time taken by each contender and
``python-rapidjson`` (in other words, they are *normalized* against a value of
1.0 for ``python-rapidjson``): the lower the number, the speedier the
contender.

In **bold** the winner.

Serialization
~~~~~~~~~~~~~

+-----------------------+-----------------+-----------------+-----------------+-----------------+-----------------+
|       serialize       |   native [1]_   |   ujson [2]_    | simplejson [3]_ |   stdlib [4]_   |    yajl [5]_    |
+=======================+=================+=================+=================+=================+=================+
|    100 arrays dict    |    **0.67**     |      1.31       |      6.28       |      2.88       |      1.74       |
+-----------------------+-----------------+-----------------+-----------------+-----------------+-----------------+
|    100 dicts array    |    **0.79**     |      1.19       |      7.16       |      2.92       |      1.69       |
+-----------------------+-----------------+-----------------+-----------------+-----------------+-----------------+
|  **256 Trues array**  |      1.19       |      1.41       |      3.02       |      2.19       |      1.20       |
+-----------------------+-----------------+-----------------+-----------------+-----------------+-----------------+
|    256 ascii array    |      1.02       |    **0.92**     |      1.90       |      1.77       |      2.05       |
+-----------------------+-----------------+-----------------+-----------------+-----------------+-----------------+
| **256 doubles array** |      1.06       |      7.55       |      8.30       |      7.65       |      4.39       |
+-----------------------+-----------------+-----------------+-----------------+-----------------+-----------------+
|   256 unicode array   |      0.87       |      0.72       |      0.82       |      0.88       |    **0.53**     |
+-----------------------+-----------------+-----------------+-----------------+-----------------+-----------------+
|    complex object     |    **0.82**     |      1.41       |      5.17       |      3.39       |      2.87       |
+-----------------------+-----------------+-----------------+-----------------+-----------------+-----------------+
|   composite object    |    **0.68**     |      0.93       |      3.01       |      1.92       |      1.85       |
+-----------------------+-----------------+-----------------+-----------------+-----------------+-----------------+
|        overall        |    **0.67**     |      1.30       |      6.27       |      2.88       |      1.74       |
+-----------------------+-----------------+-----------------+-----------------+-----------------+-----------------+

.. [1] rapidjson with ``number_mode=NM_NATIVE``
.. [2] `ujson 1.35 <https://pypi.python.org/pypi/ujson/1.35>`__
.. [3] `simplejson 3.11.1 <https://pypi.python.org/pypi/simplejson/3.11.1>`__
.. [4] Python 3.6 standard library
.. [5] `yajl 0.3.5 <https://pypi.python.org/pypi/yajl/0.3.5>`__


Deserialization
~~~~~~~~~~~~~~~

+-----------------------+------------+------------+------------+------------+------------+
|      deserialize      |   native   |   ujson    | simplejson |   stdlib   |    yajl    |
+=======================+============+============+============+============+============+
|    100 arrays dict    |  **0.90**  |    0.97    |    1.48    |    1.25    |    1.20    |
+-----------------------+------------+------------+------------+------------+------------+
|    100 dicts array    |  **0.88**  |    0.96    |    1.99    |    1.58    |    1.34    |
+-----------------------+------------+------------+------------+------------+------------+
|  **256 Trues array**  |    1.22    |    1.31    |    2.08    |    1.93    |    2.08    |
+-----------------------+------------+------------+------------+------------+------------+
|  **256 ascii array**  |    1.05    |    1.37    |    1.14    |    1.25    |    1.56    |
+-----------------------+------------+------------+------------+------------+------------+
|   256 doubles array   |  **0.16**  |    0.33    |    0.72    |    0.70    |    0.47    |
+-----------------------+------------+------------+------------+------------+------------+
|   256 unicode array   |    0.89    |  **0.79**  |    4.12    |    4.50    |    1.90    |
+-----------------------+------------+------------+------------+------------+------------+
|    complex object     |  **0.72**  |    0.88    |    1.36    |    1.28    |    1.24    |
+-----------------------+------------+------------+------------+------------+------------+
|   composite object    |  **0.83**  |    0.85    |    1.94    |    1.43    |    1.26    |
+-----------------------+------------+------------+------------+------------+------------+
|        overall        |  **0.90**  |    0.97    |    1.49    |    1.25    |    1.20    |
+-----------------------+------------+------------+------------+------------+------------+


DIY
~~~

To run these tests yourself, clone the repo and run:

.. code-block:: bash

   $ tox -e py36 -- -m benchmark --compare-other-engines

Without the option ``--compare-other-engines`` it will focus only on
``RapidJSON``.  This is particularly handy coupled with the `compare past
runs`__ functionality of ``pytest-benchmark``:

.. code-block:: bash

   $ tox -e py36 -- -m benchmark --benchmark-autosave
   # hack, hack, hack!
   $ tox -e py36 -- -m benchmark --benchmark-compare=0001

   ----------------------- benchmark 'deserialize': 18 tests ------------------------
   Name (time in us)                                                            Min…
   ----------------------------------------------------------------------------------
   test_loads[rapidjson-256 Trues array] (NOW)                         5.2320 (1.0)…
   test_loads[rapidjson-256 Trues array] (0001)                        5.4180 (1.04)…
   …

To reproduce the tables above, use the option ``--benchmark-json`` so that the
the results are written in the specified filename the run the
``benchmark-tables.py`` script giving that filename as the only argument:

.. code-block:: bash

   $ tox -e py36 -- -m benchmark --compare-other-engines --benchmark-json=comparison.json
   $ python3 benchmark-tables.py comparison.json


__ http://pytest-benchmark.readthedocs.org/en/latest/comparing.html


Incompatibility
---------------

Here are things in the standard ``json`` library supports that we have decided
not to support:

* ``separators`` argument. This is mostly used for pretty printing and not
  supported by ``RapidJSON`` so it isn't a high priority. We do support
  ``indent`` kwarg that would get you nice looking JSON anyways.

* Coercing keys when dumping. ``json`` will turn ``True`` into ``'True'`` if
  you dump it out but when you load it back in it'll still be a string. We
  want the dump and load to return the exact same objects so we have decided
  not to do this coercing.

.. _RapidJSON: https://github.com/miloyip/rapidjson


Changes
-------

0.1.0b4 (2017-08-14)
~~~~~~~~~~~~~~~~~~~~

* Make execution of the test suite on Appveyor actually happen


0.1.0b3 (2017-08-12)
~~~~~~~~~~~~~~~~~~~~

* Exclude CI configurations from the source distribution


0.1.0b2 (2017-08-12)
~~~~~~~~~~~~~~~~~~~~

* Fix Powershell wheel upload script in appveyor configuration


0.1.0b1 (2017-08-12)
~~~~~~~~~~~~~~~~~~~~

* Compilable with somewhat old g++ (`issue #69`__)

  __ https://github.com/python-rapidjson/python-rapidjson/issues/69

* **Backward incompatibilities**:

  - all ``DATETIME_MODE_XXX`` constants have been shortened to ``DM_XXX``
    ``DATETIME_MODE_ISO8601_UTC`` has been renamed to ``DM_SHIFT_TO_UTC``

  - all ``UUID_MODE_XXX`` constants have been shortened to ``UM_XXX``

* New option ``DM_UNIX_TIME`` to serialize date, datetime and time values as
  `UNIX timestamps`__ targeting `issue #61`__

  __ https://en.wikipedia.org/wiki/Unix_time
  __ https://github.com/python-rapidjson/python-rapidjson/issues/61

* New option ``DM_NAIVE_IS_UTC`` to treat naïve datetime and time values as if
  they were in the UTC timezone (also for issue #61)

* New keyword argument ``number_mode`` to use underlying C library numbers

* Binary wheels for GNU/Linux and Windows on PyPI (one would hope: this is the
  reason for the beta1 release)


0.0.11 (2017-03-05)
~~~~~~~~~~~~~~~~~~~

* Fix a couple of refcount handling glitches, hopefully targeting `issue
  #48`__.

  __ https://github.com/python-rapidjson/python-rapidjson/issues/48


0.0.10 (2017-03-02)
~~~~~~~~~~~~~~~~~~~

* Fix source distribution to contain all required stuff (`PR #64`__)

  __ https://github.com/python-rapidjson/python-rapidjson/pull/64


0.0.9 (2017-03-02)
~~~~~~~~~~~~~~~~~~

* CI testing on GitHub

* Allow using locally installed RapidJSON library (`issue #60`__)

  __ https://github.com/python-rapidjson/python-rapidjson/issues/60

* Bug fixes (`issue #37`__, `issue #51`__, `issue #57`__)

  __ https://github.com/python-rapidjson/python-rapidjson/issues/37
  __ https://github.com/python-rapidjson/python-rapidjson/issues/51
  __ https://github.com/python-rapidjson/python-rapidjson/issues/57


0.0.8 (2016-12-09)
~~~~~~~~~~~~~~~~~~

* Use unpatched RapidJSON 1.1 (`PR #46`__)

  __ https://github.com/python-rapidjson/python-rapidjson/pull/46

* Handle serialization and deserialization of datetime, date and time
  instances (`PR #35`__) and of UUID instances (`PR #40`__)

  __ https://github.com/python-rapidjson/python-rapidjson/pull/35
  __ https://github.com/python-rapidjson/python-rapidjson/pull/40

* Sphinx based documentation (`PR #44`__)

  __ https://github.com/python-rapidjson/python-rapidjson/pull/44

* Refresh benchmarks (`PR #45`__)

  __ https://github.com/python-rapidjson/python-rapidjson/pull/45

* Bug fixes (`issue #25`__, `issue #38`__, `PR #43`__)

  __ https://github.com/python-rapidjson/python-rapidjson/issues/25
  __ https://github.com/python-rapidjson/python-rapidjson/issues/38
  __ https://github.com/python-rapidjson/python-rapidjson/pull/43


