tsrkit-types 0.1.0__py3-none-any.whl

tsrkit_types/enum.py

@@ -0,0 +1,128 @@
+from enum import EnumMeta
+from typing import Tuple, Type, Union, Any, TypeVar, cast
+from tsrkit_types.integers import Uint
+
+T = TypeVar("T", bound="Enum")
+
+
+class Enum(metaclass=EnumMeta):
+    """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.decode_from(encoded)
+    >>> assert decoded == value
+    >>> assert bytes_read == 1
+    >>>
+    >>> assert MyEnum.from_json(1,) == MyEnum.A
+    >>> assert MyEnum.from_json("A",) == MyEnum.A
+    """
+    
+    @property
+    def value(self) -> Any:
+        return self._value_
+    
+    @classmethod
+    def _missing_(cls, value: Any) -> T:
+        raise ValueError(f"Invalid value: {value}")
+
+    # ---------------------------------------------------------------------------- #
+    #                                 Serialization                                #
+    # ---------------------------------------------------------------------------- #
+
+    def encode_size(self) -> int:
+        """Return the size in bytes needed to encode this enum value"""
+        return 1
+
+    def encode(self) -> bytes:
+        """Encode the value into a new bytes object."""
+        size = self.encode_size()
+        buffer = bytearray(size)
+        written = self.encode_into(buffer)
+        return bytes(buffer[:written])
+
+    def encode_into(self, buffer: bytearray, offset: int = 0) -> int:
+        """Encode this enum value into the given buffer at the given offset
+
+        Args:
+            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
+        """
+        # Get the index of the enum value in all enums
+        # Encode the index as a byte
+        all_enums = self.__class__._member_names_
+        index = all_enums.index(self._name_)
+        if index > 255:
+            raise ValueError("Enum index is too large to encode into a single byte")
+        return Uint(index).encode_into(buffer, offset)
+
+    @classmethod
+    def decode_from(
+        cls, buffer: Union[bytes, bytearray, memoryview], offset: int = 0
+    ) -> Tuple[T, int]:
+        """Decode an enum value from the given buffer at the given offset
+
+        Args:
+            buffer: 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
+        """
+        # Decode the byte (index of enum) into an Enum
+        # Return the enum value
+        index, bytes_read = Uint.decode_from(buffer, offset)
+        value = cast(T, cls._member_map_[cls._member_names_[index]])
+        return value, bytes_read
+    
+
+    # ---------------------------------------------------------------------------- #
+    #                                  JSON Serde                                  #
+    # ---------------------------------------------------------------------------- #
+
+    @classmethod
+    def from_json(cls: Type[T], data: Any) -> T:
+        """Convert a JSON value to an enum value
+
+        Args:
+            data: The JSON value (either the enum value or name)
+
+        Returns:
+            The corresponding enum value
+
+        Raises:
+            JsonDeserializationError: If the value is invalid
+        """
+        for v in cls.__members__.values():
+            if v._value_ == data or v._name_ == data:
+                return cast(T, v)
+        raise ValueError(f"Invalid value: {data}")
+
+    def to_json(self) -> Any:
+        """Convert this enum value to a JSON value
+
+        Returns:
+            The enum's value for JSON serialization
+        """
+        return self._value_
+
+    @classmethod
+    def decode(cls, buffer: Union[bytes, bytearray, memoryview], offset: int = 0) -> T:
+        """Decode a value from the provided buffer starting at the specified offset."""
+        value, bytes_read = cls.decode_from(buffer, offset)
+        return value

tsrkit_types/integers.py

