Python RapidJSON

1.23 · active · verified Thu Apr 09

Python-rapidjson is a Python 3 wrapper for the extremely fast C++ JSON parser and serialization library, RapidJSON. It provides high-performance JSON serialization and deserialization, including JSON Schema validation capabilities, while aiming for compatibility with the standard `json` module API. As of version 1.23, it maintains an active release cadence, frequently updating to support new Python versions and upstream RapidJSON improvements.

Warnings

gotcha API Incompatibilities with standard `json` module: While `python-rapidjson` aims for `json` module compatibility, there are notable differences. `json.loads()` for bytes input only supports UTF-8. Dictionary key coercion (e.g., `True` to 'true') is not performed by default. The `indent` argument for pretty printing is supported, but specific `json` module behaviors like `None` for no indent or `sort_keys` as a direct argument have been superseded by `mapping_mode` options in v1.0+ (though old arguments are kept for backward compatibility).
Fix: Consult the `python-rapidjson` documentation for `Incompatibilities` and `Exposed functions and symbols` sections. Use specific `datetime_mode`, `number_mode`, `parse_mode`, `write_mode`, `iterable_mode`, and `mapping_mode` flags for fine-grained control.
gotcha C++ Compiler Requirement for Source Installation: If a pre-compiled binary wheel is not available for your specific Python version and operating system, `pip install` will attempt to compile `python-rapidjson` from source. This requires a C++ compiler toolchain (e.g., build-essential on Linux, Xcode Command Line Tools on macOS, or Visual C++ Build Tools on Windows) to be installed on your system.
Fix: Ensure you have a C++ compiler installed, or install `python-rapidjson` via `conda` which typically manages compiler dependencies.
gotcha `DM_UNIX_TIME` for `dumps` (Serialization) Only: The `DM_UNIX_TIME` option, used with `datetime_mode` for serializing `date`, `datetime`, and `time` objects as numeric timestamps, is an irreversible operation. Consequently, it is only supported for `dumps()` (serialization) functions. Passing `DM_UNIX_TIME` to `loads()` (deserialization) will raise an error.
Fix: Do not use `DM_UNIX_TIME` when calling `rapidjson.loads()` or initializing a `Decoder`. Select an appropriate `datetime_mode` that supports both serialization and deserialization if round-tripping datetime objects is required (e.g., `DM_ISO8601`).
gotcha Recursion Limit for Parsing: As of version 1.15, `python-rapidjson` honors the Python recursion limit during parsing to prevent potential denial-of-service attacks related to extremely deeply nested JSON structures. Prior versions may not have enforced this limit, making them potentially vulnerable to stack overflow issues with malicious inputs.
Fix: Upgrade to version 1.15 or newer. For applications processing untrusted or extremely deep JSON, be aware of `sys.setrecursionlimit()` and how it affects parsing.

Install

pip install python-rapidjson PyPI
conda install -c conda-forge python-rapidjson Conda

Imports

rapidjson
```
import rapidjson
```
dumps
```
rapidjson.dumps(data)
```
While API-compatible, directly using `rapidjson.dumps` is intended. Be aware of minor incompatibilities with the standard `json` module's behavior.
loads
```
rapidjson.loads(json_string)
```
While API-compatible, directly using `rapidjson.loads` is intended. Be aware of minor incompatibilities with the standard `json` module's behavior, especially regarding UTF-8 enforcement for bytes.

Decoder

from rapidjson import Decoder, PM_COMMENTS, PM_TRAILING_COMMAS

Encoder
```
from rapidjson import Encoder
```

Quickstart

This quickstart demonstrates the basic serialization (`dumps`) and deserialization (`loads`) functionality of `python-rapidjson`, which mirrors the standard library `json` module. It also includes an example of using the `Decoder` class with `parse_mode` flags to handle more relaxed JSON syntax, such as comments and trailing commas.

import rapidjson
import os

# Example data
data = {'name': 'Alice', 'age': 30, 'isStudent': False}

# Serialize to JSON string
json_string = rapidjson.dumps(data)
print(f"Serialized: {json_string}")

# Deserialize from JSON string
loaded_data = rapidjson.loads(json_string)
print(f"Deserialized: {loaded_data}")

# Example with custom Decoder for relaxed syntax (JSONC, trailing commas)
try:
    from rapidjson import Decoder, PM_COMMENTS, PM_TRAILING_COMMAS
    decoder = Decoder(parse_mode=PM_COMMENTS | PM_TRAILING_COMMAS)
    relaxed_json = '''
    {
        "item": "value", /* This is a comment */
        "count": 123,   // Another comment
        "enabled": true, // Trailing comma
    }
    '''
    parsed_relaxed = decoder(relaxed_json)
    print(f"Parsed relaxed JSON: {parsed_relaxed}")
except ImportError:
    print("Custom Decoder features not available (might be an older version or specific flags are missing).")

view raw JSON →