dag-cbor 0.0.4

Python implementation of the DAG-CBOR codec.

dag-cbor: A Python implementation of DAG-CBOR

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.

You can install this package with pip:

pip install dag-cbor

The documentation for this package is automatically generated by pdoc.

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!'}

A buffered binary stream (i.e. an instance of io.BufferedIOBase) can be passed to the encode function using the optional keyword argument stream, in which case the encoded bytes are written to the stream rather than returned:

>>> from io import BytesIO
>>> mystream = BytesIO()
>>> dag_cbor.encode({'a': 12, 'b': 'hello!'}, stream=mystream)
>>> mystream.getvalue()
b'\xa2aa\x0cabfhello!'

A buffered binary stream can be passed to the decode function instead of a bytes object, in which case the contents of the stream are read in their entirety and decoded:

>>> mystream = BytesIO(b'\xa2aa\x0cabfhello!')
>>> dag_cbor.decode(mystream)
{'a': 12, 'b': 'hello!'}

Random data

The random module contains functions to generate random data compatible with DAG-CBOR encoding. The functions are named rand_X, where X is one of int, bytes, str, bool (for False and True), bool_none (for False, True or None), list, dict, or cid (for CID data, encoded as an instance of BaseCID from the py-cid package). The function call rand_X(n) returns an iterator yielding a stream of n random values of type X:

>>> import pprint
>>> from dag_cbor.random import rand_options, rand_dict
>>> options = {
... 	"min_codepoint": 0x30,
...     "max_codepoint": 0x7a,
...     "max_chars": 4,
...     "max_bytes": 8,
...		"include_cid": False
... }
>>> with rand_options(**options):
...     for d in rand_dict(3):
...             pprint.pp(d)
...
{'': False,
 'biq': b'\x9b\xf4\xb7oG\x90',
 'ctz': b'{\x94^`_',
 'rg': 1.0563551621961306e+308,
 'y': ['ejdx',
       [None,
        8009056699280396679,
        3.6758824653722026e+307,
        -1.5555617166832836e+308,
        ''],
       1.6466769889093459e+308,
       [-12301485475384051926,
        '',
        b'zH\xe5',
        18321703892302698705,
        8.795874874880185e+307,
        'jwdr']]}
{'': -1.2571678042268863e+308, 'vmwq': -3474837013640509145}
{'h': [['k', False, -14411084192553465082],
       1.6359295422392278e+308,
       'vcad',
       False],
 'nsio': b'*\xa6;\xf9\xab',
 'sdmc': -359404367281466347}

For the full list of functions and options, please refer to the dag_cbor.random documentation.