@@ -0,0 +1,203 @@
+import abc
+from decimal import Decimal
+import math
+from typing import Any, Tuple, Union, Callable
+from tsrkit_types.itf.codable import Codable
+
+
+class IntCheckMeta(abc.ABCMeta):
+    """Meta class to check if the instance is an integer with the same byte size"""
+    def __instancecheck__(cls, instance):
+        return isinstance(instance, int) and getattr(instance, "byte_size", 0) == cls.byte_size
+
+
+class Uint(int, Codable, metaclass=IntCheckMeta):
+    """
+    Unsigned integer type.
+    
+    
+    Usage:
+        >>> # Fixed Integer with defined class
+        >>> U8 = Uint[8]
+        >>> U8(10)
+        U8(10)
+        >>> U8.encode(10)
+        b'\n'
+        >>> U8.decode(b'\n')
+        U8(10)
+
+        >>> # Fixed Integer w dynamic usage
+        >>> num = Uint[8](10)
+        >>> num
+        U8(10)
+        >>> num.encode()
+        b'\n'
+        >>> Uint[8].decode(b'\n')
+        U8(10)
+
+
+        >>> # If you want to use the General Integer (supports up to 2**64 - 1), 
+        >>> # you can use the Uint class without specifying the byte size.
+        >>>
+        >>> num = Uint(10)
+        >>> num
+        Uint(10)
+        >>> num.encode()
+        b'\n'
+        >>> Uint.decode(b'\n')
+        Uint(10)
+
+    """
+
+    # If the byte_size is set, the integer is fixed size.
+    # Otherwise, the integer is General Integer (supports up to 2**64 - 1)
+    byte_size: int = 0
+
+    def __class_getitem__(cls, size: int):
+        return type(f"U{size}" if size else "Int", (cls,), {"byte_size": size // 8})
+
+    def __new__(cls, value: Any):
+        value = int(value)
+        if cls.byte_size > 0:
+            bits = 8 * cls.byte_size
+            min_v = 0
+            max_v = (1 << bits) - 1
+            if not (min_v <= value <= max_v):
+                raise ValueError(f"Fixed Int: {cls.__name__} out of range: {value!r} "
+                                f"not in [{min_v}, {max_v}]")
+        else:
+            if not 0 <= value < 2 ** 64:
+                raise ValueError(f"General Int: Value must be between 0 and 2**64 - 1, got {value}")
+
+        return super().__new__(cls, value)
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}({int(self)})"
+
+    def _wrap_op(self, other: Any, op: Callable[[int, int], int]):
+        res = op(int(self), int(other))
+        return type(self)(res)
+    
+    # ---------------------------------------------------------------------------- #
+    #                                  Arithmetic                                  #
+    # ---------------------------------------------------------------------------- #
+    def __add__(self, other):
+        return self._wrap_op(other, int.__add__)
+
+    def __sub__(self, other):
+        return self._wrap_op(other, int.__sub__)
+
+    def __mul__(self, other):
+        return self._wrap_op(other, int.__mul__)
+
+    def __floordiv__(self, other):
+        return self._wrap_op(other, int.__floordiv__)
+
+    def __and__(self, other):
+        return self._wrap_op(other, int.__and__)
+
+    def __or__(self, other):
+        return self._wrap_op(other, int.__or__)
+
+    def __xor__(self, other):
+        return self._wrap_op(other, int.__xor__)
+    
+    # ---------------------------------------------------------------------------- #
+    #                                  JSON Serde                                  #
+    # ---------------------------------------------------------------------------- #
+    def to_json(self) -> str:
+        return int(self)
+    
+    @classmethod
+    def from_json(cls, json_str: str) -> "Uint":
+        return cls(int(json_str))
+
+    # ---------------------------------------------------------------------------- #
+    #                                  Serialization                               #
+    # ---------------------------------------------------------------------------- #
+    @staticmethod
+    def l(x):
+        return math.floor(Decimal(x).ln() / (Decimal(7) * Decimal(2).ln()))
+
+
+    def encode_size(self) -> int:
+        if self.byte_size > 0:
+            return self.byte_size 
+        else:
+            if self < 2**7:
+                return 1
+            elif self < 2 ** (7 * 9):
+                return 1 + self.l(self)
+            elif self < 2**64:
+                return 9
+            else:
+                raise ValueError("Value too large for encoding. General Uint support up to 2**64 - 1")
+
+    def encode_into(self, buffer: bytearray, offset: int = 0) -> int:
+        if self.byte_size > 0:
+            buffer[offset:offset+self.byte_size] = self.to_bytes(self.byte_size, "little")
+            return self.byte_size
+        else:
+            if self < 2**7:
+                buffer[offset:offset+1] = self.to_bytes(1, "little")
+                return 1
+
+            size = self.encode_size()
+            self._check_buffer_size(buffer, size, offset)
+            if self < 2 ** (7 * 8):
+                _l = self.l(self)
+                # Create temporary U8 for encoding the prefix
+                prefix_value = (2**8 - 2 ** (8 - _l) + 
+                               math.floor(Decimal(self) / (Decimal(2) ** (_l * 8))))
+                buffer[offset] = int(prefix_value)
+                offset += 1
+                # Encode the remaining bytes
+                remaining = self % (2 ** (_l * 8))
+                remaining_bytes = remaining.to_bytes(_l, "little")
+                buffer[offset : offset + _l] = remaining_bytes
+            elif self < 2**64:
+                buffer[offset] = 2**8 - 1  # Full 64-bit marker
+                offset += 1
+                buffer[offset : offset + 8] = self.to_bytes(8, "little")
+            else:
+                raise ValueError(
+                    f"Value too large for encoding. General Uint support up to 2**64 - 1, got {self}"
+                )
+            return size
+    
+    @classmethod
+    def decode_from(
+            cls, buffer: Union[bytes, bytearray, memoryview], offset: int = 0
+    ) -> Tuple[Any, int]:
+        if cls.byte_size > 0:
+            value, size = int.from_bytes(buffer[offset : offset + cls.byte_size], "little"), cls.byte_size
+            return cls.__new__(cls, value), size
+        else:
+            tag = int.from_bytes(buffer[offset:offset+1], "little")
+
+            if tag < 2**7:
+                return cls(tag), 1
+
+            if tag == 2**8 - 1:
+                # Full 64-bit encoding
+                if len(buffer) - offset < 9:
+                    raise ValueError("Buffer too small to decode 64-bit integer")
+                value = int.from_bytes(buffer[offset + 1 : offset + 9], "little")
+                return cls(value), 9
+            else:
+                # Variable length encoding
+                _l = math.floor(
+                    Decimal(8) - (Decimal(2**8) - Decimal(tag)).ln() / Decimal(2).ln()
+                )
+                if len(buffer) - offset < _l + 1:
+                    raise ValueError("Buffer too small to decode variable-length integer")
+                alpha = tag + 2 ** (8 - _l) - 2**8
+                beta = int.from_bytes(buffer[offset + 1 : offset + 1 + _l], "little")
+                value = alpha * 2 ** (_l * 8) + beta
+                return cls(value), _l + 1
+
+
+U8 = Uint[8]
+U16 = Uint[16]
+U32 = Uint[32]
+U64 = Uint[64]

tsrkit_types/itf/codable.py

@@ -0,0 +1,82 @@
+from abc import ABC, abstractmethod
+from typing import TypeVar, Generic, Tuple, Union
+
+T = TypeVar("T")
+
+
+class Codable(ABC, Generic[T]):
+    """Abstract base class defining the interface for encoding and decoding data."""
+
+    @abstractmethod
+    def encode_size(self) -> int:
+        """
+        Calculate the number of bytes needed to encode the value.
+
+        Returns:
+            The number of bytes needed to encode the value.
+        """
+        raise NotImplementedError("Subclasses must implement this method")
+
+    @abstractmethod
+    def encode_into(self, buffer: bytearray, offset: int = 0) -> int:
+        """
+        Encode the value into the provided buffer at the specified offset.
+        
+        Args:
+            buffer: The buffer to encode the value into.
+            offset: The offset at which to start encoding the value.
+
+        Returns:
+            The number of bytes written to the buffer.
+        """
+        raise NotImplementedError("Subclasses must implement this method")
+
+    def encode(self) -> bytes:
+        """
+        Encode the value into a new bytes object.
+
+        Returns:
+            The encoded value as a bytes object.
+        """
+        size = self.encode_size()
+        buffer = bytearray(size)
+        written = self.encode_into(buffer)
+        return bytes(buffer[:written])
+
+    @classmethod
+    def decode_from(cls, buffer: Union[bytes, bytearray, memoryview], offset: int = 0) -> Tuple[T, int]:
+        """
+        Decode a value from the provided buffer starting at the specified offset.
+
+        Args:
+            buffer: The buffer to decode the value from.
+            offset: The offset at which to start decoding the value.
+
+        Returns:
+            A tuple containing the decoded value and the number of bytes read from the buffer.
+        """
+        raise NotImplementedError("Subclasses must implement this method")
+
+    @classmethod
+    def decode(cls, buffer: Union[bytes, bytearray, memoryview], offset: int = 0) -> T:
+        """
+        Decode a value from the provided buffer starting at the specified offset.
+
+        Args:
+            buffer: The buffer to decode the value from.
+            offset: The offset at which to start decoding the value.
+        """
+        value, bytes_read = cls.decode_from(buffer, offset)
+        return value
+    
+    def _check_buffer_size(self, buffer: bytearray, size: int, offset: int) -> None:
+        """
+        Check if the buffer has enough space to encode the value.
+
+        Args:
+            buffer: The buffer to check the size of.
+            size: The size of the value to encode.
+            offset: The offset at which to start encoding the value.
+        """
+        if len(buffer) - offset < size:
+            raise ValueError("Buffer too small to encode value")

tsrkit_types/null.py

@@ -0,0 +1,43 @@
+from typing import Optional, Self, Tuple, Union
+
+
+class NullType:
+    def __repr__(self):
+        return "Null"
+
+    def __eq__(self, other):
+        return not other
+
+    def __bool__(self):
+        return False
+    
+    # ---------------------------------------------------------------------------- #
+    #                                 Serialization                                #
+    # ---------------------------------------------------------------------------- #
+    
+    def encode_size(self) -> int:
+        return 0
+    
+    def encode_into(self, buffer: bytearray, offset: int = 0) -> int:
+        return 0
+    
+    @classmethod
+    def decode_from(cls, buffer: Union[bytes, bytearray, memoryview], offset: int = 0) -> Tuple[Self, int]:
+        return cls(), 0
+    
+    # ---------------------------------------------------------------------------- #
+    #                                  JSON Parse                                  #
+    # ---------------------------------------------------------------------------- #
+
+    def to_json(self) -> str:
+        return None
+    
+    @classmethod
+    def from_json(cls, json_str: Optional[str]) -> Self:
+        if json_str is None:
+            return cls()
+        raise ValueError("Invalid JSON string for NullType")
+    
+    
+    
+Null = NullType()

tsrkit_types/option.py

@@ -0,0 +1,30 @@
+from typing import Generic, Optional, TypeVar
+from tsrkit_types.choice import Choice
+from tsrkit_types.null import Null, NullType
+
+
+T = TypeVar("T")
+
+class Option(Choice, Generic[T]):
+    """
+    Option[T] wraps either no value (None) or a T.
+    """
+
+    def __class_getitem__(cls, opt_t: T):
+        if not isinstance(opt_t, type):
+            raise TypeError("Option[...] only accepts a single type")
+        name = f"Option[{opt_t.__class__.__name__}]"
+        return type(name,
+                    (Option,),
+                    {"_opt_types": ((None, opt_t), (None, NullType))})
+
+    def __init__(self, val: T|NullType = Null):
+        super().__init__(val)
+
+    def set(self, value: T|NullType = Null, key: Optional[str] = None):
+        if value is None:
+            value = Null
+        super().set(value, key)
+
+    def __bool__(self):
+        return self._value != Null

tsrkit_types/sequences.py

@@ -0,0 +1,212 @@
+import abc
+from typing import TypeVar, Type, ClassVar, Tuple, Generic
+from tsrkit_types.integers import Uint
+from tsrkit_types.itf.codable import Codable
+
+T = TypeVar("T")
+
+class SeqCheckMeta(abc.ABCMeta):
+    """Meta class to check if the instance is an integer with the same byte size"""
+    def __instancecheck__(cls, instance):
+        # String comparison is used to avoid identity comparison issues - like Uint[8] and Uint[8]
+        # TODO - This needs more false positive testing
+        _matches_element_type = str(getattr(cls, "_element_type", None)) == str(getattr(instance, "_element_type", None))
+        _matches_min_length = getattr(cls, "_min_length", 0) == getattr(instance, "_min_length", 0)
+        _matches_max_length = getattr(cls, "_max_length", 2**64) == getattr(instance, "_max_length", 2**64)
+        return isinstance(instance, list) and _matches_element_type and _matches_min_length and _matches_max_length
+
+
+class Seq(list, Codable, Generic[T], metaclass=SeqCheckMeta):
+    """
+    Sequence Type
+
+    Usage:
+        >>> # Create a reusable type
+        >>> class Eta(Seq[bytes, 4]): ...
+        >>>
+        >>> # (or) Disposable
+        >>> val_indexes = Seq[int, 1023]([0] * 1028)
+        >>>
+        >>> # Supports codec [both variable and fixed length] given that the element type must support codec
+        >>> Seq[U16, 1023]([0] * 1028).encode()
+    """
+    _element_type: ClassVar[Type[T]]
+    _min_length: ClassVar[int] = 0
+    _max_length: ClassVar[int] = 2 ** 64
+
+    def __class_getitem__(cls, params):
+        # To overwrite previous cls values
+        min_l, max_l, elem_t = 0, 2**64, None
+
+        if isinstance(params, int) or isinstance(params, (type, TypeVar)):
+            if isinstance(params, (type, TypeVar)): 
+                elem_t = params
+            elif isinstance(params, int): 
+                max_l, min_l = params, params
+            else: 
+                raise TypeError(f"Invalid param to define {__class__.__name__}: {params}")
+        elif len(params) == 2:
+            if isinstance(params[0], type) and isinstance(params[1], int): 
+                elem_t, min_l, max_l = params[0], params[1], params[1]
+            elif isinstance(params[0], int) and isinstance(params[1], int): 
+                min_l, max_l = params[0], params[1]
+            else: 
+                raise TypeError(f"Invalid param to define {cls.__class__.__name__}: {params}")
+        elif len(params) == 3 and isinstance(params[0], (type, TypeVar)) and isinstance(params[1], int) and isinstance(params[2], int): 
+            elem_t, min_l, max_l = params
+        else:
+            raise TypeError(f"Invalid param to define {cls.__class__.__name__}: {params}")
+
+        # build a nice name
+        parts = []
+        if elem_t:
+            parts.append(elem_t.__name__)
+        if min_l == max_l:
+            parts.append(f"N={min_l}")
+        else:
+            if min_l: 
+                parts.append(f"min={min_l}")
+            if max_l != 2 ** 64: 
+                parts.append(f"max={max_l}")
+
+        name = f"{cls.__name__}[{','.join(parts)}]"
+
+        return type(name, (cls,), {
+            "_element_type": elem_t,
+            "_min_length": min_l,
+            "_max_length": max_l,
+        })
+
+    def _validate(self, value):
+        """For TypeChecks - added to fns that alter elements"""
+        if getattr(self, "_element_type", None) is not None:
+            if not isinstance(value, self._element_type):
+                raise TypeError(f"{value!r} is not an instance of {self._element_type!r}")
+
+    def _validate_self(self):
+        """For Resultant Self check - added to fns that alter size"""
+        if  len(self) < self._min_length:
+            raise ValueError(f"Vector: Expected sequence size to be >= {self._min_length}, resultant size {len(self)}")
+        elif len(self) > self._max_length:
+            raise ValueError(f"Vector: Expected sequence size to be <= {self._max_length}, resultant size {len(self)}")
+
+    def __init__(self, initial: list[T]):
+        super().__init__()
+        self.extend(initial)
+
+    def append(self, v: T):
+        self._validate(v)
+        super().append(v)
+        self._validate_self()
+
+    def insert(self, i, v: T):
+        self._validate(v)
+        super().insert(i, v)
+        self._validate_self()
+
+    def extend(self, seq: list[T]):
+        for val in seq:
+            self._validate(val)
+        super().extend(seq)
+        self._validate_self()
+
+    def __setitem__(self, i, v: T):
+        self._validate(v)
+        super().__setitem__(i, v)
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}({list(self)})"
+    
+    @property
+    def _length(self):
+        if self._min_length == self._max_length:
+            return self._min_length
+        return None
+    
+    # ---------------------------------------------------------------------------- #
+    #                                 Serialization                                #
+    # ---------------------------------------------------------------------------- #
+    def encode_size(self):
+        size = 0
+
+        # If length is not defined
+        if self._length is None:
+            size += Uint(len(self)).encode_size()
+            
+        for item in self:
+            if not isinstance(item, Codable):
+                raise TypeError(0, 0, f"Expected Codable, got {type(item)}")
+            size += item.encode_size()
+
+        return size
+    
+    def encode_into(self, buffer: bytearray, offset: int = 0) -> int:
+        current_offset = offset
+        # If length is not defined
+        if(self._min_length != len(self)) and (self._max_length != len(self)):
+            current_offset += Uint(len(self)).encode_into(buffer, current_offset)
+
+        for item in self:
+            written = item.encode_into(buffer, current_offset)
+            current_offset += written
+
+        return current_offset - offset
+    
+    @classmethod
+    def decode_from(cls, buffer: bytes, offset: int = 0) -> Tuple["Seq", int]:
+        current_offset = offset
+        
+        # Determine if this is variable length
+        if cls._min_length == cls._max_length:
+            # Fixed length
+            _len = cls._min_length
+        else:
+            # Variable length - decode length from buffer
+            _len, _inc_offset = Uint.decode_from(buffer, current_offset)
+            current_offset += _inc_offset
+
+        items = []
+        for _ in range(_len):
+            item, _inc_offset = cls._element_type.decode_from(buffer, current_offset)
+            current_offset += _inc_offset
+            items.append(item)
+
+        return cls(items), current_offset - offset
+
+    # ---------------------------------------------------------------------------- #
+    #                                  JSON Serde                                  #
+    # ---------------------------------------------------------------------------- #
+    def to_json(self):
+        """Convert to JSON representation."""
+        return [item.to_json() for item in self]
+
+    @classmethod
+    def from_json(cls, data):
+        """Create instance from JSON representation."""
+        if cls._element_type:
+            items = [cls._element_type.from_json(item) for item in data]
+        else:
+            items = data
+        return cls(items)
+
+
+# All params supported-
+# Union[Type, int, Tuple[Type, int], Tuple[int, int], Tuple[Type, int, int]]
+
+class Vector(Seq):
+    def __class_getitem__(cls, params: None): return super().__class_getitem__(params)
+
+class Array(Seq):
+    def __class_getitem__(cls, params: int): return super().__class_getitem__(params)
+
+class TypedArray(Seq):
+    def __class_getitem__(cls, params: Tuple[Type, int]): return super().__class_getitem__(params)
+
+class TypedVector(Seq):
+    def __class_getitem__(cls, params: Type): return super().__class_getitem__(params)
+
+class BoundedVector(Seq):
+    def __class_getitem__(cls, params: Tuple[int, int]): return super().__class_getitem__(params)
+
+class TypedBoundedVector(Seq):
+    def __class_getitem__(cls, params: Tuple[Type, int, int]): return super().__class_getitem__(params)