python-rapidjson 1.23

Python wrapper around rapidjson

Authors:

Ken Robbins <[e-mail]>

Lele Gaifax <[e-mail]>

License:

MIT License

Status:

RapidJSON is an extremely fast C++ JSON parser and serialization library: this module wraps it into a Python 3 extension, exposing its serialization/deserialization (to/from either bytes, str or file-like instances) and JSON Schema validation capabilities.

Latest version documentation is automatically rendered by Read the Docs.

Getting Started

First install python-rapidjson:

$ pip install python-rapidjson

or, if you prefer Conda:

$ conda install -c conda-forge python-rapidjson

Basic usage looks like this:

>>> import rapidjson
>>> data = {'foo': 100, 'bar': 'baz'}
>>> rapidjson.dumps(data)
'{"foo":100,"bar":"baz"}'
>>> rapidjson.loads('{"bar":"baz","foo":100}')
{'bar': 'baz', 'foo': 100}
>>>
>>> class Stream:
...   def write(self, data):
...      print("Chunk:", data)
...
>>> rapidjson.dump(data, Stream(), chunk_size=5)
Chunk: b'{"foo'
Chunk: b'":100'
Chunk: b',"bar'
Chunk: b'":"ba'
Chunk: b'z"}'

Most functionalities are exposed both as functions and as classes.

The following uses a relaxed syntax Decoder instance, that handles JSONC and trailing commas:

>>> from rapidjson import Decoder
>>> from rapidjson import PM_COMMENTS, PM_TRAILING_COMMAS
>>> decoder = Decoder(parse_mode=PM_COMMENTS | PM_TRAILING_COMMAS)
>>> decoder('''
... {
...     "bar": /* Block comment */ "baz",
...     "foo":100, // Trailing comma and comment
... }
... ''')
{'bar': 'baz', 'foo': 100}

Development

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

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

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

A set of makefiles implement most common operations, such as build, check and release; see make help output for a list of available targets.

Performance

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

See this section in the documentation for a comparison with other JSON libraries.

Incompatibility

Although we tried to implement an API similar to the standard library json, being a strict drop-in replacement in not our goal and we have decided to depart from there in some aspects. See this section in the documentation for further details.

Changes

1.23 (2025-12-07)

