Metadata-Version: 2.4
Name: moat-lib-codec
Version: 0.4.23
Summary: A simple command/stream multiplexer
Author-email: Matthias Urlichs <matthias@urlichs.de>
Maintainer-email: Matthias Urlichs <matthias@urlichs.de>
Project-URL: homepage, https://m-o-a-t.org
Project-URL: repository, https://github.com/M-o-a-T/moat
Keywords: MoaT
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AnyIO
Classifier: Framework :: Trio
Classifier: Framework :: AsyncIO
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Developers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: anyio~=4.2
Requires-Dist: moat-lib-rpc~=0.7.23
Requires-Dist: moat-lib-micro~=0.3.7
Requires-Dist: moat-lib-proxy~=0.1.3
Requires-Dist: moat-util~=0.64.13
Requires-Dist: moat-lib-path~=0.4.4
Dynamic: license-file

# 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](https://github.com/M-o-a-T/micropython-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`.
