Universal Binary JSON

0.16.1 · active · verified Sat Apr 11

py-ubjson is a Python library providing a Universal Binary JSON (UBJSON) encoder and decoder, adhering to the draft-12 specification. It aims to offer an API similar to Python's built-in `json` module for seamless serialization and deserialization of UBJSON data. The library includes an optional C extension for significant performance improvements. The current version is 0.16.1.

Warnings

gotcha The C extension is not strictly required but offers a significant speed boost. If performance is critical, ensure Cython is available during installation to build the extension. Installations via `pip install py-ubjson` typically attempt to build the extension by default.
Fix: To explicitly skip the extension build (e.g., for troubleshooting), set the environment variable `PYUBJSON_NO_EXTENSION=1` before installation: `PYUBJSON_NO_EXTENSION=1 pip install py-ubjson`. To verify if the extension is enabled at runtime, check `ubjson.EXTENSION_ENABLED`.
gotcha The UBJSON 'No-Op' type is only supported by the decoder, not the encoder. Additionally, its usage is restricted to the start or between elements of a container and only within un-typed containers, as its presence in typed containers can lead to ambiguity.
Fix: Avoid generating No-Op types in your data when encoding. When decoding, be aware of its specific limitations if encountering No-Op types in incoming UBJSON streams.
gotcha Strongly-typed containers (e.g., for arrays or objects) are primarily supported by the decoder (with the exception of bytes/bytearray). The encoder does not currently support generating strongly-typed containers, and they do not support the No-Op type.
Fix: When encoding, `py-ubjson` will produce dynamically-typed containers. When decoding, understand that while strongly-typed containers can be consumed, you cannot explicitly create them using the `py-ubjson` encoder at this time.

Install

pip install py-ubjson Install with pip

Imports

ubjson
```
import ubjson
```
dumpb
```
from ubjson import dumpb
```
Used to encode Python objects to a UBJSON `bytes` object.
loadb
```
from ubjson import loadb
```
Used to decode a UBJSON `bytes` object to a Python object.
dump
```
from ubjson import dump
```
Used to encode Python objects to a file-like object.
load
```
from ubjson import load
```
Used to decode a file-like object containing UBJSON data.

Quickstart

This example demonstrates how to encode a Python dictionary into UBJSON bytes and then decode it back using `ubjson.dumpb` and `ubjson.loadb`.

import ubjson

data = {
    'name': 'Alice',
    'age': 30,
    'isStudent': False,
    'courses': ['Math', 'Science'],
    'grades': {'Math': 95, 'Science': 88}
}

# Encode to UBJSON bytes
encoded_data = ubjson.dumpb(data)
print(f"Encoded (bytes): {encoded_data!r}")

# Decode from UBJSON bytes
decoded_data = ubjson.loadb(encoded_data)
print(f"Decoded: {decoded_data}")

assert data == decoded_data

view raw JSON →