cbor

library1.0.0pypypi✓ verified 24d ago

The `cbor` library provides a Python implementation of RFC 7049, the Concise Binary Object Representation (CBOR). It allows encoding and decoding Python objects into a compact, binary format, offering an API similar to Python's built-in `json` module. The current version is 1.0.0, released in March 2024, indicating a stable and mature API, with a relatively slow release cadence focused on stability.

serialization

pip install cbor

package ↗homepage ↗

INSTALL

IMPORT

SIG · CBOR

cbor

serializationpythonv1.0.0

Install

2.4s avg

Import

10ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.002s · 19.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.4s · import 0.002s · 20MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

cbor

✓ import cbor

This quickstart demonstrates encoding and decoding basic Python data types, including `datetime` objects and `bytes`, to and from CBOR binary format. It also shows how to use `dump` and `load` for streaming data to/from file-like objects.

import cbor import io import datetime # Example Python dictionary with various types data_to_encode = { 'name': 'Alice', 'age': 30, 'is_student': False, 'grades': [95.5, 88, 92.0], 'address': None, 'bio_bytes': b'\x01\x02\x03', 'timestamp': datetime.datetime.now(datetime.timezone.utc).replace(microsecond=0) } # 1. Encode to bytes encoded_bytes = cbor.dumps(data_to_encode) print(f"Encoded CBOR bytes: {encoded_bytes.hex()}") # 2. Decode from bytes decoded_data = cbor.loads(encoded_bytes) print(f"Decoded data: {decoded_data}") print(f"Decoded timestamp type: {type(decoded_data['timestamp'])}") # 3. Encode/Decode using file-like objects (streaming) buffer = io.BytesIO() cbor.dump(data_to_encode, buffer) buffer.seek(0) stream_decoded_data = cbor.load(buffer) print(f"Stream decoded data: {stream_decoded_data}")

Debug

Known issues

breakingOlder versions (e.g., pre-0.2.0) of the `cbor` library had minor API changes (e.g., removal of `cbor.MAJOR_TYPE_BITS`, aliasing of `cbor.CBORError`). While the 1.0.0 API is stable, upgrading from very old `0.x` versions might require minor code adjustments.

fix

Consult the `CHANGES.rst` file in the GitHub repository for specific migration details if upgrading from legacy `0.x` versions. For new projects, always install the latest stable version.

affects: <0.2.0 to 1.0.0

gotchaSimilar to `json`, `cbor.dumps()` cannot serialize arbitrary Python objects (e.g., custom classes) by default. It only handles built-in types and a few standard library types like `datetime`.

fix

For custom objects, provide a `default` callable argument to `cbor.dumps()` that returns a serializable representation of the object. Alternatively, convert custom objects to a dictionary or list before serialization.

affects: >=0.1.0

gotchaThe library explicitly supports only Python 3. Despite PyPI metadata listing `requires_python: None`, attempting to use `cbor` in a Python 2 environment will result in import errors or syntax issues.

fix

Ensure your project runs on Python 3 (preferably 3.8+). If you need CBOR for Python 2, you will need to find a different, compatible library or port your environment to Python 3.

affects: <3.0

gotcha`datetime.datetime` objects are serialized using CBOR tag 0, which represents a standard date/time string (RFC 3339). If you require a different representation, such as a UNIX timestamp or a custom string format, you must convert the `datetime` object manually before serialization.

fix

Before calling `cbor.dumps()` or `cbor.dump()`, convert `datetime` objects to your desired format (e.g., `int(dt.timestamp())` for UNIX timestamp, `dt.isoformat()` for ISO string) or implement a custom `default` serializer if you need more control over date handling.

affects: >=0.1.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'cbor'

The `cbor` library is not installed in the Python environment, or the environment where the code is run does not have access to the installed package.

fix

Install the library using pip: `pip install cbor`

NameError: name 'cbor' is not defined

The `cbor` library has been installed but has not been imported into the Python script before being used.

fix

Add `import cbor` at the beginning of your Python script.

TypeError: a bytes-like object is required, not 'str'

The `cbor.loads()` function expects a bytes object as input, but it received a string. Unlike JSON, CBOR is a binary format.

fix

Ensure the input to `cbor.loads()` is a bytes object, typically by reading from a file in binary mode (`'rb'`) or by prefixing a string literal with `b` (e.g., `b'my_cbor_data'`). For files, use `cbor.load()` with an open binary file handle.

Upgrade

Version history

1.0.0latest on PyPI · released Feb 9, 2016

Audit

Dependencies

No dependency data recorded yet.

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/cbor/ ↗

homepagehttps://bitbucket.org/bodhisnarkva/cbor ↗