The MoaT-Codec library

% start synopsis % start main

This library packages various codecs used for MoaT protocols in a way that's reason- and stream-able.

% end synopsis

Supplied codecs

• CBOR
• msgpack
• no-op
• UTF-8
• JSON
• YAML

On CPython the CBOR codec is implemented in pure Python. MicroPython uses the ccbor C module instead (compiled into the firmware; moat micro prep builds it into the test interpreters). The wire format is identical; the C decoder is stricter than the pure-Python one in a few places:

• duplicate map keys are an error instead of silently overwriting the earlier value,
• unassigned CBOR simple values are an error instead of a Tag,
• half/single-precision floats decode to their exact value instead of being rounded to a fixed number of significant digits,
• the nesting depth is limited (default 32),
• a not-well-formed byte in an incremental stream is skipped after the error is reported, so decoding can resynchronise.

% end main

Interface

Codec

• encode(obj)

  Encode the object to a bytestream.

• decode(bytes)

  Decode the given bytes to a single object.

• feed(bytes, final=False)

  Data stream. Returns an array of objects.

  This method only exists when a sequence of encoded objects can be streamed, i.e. contains built-in message boundaries.

  if @final is True, raise an exception if there is an incomplete object in the buffer after this call.

• getstate(), setstate(*args)

  A streaming decoder may store partially-decoded state (unprocessed buffer) here.

The list of accepted objects is implementation dependent.

Extension

Extension types vary by whether they carry binary data as in (msgpack), or objects (as in cbor).

• binary (classvar): True if msgpack-style, False if cbor-style

• encoder(cls, key, fn)

  Encode an object obj of type type. fn(codec, obj) must return a bytestring / an encodeable object. If the registration key is None the function must return a tuple with the key as first element.

• decoder(key, fn)

  Add a decoder (key, data) to an object. fn(codec, data) is called with a bytestring / a decoded object, and returns whatever has been encoded.

Extensions get the codec as their first argument. They can use it to store data, e.g. references. The extension object is available as codec.ext.