dag_cbor.encoding

Encoding functions for DAG-CBOR codec.

canonical_order_dict

canonical_order_dict(value)[source]

Returns a dictionary with canonically ordered keys, according to the DAG-CBOR specification. Specifically, keys are sorted increasingly first by length and then by the lexicographic ordering of the corresponding UTF-8 bytestrings.

Parameters:: value (Dict[str, Any]) –
Return type:: Dict[str, Any]

check_key_compliance

check_key_compliance(value)[source]

Enforces DAG-CBOR compliance for keys in a mapping.

Parameters:: value (Dict[str, Any]) –
Return type:: None

encode

encode(data, stream=None, *, include_multicodec=False, normalize_strings=None)[source]

Encodes the given data with the DAG-CBOR codec.

By default, the encoded data is written to an internal stream and the bytes are returned at the end (as a bytes object).

def encode(data: IPLDKind, stream: None = None) -> bytes:
    ...

Example usage:

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

If a stream is given, the encoded data is written to the stream and the number of bytes written is returned:

def encode(data: IPLDKind, stream: BufferedIOBase) -> int:
    ...

Example usage with a stream:

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

Parameters:

data (IPLDKind) – the DAG data to be encoded
stream (Optional[BufferedIOBase]) – an optional stream into which the encoded data should be written
include_multicodec (bool; default = False) – if True, the encoded data is prefixed by the multicodec code for 'dag-cbor' (see multicodec.wrap).
normalize_strings (Optional[Literal['NFC', 'NFKC', 'NFD', 'NFKD']]) – whether strings should be normalised prior to encoding

Raises:

CBOREncodingError – if an int outside of range(-2**64, 2**64) is encountered
DAGCBOREncodingError – if a value of type other than None, bool, int, float, str, bytes, list, dict, or CID is encountered
DAGCBOREncodingError – if attempting to encode the special float values NaN, Infinity and -Infinity
DAGCBOREncodingError – if a key of a dictionary is not a string

Return type:

Union[bytes, int]