Getting Started
This is a fully compliant Python implementation of the DAG-CBOR codec, a subset of the Concise Binary Object Representation (CBOR) supporting the IPLD Data Model and enforcing a unique (strict) encoded representation of items.
Installation
You can install the latest release from PyPI as follows:
$ pip install --upgrade dag-cbor
GitHub repo: https://github.com/hashberg-io/dag-cbor
Basic Usage
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!'}
The ipld
module contains utility types and functions pertaining to the IPLD Data Model.
The random
module contains functions to generate random data compatible with DAG-CBOR encoding.
The DAG-CBOR codec
The DAG-CBOR codec is a restriction of the 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
is0b110_11000
, which means “major type 6 (0b110
, i.e. 6) with 1 byte of argument (0b11000
, i.e. 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, first by increasing length and then by lexicographic ordering of their utf-8 encoded bytes (cf. strictness).
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).
Multiformats Config
Please note that dag_cbor
internally imports multiformats: if you’d like to initialise multiformats
with a custom selection of multicodecs/multihashes, you should call multiformats_config.enable()
before you import dag_cbor
(see the multiformats docs for further details):
import multiformats_config
multiformats_config.enable(codecs=["sha1", 0x29], bases=["base64url", "9"])
import dag_cbor # internally imports multiformats