jam.types.base.enum

Enum type implementation for the JAM protocol.

Type Definition

Enum

  • Extends Python’s built-in Enum type

  • Adds encoding/decoding capabilities

  • JSON serialization support

  • Type-safe variant selection

Encoding Format

Structure:

[Index: u8]  # Single byte index into enum variants

  • Index: Zero-based index of the enum variant in declaration order

  • Maximum 256 variants supported (u8 limit)

  • Deterministic encoding based on declaration order

Implementation Details

Memory Layout

  • Single byte storage

  • No padding or alignment

  • Direct buffer access

  • Zero-copy decoding

Variant Handling

  • Variants ordered by declaration

  • Index-based encoding

  • Name and value preservation

  • Type safety checks

JSON Support

  • Bidirectional conversion

  • Value-based serialization

  • Name-based deserialization

  • Error handling

Error Handling

Common error cases:

  1. Too many variants:

    if index > 255:
    raise ValueError("Enum index is too large to encode into a single byte")

  2. Invalid variant:

    if variant_name not in cls._member_names_:
    raise ValueError(f"Invalid variant: {variant_name}")

  3. JSON conversion error:

    if value not in cls.__members__.values():
    raise JsonDeserializationError(f"Invalid value: {value}")

Examples

Basic Usage

from jam.types.base.enum import Enum, decodable_enum

@decodable_enum
class Color(Enum):
    RED = 1
    GREEN = 2
    BLUE = 3

# Create and encode
color = Color.RED
encoded = color.encode()  # -> [00]  # First variant

# Decode
decoded = Color.decode(encoded)
assert decoded == Color.RED

JSON Handling

# Value-based JSON
json_data = Color.RED.to_json()  # -> 1
color = Color.from_json(1)  # -> Color.RED

# Name-based JSON
color = Color.from_json("RED")  # -> Color.RED

API Reference

Classes

class jam.types.base.enum.Enum(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Codable, JsonSerde, Enum

Decodable Enum type - Extending the built-in Enum type to add encoding and decoding methods

How to use it: >>> class MyEnum(Enum): >>> A = 1 >>> B = 2 >>> C = 3 >>> >>> value = MyEnum.A >>> encoded = value.encode() >>> decoded, bytes_read = MyEnum.decodeFrom(encoded) >>> assert decoded == value >>> assert bytes_read == 1 >>> >>> assert MyEnum.from_json(1,) == MyEnum.A >>> assert MyEnum.from_json(“A”,) == MyEnum.A

encode_size() → int[source]

Return the size in bytes needed to encode this enum value

encode_into(buffer: bytearray, offset: int = 0) → int[source]

Encode this enum value into the given buffer at the given offset

Parameters:

  • buffer – The buffer to encode into

  • offset – The offset to start encoding at

Returns:

The number of bytes written

Raises:

ValueError – If the enum has too many variants to encode in a byte

classmethod decodeFrom(data: bytes | bytearray | memoryview, offset: int = 0) → Tuple[T, int][source]

Decode an enum value from the given buffer at the given offset

Parameters:

  • data – The buffer to decode from

  • offset – The offset to start decoding at

Returns:

A tuple of (decoded enum value, number of bytes read)

Raises:

ValueError – If the encoded index is invalid

classmethod from_json(data: Any) → T[source]

Convert a JSON value to an enum value

Parameters:

data – The JSON value (either the enum value or name)

Returns:

The corresponding enum value

Raises:

JsonDeserializationError – If the value is invalid

to_json() → Any[source]

Convert this enum value to a JSON value

Returns:

The enum’s value for JSON serialization

Decorators

jam.types.base.enum.decodable_enum(cls: Type[Enum]) → Type[Enum][source]

Decorator to make an enum class decodable

Parameters:

cls – The enum class to make decodable

Returns:

The decorated enum class with decode_from method added