jam.utils.codec.errors

Error types for codec operations.

Exception Types

CodecError

Base exception class for all codec-related errors:

class CodecError(Exception):
    pass

BufferError

Exception for buffer operation errors:

@dataclass
class BufferError(CodecError):
    expected: int  # Expected bytes
    actual: int   # Available bytes
    message: str  # Error description

EncodeError

Exception raised during encoding:

class EncodeError(BufferError):
    pass

DecodeError

Exception raised during decoding:

class DecodeError(BufferError):
    pass

Common Error Cases

Buffer Operations

Buffer underflow:

if len(buffer) - offset < needed:
    raise BufferError(
        expected=needed,
        actual=len(buffer) - offset,
        message="Buffer too short"
    )

Buffer overflow:

if offset + length > len(buffer):
    raise BufferError(
        expected=length,
        actual=len(buffer) - offset,
        message="Buffer overflow"
    )

Type Errors

Type mismatch:

if not isinstance(value, expected_type):
    raise EncodeError(
        expected=sizeof(expected_type),
        actual=sizeof(type(value)),
        message=f"Expected {expected_type}, got {type(value)}"
    )

Invalid value:

if value < 0 or value > max_value:
    raise EncodeError(
        expected=sizeof(int),
        actual=sizeof(value),
        message=f"Value {value} out of range"
    )

Format Errors

Invalid UTF-8:

try:
    return bytes.decode('utf-8')
except UnicodeError as e:
    raise DecodeError(
        expected=len(bytes),
        actual=0,
        message=f"Invalid UTF-8: {e}"
    )

Invalid length prefix:

if prefix > max_length:
    raise DecodeError(
        expected=max_length,
        actual=prefix,
        message="Invalid length prefix"
    )

Examples

Basic Usage

try:
    codec.decode(buffer)
except BufferError as e:
    print(f"Buffer error: expected {e.expected} bytes, got {e.actual}")
except EncodeError as e:
    print(f"Encoding error: {e.message}")
except DecodeError as e:
    print(f"Decoding error: {e.message}")

Custom Errors

class ValidationError(CodecError):
    def __init__(self, field: str, value: Any):
        super().__init__(f"Invalid {field}: {value}")
        self.field = field
        self.value = value

try:
    if value < 0:
        raise ValidationError("age", value)
except ValidationError as e:
    print(f"Validation failed: {e.field} = {e.value}")

API Reference

Error types for codec operations.

exception jam.utils.codec.errors.CodecError[source]

Bases: Exception

Base codec exception.

exception jam.utils.codec.errors.BufferError(expected: int, actual: int, message: str = 'Buffer error')[source]

Bases: CodecError

Buffer operation error with expected vs actual size.

expected: int

actual: int

message: str = 'Buffer error'

__init__(expected: int, actual: int, message: str = 'Buffer error') → None

exception jam.utils.codec.errors.EncodeError(expected: int, actual: int, message: str = 'Buffer error')[source]

Bases: BufferError

Exception raised when encoding fails.

exception jam.utils.codec.errors.DecodeError(expected: int, actual: int, message: str = 'Buffer error')[source]

Bases: BufferError

Exception raised when decoding fails.