{"id":4467,"library":"cbor","title":"CBOR (Concise Binary Object Representation)","description":"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.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/agronholm/cbor","tags":["serialization","binary","data format","RFC 7049"],"install":[{"cmd":"pip install cbor","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"cbor","correct":"import cbor"}],"quickstart":{"code":"import cbor\nimport io\nimport datetime\n\n# Example Python dictionary with various types\ndata_to_encode = {\n    'name': 'Alice',\n    'age': 30,\n    'is_student': False,\n    'grades': [95.5, 88, 92.0],\n    'address': None,\n    'bio_bytes': b'\\x01\\x02\\x03',\n    'timestamp': datetime.datetime.now(datetime.timezone.utc).replace(microsecond=0)\n}\n\n# 1. Encode to bytes\nencoded_bytes = cbor.dumps(data_to_encode)\nprint(f\"Encoded CBOR bytes: {encoded_bytes.hex()}\")\n\n# 2. Decode from bytes\ndecoded_data = cbor.loads(encoded_bytes)\nprint(f\"Decoded data: {decoded_data}\")\nprint(f\"Decoded timestamp type: {type(decoded_data['timestamp'])}\")\n\n# 3. Encode/Decode using file-like objects (streaming)\nbuffer = io.BytesIO()\ncbor.dump(data_to_encode, buffer)\nbuffer.seek(0)\nstream_decoded_data = cbor.load(buffer)\nprint(f\"Stream decoded data: {stream_decoded_data}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"Older 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.","severity":"breaking","affected_versions":"<0.2.0 to 1.0.0"},{"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.","message":"Similar 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`.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"<3.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}