dag_cbor.decoding

Deconding function for DAG-CBOR codec.

DecodeCallback

class DecodeCallback(*args, **kwargs)[source]

Bases: Protocol

Type of optional callbacks for the decode function.

decode

decode(stream_or_bytes, *, allow_concat=False, callback=None, require_multicodec=False, normalize_strings=None)[source]

Decodes and returns a single data item from the given stream_or_bytes, with the DAG-CBOR codec.

A simple use for the optional callback argument is to count the number of bytes read from the stream:

>>> import dag_cbor
>>> from io import BytesIO
>>> class BytesReadCounter:
...     _num_bytes_read = 0
...     def __call__(self, _, num_bytes_read):
...         self._num_bytes_read += num_bytes_read
...     def __int__(self):
...         return self._num_bytes_read
...
>>> encoded_bytes = b'\xa2aa\x0cabfhello!\x82\x00\x01'
>>> len(encoded_bytes)
16
>>> stream = BytesIO(encoded_bytes)
>>> bytes_read_cnt = BytesReadCounter()
>>> dag_cbor.decode(stream, allow_concat=True, callback=bytes_read_cnt)
{'a': 12, 'b': 'hello!'}
>>> int(bytes_read_cnt)
13
>>> bytes_remaining = stream.read()
>>> bytes_remaining
b'\x82\x00\x01'
>>> len(bytes_remaining)
3
>>> dag_cbor.decode(bytes_remaining)
[0, 1]

Parameters:

stream_or_bytes (Union[BufferedIOBase, bytes]) – the bytes object or bytes stream to decode
allow_concat (bool; default = False) – whether to allow partial stream decoding (if this is False, a byte stream will always be consumed in its entirety)
callback (Optional[DecodeCallback]) – optional callback to be invoked as callback(item, num_bytes_read) every time an item is decoded, where num_bytes_read is the number of bytes read decoding the item (excluding sub-items, in the case of lists or dictionaries).
require_multicodec (bool; default = False) – if True, the data being decoded must be prefixed by the multicodec code for 'dag-cbor' (see multicodec.unwrap).
normalize_strings (Literal['NFC', 'NFKC', 'NFD', 'NFKD', None]) – whether strings should be normalised after decoding

Raises:

CBORDecodingError – while reading the leading byte of a data item head, if no bytes are available
CBORDecodingError – while reading the argument bytes of a data item head, if the expected number of argument bytes is not available
CBORDecodingError – while decoding the data of a bytestring or string, if the expected number of data bytes is not available
CBORDecodingError – while decoding the items of a list or a map (keys and values), if the expected number of items is not available
CBORDecodingError – if an invalid utf-8 byte sequence is encountered while attempting to decode a string
DAGCBORDecodingError – if attempting to decode the special float values NaN, Infinity and -Infinity
DAGCBORDecodingError – if the additional info is greater than 27, or different from 27 for major type 7
DAGCBORDecodingError – if an integer value was not minimally encoded
DAGCBORDecodingError – if a key of a map is not a string
DAGCBORDecodingError – if a map has repeated keys
DAGCBORDecodingError – if map keys are not in canonical order
DAGCBORDecodingError – if a tag (major type 6) different than 42 (for CID data) is encountered
DAGCBORDecodingError – if non-bytestring data is found where CID data is expected (tag 42)
DAGCBORDecodingError – if a simple value (major type 7) different from 20 (False), 21 (True) or 22 (None) is encountered
DAGCBORDecodingError – if require_multicodec is set to True and the bytes are not prefixed by the 'dag-cbor' multicodec code
DAGCBORDecodingError – if allow_concat is set to False and the decoding did not use all available bytes

Return type:

IPLDKind