jam.utils.codec.primitives package
Submodules
Module Contents
Primitive type codecs for JAM protocol.
This module provides codecs for primitive types including: - Integers (fixed width and general) - Booleans - Strings - Bit sequences
- class jam.utils.codec.primitives.IntegerCodec(byte_size: int)[source]
Bases:
CodecBase codec for fixed-width integers.
Encodes integers in little-endian format with fixed width. Supports both signed and unsigned values.
- __init__(byte_size: int)[source]
Initialize codec for specific integer type.
- Parameters:
byte_size – Number of bytes for encoded value
python_type – Python type for values
- encode_into(value: int, buffer: bytes | bytearray | memoryview, offset: int = 0) int[source]
Encode integer into buffer.
- Parameters:
value – Integer to encode
buffer – Target buffer
offset – Starting offset
- Returns:
Number of bytes written
- Raises:
EncodeError – If value out of bounds or buffer too small
- static decode_from(_byte_size: int, buffer: bytes | bytearray | memoryview, offset: int = 0) Tuple[int, int][source]
Decode integer from buffer.
- Parameters:
buffer – Source buffer
offset – Starting offset
context – Optional decoding context
- Returns:
Tuple of (decoded value, bytes read)
- Raises:
DecodeError – If buffer too small
- class jam.utils.codec.primitives.GeneralCodec[source]
-
Codec for variable-length integer encoding.
Implements variable length int encoding scheme
- encode_into(value: int, buffer: bytearray, offset: int = 0) int[source]
Encode integer using variable-length scheme.
- Parameters:
value – Integer to encode
buffer – Target buffer
offset – Starting offset
- Returns:
Number of bytes written
- Raises:
EncodeError – If value invalid or buffer too small
- static decode_from(buffer: bytes | bytearray | memoryview, offset: int = 0) Tuple[int, int][source]
Decode integer using variable-length scheme.
- Parameters:
buffer – Source buffer
offset – Starting offset
- Returns:
Tuple of (decoded value, bytes read)
- Raises:
DecodeError – If buffer too small or invalid encoding
- class jam.utils.codec.primitives.BooleanCodec[source]
-
Codec for boolean values.
Encoding scheme: - False -> b’’ - True -> b’00’
Any non-zero value is decoded as True for robustness.
- encode_size(value: bool) int[source]
Calculate size needed to encode a boolean value.
- Parameters:
value – Boolean to encode
- Returns:
Always returns 1 as booleans are encoded as a single byte
- encode_into(value: bool, buffer: bytearray, offset: int = 0) int[source]
Encode a boolean value into the provided buffer.
- Parameters:
value – Boolean to encode
buffer – Target buffer
offset – Starting position in buffer
- Returns:
Number of bytes written (always 1)
- Raises:
EncodeError – If the buffer is too small or value is invalid type
- static decode_from(buffer: bytes | bytearray | memoryview, offset: int = 0) Tuple[bool, int][source]
Decode a boolean value from the provided buffer.
- Parameters:
buffer – Source buffer
offset – Starting position in buffer
- Returns:
Tuple of (decoded boolean, bytes read)
- Raises:
DecodeError – If the buffer is too small
- class jam.utils.codec.primitives.StringCodec[source]
-
Codec for string values.
Handles both str and static str references with UTF-8 encoding. Maximum string length is determined by u64 max value.
- encode_size(value: str | bytes) int[source]
Calculate the number of bytes needed to encode the string.
The size includes: - 8 bytes for length prefix (u64) - bytes needed for UTF-8 encoded string content
- Parameters:
value – String to encode
- Returns:
Total number of bytes needed
- Raises:
EncodeError – If string is too large to encode
- encode_into(value: str, buffer: bytearray, offset: int = 0) int[source]
Encode a string into the provided buffer.
- Parameters:
value – String to encode
buffer – Target buffer
offset – Starting position in buffer
- Returns:
Number of bytes written
- Raises:
EncodeError – If buffer is too small or string cannot be encoded
- static decode_from(buffer: bytes | bytearray | memoryview, offset: int = 0) Tuple[str, int][source]
Decode a string from the provided buffer.
- Parameters:
buffer – Source buffer
offset – Starting position in buffer
- Returns:
Tuple of (decoded string, bytes read)
- Raises:
DecodeError – If buffer is too small or contains invalid UTF-8