Package dag_cbor

Python implementation of the DAG-CBOR codec specification.

The core functionality of the library is performed by the encode() and decode() functions:

>>> import dag_cbor
>>> dag_cbor.encode({'a': 12, 'b': 'hello!'})
b'\xa2aa\x0cabfhello!'
>>> dag_cbor.decode(b'\xa2aa\x0cabfhello!')
{'a': 12, 'b': 'hello!'}

For their documentation, see the dag_cbor.encoding and dag_cbor.decoding modules. The dag_cbor.random module contains functions to generate random data compatible with DAG-CBOR encoding. The dag_cbor.utils module contains errors and utility functions.

The DAG-CBOR codec is a restriction of CBOR codec, enforcing additional conventions:

  • The only tag (major type 6) allowed is the CID tag 42, to be encoded as a two bytes head 0xd82a (0xd8 == 0b110_11000 means "major type 6 (0b110 == 6) with 1 byte of argument (0b11000 = 24)", while 0x2a is the number 42).
  • Integers (major types 0 and 1) must be encoded using the minimum possible number of bytes.
  • Lengths for major types 2, 3, 4 and 5 must be encoded in the data item head using the minimum possible number of bytes.
  • Map keys must be strings (major type 3) and must be unique.
  • Map keys must be sorted ascendingly according to the lexicographic ordering of their utf-8 encoded bytes (which is the standard ordering of bytes objects in Python).
  • Indefinite-length items (bytes, strings, lists or maps) are not allowed.
  • The "break" token is not allowed.
  • The only major type 7 items allowed are 64-bit floats (minor 27) and the simple values true (minor 20), false (minor 21) and null (minor 22).
  • The special float values NaN, Infinity and -Infinity are not allowed.
  • Encoding and decoding is only allowed on a single top-level item: back-to-back concatenated items at the top level are not allowed.

Because the CBOR codec can encode/decode all data handled by the DAG-CBOR codec, we use an established CBOR implementation as the reference when testing, namely the cbor2 package (with the exception of CID data, which is not natively handled by cbor2).

Expand source code
"""
    Python implementation of the [DAG-CBOR codec](https://ipld.io/specs/codecs/dag-cbor/spec/) specification.

    The core functionality of the library is performed by the `dag_cbor.encoding.encode` and `dag_cbor.decoding.decode` functions:

    ```python
    >>> import dag_cbor
    >>> dag_cbor.encode({'a': 12, 'b': 'hello!'})
    b'\\xa2aa\\x0cabfhello!'
    >>> dag_cbor.decode(b'\\xa2aa\\x0cabfhello!')
    {'a': 12, 'b': 'hello!'}
    ```

    For their documentation, see the `dag_cbor.encoding` and `dag_cbor.decoding` modules.
    The `dag_cbor.random` module contains functions to generate random data compatible with DAG-CBOR encoding.
    The `dag_cbor.utils` module contains errors and utility functions.

    The DAG-CBOR codec is a restriction of [CBOR codec](https://cbor.io/), enforcing additional conventions:

    - The only tag (major type 6) allowed is the CID tag 42, to be encoded as a two bytes head `0xd82a`
      (`0xd8 == 0b110_11000` means "major type 6 (`0b110 == 6`) with 1 byte of argument (`0b11000 = 24`)",
      while `0x2a` is the number 42).
    - Integers (major types 0 and 1) must be encoded using the minimum possible number of bytes.
    - Lengths for major types 2, 3, 4 and 5 must be encoded in the data item head using the minimum possible number of bytes.
    - Map keys must be strings (major type 3) and must be unique.
    - Map keys must be sorted ascendingly according to the lexicographic ordering of their utf-8 encoded bytes (which is
      the standard ordering of `bytes` objects in Python).
    - Indefinite-length items (bytes, strings, lists or maps) are not allowed.
    - The "break" token is not allowed.
    - The only major type 7 items allowed are 64-bit floats (minor 27) and the simple values `true` (minor 20),
      `false` (minor 21) and `null` (minor 22).
    - The special float values `NaN`, `Infinity` and `-Infinity` are not allowed.
    - Encoding and decoding is only allowed on a single top-level item: back-to-back concatenated items at the top level
      are not allowed.

    Because the CBOR codec can encode/decode all data handled by the DAG-CBOR codec, we use an established CBOR implementation
    as the reference when testing, namely the [`cbor2`](https://github.com/agronholm/cbor2) package (with the exception of CID
    data, which is not natively handled by `cbor2`).
"""

__version__ = "0.1.0"

from .encoding import encode as encode
from .decoding import decode as decode
from . import random as random

Sub-modules

dag_cbor.decoding

Deconding function for DAG-CBOR codec …

dag_cbor.encoding

Encoding functions for DAG-CBOR codec …

dag_cbor.random

Functions to generate random data …

dag_cbor.utils

Error classes and utility functions …