cbor2

cbor2 is a Python library for encoding and decoding data in the Concise Binary Object Representation (CBOR) format defined by RFC 8949. It exposes a simple, json-like API (dumps/loads, dump/load) while implementing the heavy lifting in Rust for speed, and supports a wide range of CBOR tags mapped to Python standard-library objects.

Beyond basic serialization, cbor2 handles shared value references (including cyclic structures), string references for compact repeated-string encoding, and fully customizable tag handling through encoder default hooks and decoder tag/object hooks. It also ships a command-line tool for converting CBOR streams to JSON for diagnostics.

What You Get

• A simple API (dumps/loads, dump/load) modeled on the json and pickle modules
• Extensive CBOR tag support mapping to Python standard-library types (datetime, Decimal, fractions, UUID, and more)
• Shared and string reference encoding for compact output and cyclic data structures
• Customizable encoding and decoding via default, tag_hook, and object_hook callbacks
• A cbor2 command-line tool that converts CBOR files or streams to JSON for diagnostics

Common Use Cases

• Serializing structured data into a compact binary format for storage or transport
• Interoperating with CBOR-based protocols and IoT/embedded systems
• Encoding complex Python objects with custom tag hooks for round-tripping
• Inspecting binary CBOR payloads by converting them to readable JSON

Under The Hood

Architecture - The library is a thin Python package (python/cbor2 with init.py, tool.py, and type stubs) layered over a compiled Rust extension module (cbor2._cbor2) whose encoder.rs, decoder.rs, and types.rs implement the actual CBOR encoding, decoding, and tag-to-type mapping; the Python side re-exports the fast path and provides the CLI entry point (cbor2.tool:main).

Tech Stack - Rust powers the core (built via setuptools-rust from rust/Cargo.toml), with a Python front end targeting CPython and PyPy 3.10 through 3.15, including free-threaded builds. Packaging uses setuptools with setuptools_scm for versioning, and documentation is built with Sphinx and hosted on Read the Docs.

Code Quality - The project enforces strict mypy typing, ruff linting with several extended rule sets, and ships a py.typed marker. Testing is thorough: pytest with Hypothesis property-based tests, coverage reporting, atheris fuzzing harnesses, and a tox matrix across many interpreters, run on both big- and little-endian architectures.

API Design - The public surface intentionally mirrors the json and pickle modules (dumps/loads, dump/load), so it is immediately familiar. Advanced behavior — custom types, shared references, tag handling — is opt-in through well-named hook parameters (default, tag_hook, object_hook), keeping the common case trivial while leaving full control available.