• Fix serialization bug when using MM_COERCE_KEYS_TO_STRINGS together with sort_keys=True (issue #229)

1.22 (2025-10-21)

• Generate wheels on PyPI using Python 3.14 final release, thanks to cibuildwheel 3.2.1

1.21 (2025-07-10)

• Use current master version of rapidjson, thanks to Kyle Gottfried (although I didn’t merge his PR #224)

• Recompute comparison table with latest versions of other libraries, using Python 3.13

• Typing stubs: specify default value for stream argument of Encoder.__call__() (issue #215)

• Use more recent OS images on GH Actions to test and build wheels

1.20 (2024-08-05)

• Rectify type hints of loads() and Decoder.__call__() (issue #214)

• Ensure Validator receives valid UTF-8 bytes/bytearray arguments

• Generate wheels on PyPI using Python 3.13.0rc1 release, thanks to cibuildwheel 2.20.0

1.19 (2024-07-28)

• Properly dump subclasses of float with custom __repr__() method ( issue #213)

1.18 (2024-06-29)

• Expose PEP-484 typing stubs, thanks to Rodion Kosianenko and GoodWasHere (PR #204)

1.17 (2024-05-18)

• Use current master version of rapidjson

• Generate wheels on PyPI using Python 3.13b1 release, thanks to cibuildwheel 2.18.0

1.16 (2024-02-28)

• Produce Python 3.8 wheels again, I deactivated it too eagerly, it’s in security fixes only mode, not yet reached its end-of-life state

1.15 (2024-02-28)

• Honor the recursion limit also at parse time, to avoid attacks as described by CVE-2024-27454

1.14 (2023-12-14)

• Produce binary wheels for macOS/arm64, thanks to timothyjlaurent (PR #195)

1.13 (2023-10-29)

• Fix handling of write_mode in dump functions (problem emerged discussing issue #191)

1.12 (2023-10-07)

• Generate wheels on PyPI using final Python 3.12 release, thanks to cibuildwheel 2.16.2

1.11 (2023-09-11)

• Use current master version of rapidjson

• Use cibuildwheel 2.15.0

1.10 (2023-03-15)

• Use current master version of rapidjson

• Produce ppc64le wheels, thanks to mgiessing (PR #170)

• Use cibuildwheel 2.12.1

1.9 (2022-10-17)

• Produce Python 3.11 wheels, thanks to cibuildwheel 2.11.1

1.8 (2022-07-07)

• Fix problem on macOS explicitly requiring C++11, thanks to agate-pris (issue #166)

1.7 (2022-07-06)

• Use current master version of rapidjson

• Update the test suite to work on Pyston, thanks to Kevin Modzelewski (PR #161)

1.6 (2022-02-19)

• Fix memory leak when using end_array (issue #160)

1.5 (2021-10-16)

• Fix serialization bug when using DM_UNIX_TIME in a non-C locale context

1.4 (2021-06-25)

• Build binary wheel for aarch64, thanks to odidev (PR #156)

1.3 (2021-06-25)

• Yet another attempt to fix automatic wheels upload

1.2 (2021-06-25)

• Fix automatic wheels upload from GH Actions to PyPI

1.1 (2021-06-25)

• Reduce decoder memory consumption by uniquifiying keys in the loaded dictionaries

• Implement an alternative way of transmogrify JSON objects, similar to json‘s object_pairs_hook load option (issue #154)

1.0 (2020-12-13)

• Require Python 3.6 or greater

• New serialization options, iterable_mode and mapping_mode, to give some control on how generic iterables and mappings get encoded (fix issue #149 and issue #150)

• Internal refactorings, folding “skipkeys” and “sort_keys” arguments into the mapping_mode options, respectively as MM_SKIP_NON_STRING_KEYS and MM_SORT_KEYS: “old” arguments kept for backward compatibility

• Bump major version to 1, tag as “production/stable” and switch to a simpler X.Y versioning schema

0.9.4 (2020-11-16)

• Fix memory leak loading an invalid JSON (issue #148)

0.9.3 (2020-10-24)

• Fix access to Encoder instance attributes (issue #147)

0.9.2 (2020-10-24)

• Use current master version of rapidjson

• Enable GH Actions-based test workflow, thanks to Martin Thoma (PR #143)

• Produce Python 3.9 wheels, disable testing under Python < 3.6

• Make the character used for indentation in pretty mode a parameter (issue #135)

• Handle wider precision range in timestamps fractional seconds (PR 133), thanks to Karl Seguin

• Add comparison benchmarks against orjson and hyperjson (issue #130 and PR #131, thanks to Sebastian Pipping)

0.9.1 (2019-11-13)

• Fix memory leak in case of failed validation (issue #126)

0.9.0 (2019-11-13)

• Produce Python 3.8 wheels

• Compatibility fix for Python 3.8 (issue #125)

• New dump option write_mode, supporting RapidJSON’s kFormatSingleLineArray option (issue #123), thanks to Nguyễn Hồng Quân for the initial implementation (PR #124)

0.8.0 (2019-08-09)

• New serialization option bytes_mode to control how bytes instances get encoded (issue #122)

0.7.2 (2019-06-09)

• Hopefully fix the memory leak when loading from a stream (issue #117)

0.7.1 (2019-05-11)

• Raise a more specific exception on loading errors, JSONDecodeError, instead of generic ValueError (issue #118)

• Fix optimization path when using OrderedDicts (issue #119)

• Fix serialization of IntEnums (issue #121)

• I spent quite a lot of time investigating on the memory leak when loading from a stream (issue #117): as I was not able to fully replicate the problem, I cannot be sure I solved the problem… sorry!

0.7.0 (2019-02-11)

• Raise correct exception in code samples (PR #109), thanks to Thomas Dähling

• Fix compilation with system-wide install of rapidjson (issue #110)

• Use current master version of rapidjson, that includes a fix for its issue #1368 and issue #1336, and cures several compilation warnings as well (issue #112 and issue #107)

• Fix memory leak when using object_hook (issue #115)

0.6.3 (2018-07-11)

• No visible changes, but now PyPI carries binary wheels for Python 3.7.

0.6.2 (2018-06-08)

• Use a more specific ValidationError, to differentiate from invalid JSON

0.6.1 (2018-06-06)

• Nothing new, attempt to build Python 3.6 binary wheels on Travis CI

0.6.0 (2018-06-06)

• Add a new comparison table involving ensure_ascii (issue #98)

• Use Python’s repr() to emit float values instead of rapidjson’s dtoa() (issue #101)

• Use a newer (although unreleased) version of rapidjson to fix an issue with JSONSchema validation (PR #103), thanks to Anthony Miyaguchi

0.5.2 (2018-03-31)

• Tiny tweak to restore macOS build on Travis CI

0.5.1 (2018-03-31)

• Minor tweaks to CI and PyPI deploy configuration

0.5.0 (2018-03-31)

• New RawJSON class, allowing inclusion of pre-serialized content (PR #95 and PR #96), thanks to Silvio Tomatis

0.4.3 (2018-01-14)

• Deserialize from bytes and bytearray instances, ensuring they contain valid UTF-8 data

• Speed up parsing of floating point numbers, avoiding intermediary conversion to a Python string (PR #94)

0.4.2 (2018-01-09)

• Fix precision handling of DM_UNIX_TIME timestamps

0.4.1 (2018-01-08)

• Fix memory leaks in Decoder() and Encoder() classes, related to bad handling of PyObject_GetAttr() result value

• Fix compatibility with Python 3.7a

0.4.0 (2018-01-05)

• Implemented the streaming interface, see load() and dump() (issue #80)

  Backward incompatibility: now the flags arguments on all the functions are keyword only, to mimic stdlib’s json style

0.3.2 (2017-12-21)

• Reduce compiler warnings (issue #87)

0.3.1 (2017-12-20)

• Fix Travis CI recipe to accomodate MacOS

0.3.0 (2017-12-20)

• Fix compilation on MacOS (issue #78)

• Handle generic iterables (PR #89)

  Backward incompatibility: the dumps() function and the Encoder() constructor used to accept a max_recursion_depth argument, to control the maximum allowed nesting of Python structures; since the underlying function is now effectively recursive, it has been replaced by the generic sys.setrecursionlimit() mechanism

0.2.7 (2017-12-08)

• Restore compatibility with Python < 3.6

0.2.6 (2017-12-08)

• Fix memory leaks when using object_hook/start_object/end_object

0.2.5 (2017-09-30)

• Fix bug where error handling code could raise an exception causing a confusing exception to be returned (PR #82)

• Fix bug where loads’s object_hook and dumps’s default arguments could not be passed None explicitly (PR #83)

• Fix crash when dealing with surrogate pairs (issue #81)

0.2.4 (2017-09-17)

• Fix compatibility with MacOS/clang

0.2.3 (2017-08-24)

• Limit the precision of DM_UNIX_TIME timestamps to six decimal digits

0.2.2 (2017-08-24)

• Nothing new, attempt to fix production of Python 3.6 binary wheels

0.2.1 (2017-08-24)

• Nothing new, attempt to fix production of Python 3.6 binary wheels

0.2.0 (2017-08-24)

• New parse_mode option, implementing relaxed JSON syntax (issue #73)

• New Encoder and Decoder, implementing a class-based interface

• New Validator, exposing the underlying JSON schema validation (issue #71)

0.1.0 (2017-08-16)

• Remove beta status

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)

• 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

• 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.

0.0.10 (2017-03-02)

• Fix source distribution to contain all required stuff (PR #64)

0.0.9 (2017-03-02)

• CI testing on GitHub

• Allow using locally installed RapidJSON library (issue #60)

• Bug fixes (issue #37, issue #51, issue #57)

0.0.8 (2016-12-09)

• Use unpatched RapidJSON 1.1 (PR #46)

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

• Sphinx based documentation (PR #44)

• Refresh benchmarks (PR #45)

• Bug fixes (issue #25, issue #38, PR #43)