bluedynamics/zodb-json-codec

README

zodb-json-codec

Fast pickle-to-JSON transcoder for ZODB, implemented in Rust via PyO3.

Converts ZODB pickle records into human-readable, JSONB-queryable JSON while staying round-trip safe. Designed as the codec layer for zodb-pgjsonb, a PostgreSQL JSONB storage backend for ZODB.

Key capabilities:

Round-trip safe: encode to JSON and back yields a pickle that unpickles to an equal object (the bytes differ: memo puts are dropped and the header is rewritten; see the format reference)
Human-readable JSON with compact type markers (@dt, @ref, @t, ...)
JSONB-queryable output for PostgreSQL
Faster than CPython's C pickle extension on most operations
GIL released during Rust phases for multi-threaded Python
Escape hatch (@pkl) ensures any pickle data roundtrips safely

Installation

pip install zodb-json-codec

For building from source, see the documentation.

Quick Example

import zodb_json_codec

# ZODB records (two concatenated pickles: class + state)
record = zodb_json_codec.decode_zodb_record(data)
# -> {"@cls": ["myapp.models", "Document"], "@s": {"title": "Hello", ...}}
data = zodb_json_codec.encode_zodb_record(record)

# Standalone pickle <-> JSON string
json_str = zodb_json_codec.pickle_to_json(pickle_bytes)
pickle_bytes = zodb_json_codec.json_to_pickle(json_str)

Documentation

Full documentation is available at https://bluedynamics.github.io/zodb-json-codec/

Tutorials — Getting started, working with ZODB records
How-To Guides — Install, integrate, benchmark, build from source
Reference — Python API, JSON format, BTree format, project structure
Explanation — Architecture, performance, optimization journal, security

Source Code and Contributions

The source code is managed in a Git repository, with its main branches hosted on GitHub. Issues can be reported there too.

We'd be happy to see many forks and pull requests to make this package even better. We welcome AI-assisted contributions, but expect every contributor to fully understand and be able to explain the code they submit. Please don't send bulk auto-generated pull requests.

Maintainers are Jens Klein and the BlueDynamics Alliance developer team. We appreciate any contribution and if a release on PyPI is needed, please just contact one of us. We also offer commercial support if any training, coaching, integration or adaptations are needed.

License

MIT