py-ubjson

py-ubjson is a Python implementation of the Universal Binary JSON draft-12 specification, giving Python programs a json-module-like API (dump/dumpb/load/loadb) for a compact binary serialization format instead of text JSON. It ships as a pure-Python package with an optional C extension that provides a significant speed boost when compiled, and it falls back cleanly to the pure-Python path when the extension is unavailable or explicitly disabled via the PYUBJSON_NO_EXTENSION environment variable.

Beyond the core encode/decode API, the package includes a python3 -mubjson command-line utility for converting files between JSON and UBJSON, and supports encoding any object implementing the standard Mapping/Sequence interfaces rather than only built-in dict/list types. It targets use cases where JSON’s textual overhead is undesirable — compact wire formats, embedded/IoT messaging, and binary storage of structured data — while keeping a drop-in-familiar API for developers already used to Python’s json module.

What You Get

• dump/dumpb and load/loadb functions mirroring the stdlib json module’s API for encoding to and decoding from UBJSON
• An optional C extension (auto-built via setup.py) that significantly speeds up encoding/decoding, with a pure-Python fallback and an ubjson.EXTENSION_ENABLED flag to check which is active at runtime
• Support for encoding any object implementing Python’s Mapping or Sequence interfaces, not just built-in dict/list
• A python3 -mubjson CLI utility to convert files between JSON and UBJSON formats directly from the shell
• Support for strongly-typed and untyped UBJSON containers, plus decoder-side handling of the No-Op marker type

Common Use Cases

• Serializing structured messages for IoT or embedded devices where binary compactness matters more than human readability
• Storing or transmitting structured data in a smaller binary footprint than equivalent JSON text
• Converting existing JSON files or streams to UBJSON (and back) for archival or interchange via the bundled CLI tool
• Swapping json.dumps/json.loads calls for ubjson.dumpb/ubjson.loadb in code that already validates/handles Python’s native JSON types

Under The Hood

Architecture - the package splits into a pure-Python reference implementation (ubjson/encoder.py, ubjson/decoder.py) and an optional CPython C extension built from src/_ubjson.c plus supporting encoder.c/decoder.c/markers.h files that reimplement the same draft-12 spec for speed; setup.py attempts to build the extension automatically and falls back to the pure-Python path (surfaced via ubjson.EXTENSION_ENABLED) if the C toolchain is unavailable or PYUBJSON_NO_EXTENSION is set. Tech Stack - Python 2.7+/3.2+ compatible pure-Python core with a C99 extension for the hot path, packaged with distutils/setuptools Extension; no runtime dependencies beyond the standard library. Code Quality - a test/test.py unit-test suite plus test/perf.py for encode/decode benchmarking, with static analysis enforced via flake8 and pylint using project-specific configs (flake8.cfg, pylint.rc); the repository has been dormant since mid-2024 with no open development activity. API Design - the public surface intentionally mirrors the stdlib json module’s four core functions (dump, dumpb, load, loadb), so callers familiar with json.dumps/json.loads can adopt UBJSON with essentially the same call shape.