jam.utils.codec.composite.dictionaries module

Dictionary codec implementation for JAM protocol.

Implements encoding and decoding of key-value mappings according to the JAM specification. Dictionaries are encoded as a length-prefixed sequence of key-value pairs, with pairs sorted by encoded key bytes to ensure deterministic encoding.

Format:

[Length_Tag: u8][Length_Data: varies][Pairs…] where each Pair is:

[Encoded Key][Encoded Value]

class jam.utils.codec.composite.dictionaries.DictionaryCodec[source]

Bases: Codec[Mapping[K, V]], Generic[K, V]

Codec for key-value mappings.

Dictionaries are encoded as length-prefixed sequences of key-value pairs, sorted by encoded key bytes for deterministic encoding.

_encode_pair(key: Codable[K], value: Codable[V], buffer: bytearray, offset: int) → Tuple[bytes, int][source]

Encode a single key-value pair into buffer.

Parameters:

  • key – Key to encode

  • value – Value to encode

  • buffer – Target buffer

  • offset – Starting position in buffer

Returns:

Tuple of (key_bytes for sorting, bytes written)

Raises:

EncodeError – If key/value invalid or buffer too small

encode_size(value: Mapping[Codable[K], Codable[V]]) → int[source]

Calculate number of bytes needed to encode dictionary.

Parameters:

value – Dictionary to encode

Returns:

Number of bytes needed

Raises:

EncodeError – If dictionary contains invalid types

encode_into(value: Mapping[Codable[K], Codable[V]], buffer: bytearray, offset: int = 0) → int[source]

Encode dictionary into buffer.

Parameters:

  • value – Dictionary to encode

  • buffer – Target buffer

  • offset – Starting position in buffer

Returns:

Number of bytes written

Raises:

EncodeError – If dictionary invalid or buffer too small

static decode_from(key_codable_class: Type[Codable[K]], value_codable_class: Type[Codable[V]], buffer: bytes | bytearray | memoryview, offset: int = 0) → Tuple[Dict[K, V], int][source]

Decode dictionary from buffer.

Parameters:

  • buffer – Source buffer

  • offset – Starting position in buffer

Returns:

Tuple of (decoded dict, bytes read)

Raises:

DecodeError – If buffer too small or invalid encoding