tsrkit-types 0.1.2__py3-none-any.whl → 0.1.3__py3-none-any.whl

tsrkit_types/__init__.py

@@ -1,76 +1,95 @@
-# from jam.types.base.integers import (
-#     U8,
-#     U16,
-#     U32,
-#     U64,
-#     U128,
-#     U256,
-#     Int,
-# )
-# from jam.types.base.string import String
-# from jam.types.base.null import Null, Nullable
-# from jam.types.base.dictionary import Dictionary, decodable_dictionary
-# from jam.types.base.boolean import Boolean
-# from jam.types.base.bit import Bit
-# from jam.types.base.composite import Choice, Option, decodable_choice, decodable_option
-# from jam.types.base.sequences.array import Array, decodable_array
-# from jam.types.base.sequences.vector import Vector, decodable_vector
-# from jam.types.base.bytes.bytes import Bytes
-# # from jam.types.base.sequences.bytes import BitArray, decodable_bit_array, Byte
-# # from jam.types.base.bytes.byte_array import (
-# #     ByteArray8,
-# #     ByteArray16,
-# #     ByteArray32,
-# #     ByteArray64,
-# #     ByteArray96,
-# #     ByteArray128,
-# #     ByteArray144,
-# #     ByteArray256,
-# #     ByteArray784,
-# # )
-#
-# __all__ = [
-#     # Integer types
-#     "Int",
-#     "U8",
-#     "U16",
-#     "U32",
-#     "U64",
-#     "U128",
-#     "U256",
-#     # Choice and Null types
-#     "Choice",
-#     "Option",
-#     "Null",
-#     "Nullable",
-#     # Dictionary type
-#     "Dictionary",
-#     # Boolean and Bit types
-#     "Boolean",
-#     "Bit",
-#     # String type
-#     "String",
-#     # Sequence types
-#     # "Array",
-#     # "Vector",
-#     # # Byte types
-#     # "ByteArray8",
-#     # "ByteArray16",
-#     # "ByteArray32",
-#     # "ByteArray64",
-#     # "ByteArray96",
-#     # "ByteArray128",
-#     # "ByteArray144",
-#     # "ByteArray256",
-#     # "ByteArray784",
-#     # "BitArray",
-#     # "Byte",
-#     "Bytes",
-#     # Decodable types
-#     "decodable_array",
-#     "decodable_bit_array",
-#     "decodable_vector",
-#     "decodable_dictionary",
-#     "decodable_choice",
-#     "decodable_option",
-# ]
+"""
+TSRKit Types - Performant Python types for binary serialization and JSON encoding.
+
+This module provides a comprehensive set of typed data structures with built-in
+serialization capabilities, including integers, strings, containers, and more.
+"""
+
+# Core interfaces
+from .itf.codable import Codable
+
+# Integer types
+from .integers import Uint, U8, U16, U32, U64
+
+# String types
+from .string import String
+
+# Boolean types
+from .bool import Bool
+
+# Null types
+from .null import Null, NullType
+
+# Choice and Option types
+from .choice import Choice
+from .option import Option
+
+# Container types
+from .sequences import (
+    Seq, Vector, Array, 
+    TypedVector, TypedArray, 
+    BoundedVector, TypedBoundedVector
+)
+
+# Dictionary types
+from .dictionary import Dictionary
+
+# Bytes types
+from .bytes import Bytes, ByteArray16, ByteArray32, ByteArray64, ByteArray128, ByteArray256, ByteArray512, ByteArray1024
+from .bytearray import ByteArray
+
+# Bit types
+from .bits import Bits
+
+# Enum types
+from .enum import Enum
+
+# Structure decorator
+from .struct import structure, struct
+
+# Export all public types
+__all__ = [
+    # Core interfaces
+    "Codable",
+    
+    # Integer types
+    "Uint", "U8", "U16", "U32", "U64",
+    
+    # String types
+    "String",
+    
+    # Boolean types
+    "Bool",
+    
+    # Null types
+    "Null", "NullType",
+    
+    # Choice and Option types
+    "Choice", "Option",
+    
+    # Container types
+    "Seq", "Vector", "Array",
+    "TypedVector", "TypedArray", 
+    "BoundedVector", "TypedBoundedVector",
+    
+    # Dictionary types
+    "Dictionary",
+    
+    # Bytes types
+    "Bytes", "ByteArray16", "ByteArray32", "ByteArray64", "ByteArray128", "ByteArray256", "ByteArray512", "ByteArray1024",
+    "ByteArray",
+    
+    # Bit types
+    "Bits",
+    
+    # Enum types
+    "Enum",
+    
+    # Structure decorator
+    "structure", "struct",
+]
+
+# Version information
+__version__ = "1.0.0"
+__author__ = "TSRKit Team"
+__license__ = "MIT"

tsrkit_types/bits.py

@@ -34,7 +34,13 @@ class Bits(Seq):
 	
 	@classmethod
 	def from_json(cls, json_str: str) -> "Bits":
-		return cls(Bytes.from_hex(json_str).to_bits(bit_order=cls._order))
+		bits = Bytes.from_json(json_str).to_bits(bit_order=cls._order)
+		
+		# For fixed-length types, trim to exact size
+		if cls._min_length == cls._max_length and cls._min_length > 0:
+			bits = bits[:cls._min_length]
+		
+		return cls(bits)
 
 	# ---------------------------------------------------------------------------- #
 	#                                 Serialization                                #
@@ -43,7 +49,9 @@ class Bits(Seq):
 	def encode_size(self) -> int:
 		# Calculate the number of bytes needed
 		bit_enc = 0
-		if self._length is None:
+		# Check if this is a variable-length type (needs length prefix)
+		is_fixed_length = (self._min_length == self._max_length and self._min_length > 0)
+		if not is_fixed_length:
 			bit_enc = Uint(len(self)).encode_size()
 
 		return bit_enc + ((len(self) + 7) // 8)
@@ -54,17 +62,18 @@ class Bits(Seq):
 		total_size = self.encode_size()
 		self._check_buffer_size(buffer, total_size, offset)
 
-		# Initialize all bytes to 0
-		for i in range(0, total_size):
-			buffer[offset + i] = 0
-
-		if self._length is None:
+		current_offset = offset
+		
+		# Check if this is a variable-length type (needs length prefix)
+		is_fixed_length = (self._min_length == self._max_length and self._min_length > 0)
+		
+		if not is_fixed_length:
 			# Encode the bit length first
-			offset += Uint(len(self)).encode_into(buffer, offset)
+			current_offset += Uint(len(self)).encode_into(buffer, current_offset)
 		else:
-			# Ensure bit length is size of value
-			if len(self) != self._length:
-				raise ValueError("Bit sequence length mismatch")
+			# Ensure bit length matches expected size for fixed-length types
+			if len(self) != self._min_length:
+				raise ValueError(f"Bit sequence length mismatch: expected {self._min_length}, got {len(self)}")
 
 		if not all(
 			isinstance(bit, (bool, int)) and bit in (0, 1, True, False)
@@ -72,9 +81,9 @@ class Bits(Seq):
 		):
 			raise ValueError(f"Bit sequence must contain only 0s and 1s, got an sequence of {self}")
 
-		buffer[offset : offset + total_size] = Bytes.from_bits(
-			self, bit_order=self._order
-		)
+		# Convert bits to bytes and write to buffer
+		bit_bytes = Bytes.from_bits(self, bit_order=self._order)
+		buffer[current_offset : current_offset + len(bit_bytes)] = bit_bytes
 
 		return total_size
 
@@ -98,18 +107,28 @@ class Bits(Seq):
 		Raises:
 			DecodeError: If buffer too small or bit_length not specified
 		"""
-		_len = cls._length
-		if _len is None:
-			# Assume first byte is the bit length
+		# Check if this is a fixed-length Bits type
+		is_fixed_length = (cls._min_length == cls._max_length and cls._min_length > 0)
+		
+		original_offset = offset
+		
+		if is_fixed_length:
+			_len = cls._min_length
+		else:
+			# Variable length - decode length from buffer
 			_len, size = Uint.decode_from(buffer, offset)
 			offset += size
 
 		if _len == 0:
-			return [], 0
+			return cls([]), offset - original_offset
 
 		# Calculate required bytes
 		byte_count = (_len + 7) // 8
 		cls._check_buffer_size(buffer, byte_count, offset)
 
-		result = Bytes(buffer[offset : offset + byte_count]).to_bits(bit_order=cls._order)
-		return cls(result), byte_count
+		result_bits = Bytes(buffer[offset : offset + byte_count]).to_bits(bit_order=cls._order)
+		# Trim to exact bit length
+		result_bits = result_bits[:_len]
+		
+		total_bytes_read = offset + byte_count - original_offset
+		return cls(result_bits), total_bytes_read

tsrkit_types/bool.py

@@ -29,13 +29,9 @@ class Bool(Codable):
     #                                  JSON Parse                                  #
     # ---------------------------------------------------------------------------- #
     
-    def to_json(self) -> str:
-        return "true" if self._value else "false"
+    def to_json(self) -> bool:
+        return bool(self)
     
     @classmethod
-    def from_json(cls, json_str: str) -> "Bool":
-        if json_str == "true":
-            return cls(True)
-        if json_str == "false":
-            return cls(False)
-        raise ValueError("Invalid JSON string for Bool")
+    def from_json(cls, data: bool) -> "Bool":
+        return cls(data)

tsrkit_types/bytearray.py

@@ -0,0 +1,37 @@
+from typing import Tuple, Union
+from tsrkit_types.integers import Uint
+from tsrkit_types.itf.codable import Codable
+from tsrkit_types.bytes_common import BytesMixin
+
+
+class ByteArray(bytearray, Codable, BytesMixin):
+    """Variable Size ByteArray"""
+
+    # Bit conversion and JSON methods inherited from BytesMixin
+    
+    # ---------------------------------------------------------------------------- #
+    #                                 Serialization                                #
+    # ---------------------------------------------------------------------------- #
+    def encode_size(self) -> int:
+        return Uint(len(self)).encode_size() + len(self)
+    
+    def encode_into(self, buf: bytearray, offset: int = 0) -> int:
+        current_offset = offset
+        _len = len(self)
+        current_offset += Uint(_len).encode_into(buf, current_offset)
+        buf[current_offset:current_offset+_len] = self
+        current_offset += _len
+        return current_offset - offset
+    
+    @classmethod
+    def decode_from(cls, buffer: Union[bytes, bytearray, memoryview], offset: int = 0) -> Tuple["ByteArray", int]:
+        current_offset = offset
+        _len, _inc_offset = Uint.decode_from(buffer, offset)
+        current_offset += _inc_offset
+        return cls(buffer[current_offset:current_offset+_len]), current_offset + _len - offset
+    
+    # ---------------------------------------------------------------------------- #
+    #                               JSON Serialization                             #
+    # ---------------------------------------------------------------------------- #
+    # JSON methods inherited from BytesMixin
+    

tsrkit_types/bytes.py

@@ -1,8 +1,19 @@
+import abc
 from typing import Tuple, Union, ClassVar
 from tsrkit_types.integers import Uint
 from tsrkit_types.itf.codable import Codable
+from tsrkit_types.bytes_common import BytesMixin
 
-class Bytes(bytes, Codable):
+class BytesCheckMeta(abc.ABCMeta):
+    """Meta class to check if the instance is a bytes with the same key and value types"""
+    def __instancecheck__(cls, instance):
+        # TODO - This needs more false positive testing
+        _matches_length = str(getattr(cls, "_length", None)) == str(getattr(instance, "_length", None))
+        return isinstance(instance, bytes) and _matches_length
+
+
+class Bytes(bytes, Codable, BytesMixin, metaclass=BytesCheckMeta):
+    """Fixed Size Bytes"""
 
     _length: ClassVar[Union[None, int]] = None
 
@@ -16,47 +27,7 @@ class Bytes(bytes, Codable):
             "_length": _len,
         })
 
-    def __str__(self):
-        return f"{self.__class__.__name__}({self.hex()})"
-
-    @classmethod
-    def from_bits(cls, bits: list[bool], bit_order = "msb") -> "Bytes":
-        # Sanitize input: make sure bits are 0 or 1
-        bits = [int(bool(b)) for b in bits]
-        n = len(bits)
-        # Pad with zeros to multiple of 8
-        pad = (8 - n % 8) % 8
-        bits += [0] * pad
-
-        byte_arr = []
-        for i in range(0, len(bits), 8):
-            byte_bits = bits[i:i + 8]
-            if bit_order == "msb":
-                # Most significant bit first
-                val = 0
-                for bit in byte_bits:
-                    val = (val << 1) | bit
-            elif bit_order == "lsb":
-                # Least significant bit first
-                val = 0
-                for bit in reversed(byte_bits):
-                    val = (val << 1) | bit
-            else:
-                raise ValueError(f"Unknown bit_order: {bit_order}")
-            # noinspection PyUnreachableCode
-            byte_arr.append(val)
-        return cls(bytes(byte_arr))
-
-    def to_bits(self, bit_order="msb") -> list[bool]:
-        bits = []
-        for byte in self:
-            if bit_order == "msb":
-                bits.extend([(byte >> i) & 1 for i in reversed(range(8))])
-            elif bit_order == "lsb":
-                bits.extend([(byte >> i) & 1 for i in range(8)])
-            else:
-                raise ValueError(f"Unknown bit_order: {bit_order}")
-        return bits
+    # Bit conversion methods inherited from BytesMixin
     
     # ---------------------------------------------------------------------------- #
     #                                 Serialization                                #
@@ -88,13 +59,12 @@ class Bytes(bytes, Codable):
     # ---------------------------------------------------------------------------- #
     #                               JSON Serialization                             #
     # ---------------------------------------------------------------------------- #
-    def to_json(self):
-        """Convert bytes to hex string for JSON serialization"""
-        return self.hex()
-    
-    @classmethod
-    def from_json(cls, data: str):
-        """Create Bytes instance from hex string"""
-        data = data.replace("0x", "")
-        return cls(bytes.fromhex(data))
-        
+    # JSON methods inherited from BytesMixin
+        
+ByteArray16 = Bytes[16]
+ByteArray32 = Bytes[32]
+ByteArray64 = Bytes[64]
+ByteArray128 = Bytes[128]
+ByteArray256 = Bytes[256]
+ByteArray512 = Bytes[512]
+ByteArray1024 = Bytes[1024]

tsrkit_types/bytes_common.py

@@ -0,0 +1,68 @@
+"""
+Common functionality for Bytes and ByteArray types.
+"""
+
+from typing import Union
+
+
+class BytesMixin:
+    """Mixin providing common functionality for bytes-like types."""
+    
+    @classmethod
+    def from_bits(cls, bits: list[bool], bit_order: str = "msb"):
+        """Convert a list of bits to bytes with specified bit order."""
+        # Sanitize input: make sure bits are 0 or 1
+        bits = [int(bool(b)) for b in bits]
+        n = len(bits)
+        # Pad with zeros to multiple of 8
+        pad = (8 - n % 8) % 8
+        bits += [0] * pad
+
+        byte_arr = []
+        for i in range(0, len(bits), 8):
+            byte_bits = bits[i:i + 8]
+            if bit_order == "msb":
+                # Most significant bit first
+                val = 0
+                for bit in byte_bits:
+                    val = (val << 1) | bit
+            elif bit_order == "lsb":
+                # Least significant bit first
+                val = 0
+                for bit in reversed(byte_bits):
+                    val = (val << 1) | bit
+            else:
+                raise ValueError(f"Unknown bit_order: {bit_order}")
+            byte_arr.append(val)
+        return cls(bytes(byte_arr))
+
+    def to_bits(self, bit_order: str = "msb") -> list[bool]:
+        """Convert bytes to a list of bits with specified bit order."""
+        bits = []
+        for byte in self:
+            if bit_order == "msb":
+                bits.extend([bool((byte >> i) & 1) for i in reversed(range(8))])
+            elif bit_order == "lsb":
+                bits.extend([bool((byte >> i) & 1) for i in range(8)])
+            else:
+                raise ValueError(f"Unknown bit_order: {bit_order}")
+        return bits
+    
+    def to_json(self):
+        """Convert bytes to hex string for JSON serialization."""
+        return self.hex()
+    
+    @classmethod
+    def from_json(cls, data: str):
+        """Create instance from hex string."""
+        data = data.replace("0x", "")
+        return cls(bytes.fromhex(data))
+    
+    def __str__(self):
+        return f"{self.__class__.__name__}({self.hex()})"
+
+
+def validate_bit_order(bit_order: str) -> None:
+    """Validate bit order parameter."""
+    if bit_order not in ("msb", "lsb"):
+        raise ValueError(f"Unknown bit_order: {bit_order}. Must be 'msb' or 'lsb'") 

tsrkit_types/choice.py

@@ -112,13 +112,13 @@ class Choice(Codable):
 
     def encode_into(self, buf: bytearray, offset: int = 0) -> int:
         current_offset = offset
-        # Find the first isinstance(self._value, type) for self._choice_types
-        for i, t in enumerate(self._choice_types):
-            if isinstance(self._value, t):
+        # Find the index of the (key, type) pair that matches our current choice
+        for i, (key, choice_type) in enumerate(self._opt_types):
+            if self._choice_key == key and isinstance(self._value, choice_type):
                 current_offset += Uint(i).encode_into(buf, current_offset)
                 break
         else:
-            raise ValueError(f"Value {self._value} is not a valid choice")
+            raise ValueError(f"Value {self._value} with key {self._choice_key} is not a valid choice")
         current_offset += self._value.encode_into(buf, current_offset)
         return current_offset - offset
 

tsrkit_types/dictionary.py

@@ -102,7 +102,7 @@ class Dictionary(dict, Codable, Generic[K, V], metaclass=DictCheckMeta):
         if not isinstance(data, dict):
             _value = cls({})
             for val in data:
-                _value[cls.key_type.from_json(val[cls.key_name])] = cls.value_type.from_json(val[cls.value_name])
+                _value[cls._key_type.from_json(val[cls._key_name])] = cls._value_type.from_json(val[cls._value_name])
             return _value
         else:
             return cls(

tsrkit_types/integers.py

@@ -195,6 +195,23 @@ class Uint(int, Codable, metaclass=IntCheckMeta):
                 beta = int.from_bytes(buffer[offset + 1 : offset + 1 + _l], "little")
                 value = alpha * 2 ** (_l * 8) + beta
                 return cls(value), _l + 1
+            
+    def to_bits(self, bit_order: str = "msb") -> list[bool]:
+        """Convert an int to bits"""
+        if bit_order == "msb":
+            return [bool((self >> i) & 1) for i in reversed(range(self.byte_size * 8 if self.byte_size > 0 else 64))]
+        elif bit_order == "lsb":
+            return [bool((self >> i) & 1) for i in range(self.byte_size * 8 if self.byte_size > 0 else 64)]
+        else:
+            raise ValueError(f"Invalid bit order: {bit_order}")
+        
+    @classmethod
+    def from_bits(cls, bits: list[bool], bit_order: str = "msb") -> "Uint":
+        """Convert bits to an int"""
+        if bit_order == "msb":
+            return cls(int("".join(str(int(b)) for b in bits), 2))
+        elif bit_order == "lsb":
+            return cls(int("".join(str(int(b)) for b in reversed(bits)), 2))
 
 
 U8 = Uint[8]

tsrkit_types/itf/codable.py

@@ -69,7 +69,8 @@ class Codable(ABC, Generic[T]):
         value, bytes_read = cls.decode_from(buffer, offset)
         return value
     
-    def _check_buffer_size(self, buffer: bytearray, size: int, offset: int) -> None:
+    @classmethod
+    def _check_buffer_size(cls, buffer: bytearray, size: int, offset: int) -> None:
         """
         Check if the buffer has enough space to encode the value.
 

tsrkit_types/option.py

@@ -16,7 +16,7 @@ class Option(Choice, Generic[T]):
         name = f"Option[{opt_t.__class__.__name__}]"
         return type(name,
                     (Option,),
-                    {"_opt_types": ((None, opt_t), (None, NullType))})
+                    {"_opt_types": ((None, NullType), (None, opt_t))})
 
     def __init__(self, val: T|NullType = Null):
         super().__init__(val)
@@ -27,4 +27,22 @@ class Option(Choice, Generic[T]):
         super().set(value, key)
 
     def __bool__(self):
-        return self._value != Null
+        return self._value != Null
+    
+    # ---------------------------------------------------------------------------- #
+    #                                  JSON Serde                                  #
+    # ---------------------------------------------------------------------------- #
+    
+    def to_json(self):
+        """Convert Option to JSON. Returns None for empty Options."""
+        if self._value == Null:
+            return None
+        return self._value.to_json()
+    
+    @classmethod
+    def from_json(cls, data):
+        """Create Option from JSON data. None creates empty Option."""
+        if data is None:
+            return cls()  # Empty Option
+        # Try to create the wrapped type from the data
+        return cls(cls._opt_types[1][1].from_json(data))

tsrkit_types/sequences.py

@@ -1,5 +1,5 @@
 import abc
-from typing import TypeVar, Type, ClassVar, Tuple, Generic
+from typing import TypeVar, Type, ClassVar, Tuple, Generic, Optional
 from tsrkit_types.integers import Uint
 from tsrkit_types.itf.codable import Codable
 
@@ -118,7 +118,7 @@ class Seq(list, Codable, Generic[T], metaclass=SeqCheckMeta):
         return f"{self.__class__.__name__}({list(self)})"
     
     @property
-    def _length(self):
+    def _length(self) -> Optional[int]:
         if self._min_length == self._max_length:
             return self._min_length
         return None
@@ -143,7 +143,7 @@ class Seq(list, Codable, Generic[T], metaclass=SeqCheckMeta):
     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)):
+        if(self._min_length != self._max_length):
             current_offset += Uint(len(self)).encode_into(buffer, current_offset)
 
         for item in self:

tsrkit_types/struct.py

@@ -1,6 +1,8 @@
 from dataclasses import dataclass, fields
 from typing import Any, Tuple, Union
 from tsrkit_types.itf.codable import Codable
+from tsrkit_types.null import NullType
+from tsrkit_types.option import Option
 
 
 def structure(_cls=None, *, frozen=False, **kwargs):
@@ -58,22 +60,26 @@ def structure(_cls=None, *, frozen=False, **kwargs):
             for field in fields(cls):
                 k = field.metadata.get("name", field.name)
                 v = data.get(k)
-                if v is None:
-                    if field.metadata.get("default") is not None:
-                        init_data[field.name] = field.metadata.get("default")
-                    else:
-                        raise ValueError(f"Field {k} not found in {cls}")
+                if v is None and field.metadata.get("default") is not None:
+                    init_data[field.name] = field.metadata.get("default")
                 else:
                     init_data[field.name] = field.type.from_json(v)
             return cls(**init_data)
 
 
         new_cls.__init__ = __init__
-        new_cls.encode_size = encode_size
-        new_cls.decode_from = decode_from
-        new_cls.encode_into = encode_into
-        new_cls.to_json = to_json
-        new_cls.from_json = from_json
+
+        # Only overwrite if the method is not already defined
+        if not new_cls.__dict__.get("encode_size"):
+            new_cls.encode_size = encode_size
+        if not new_cls.__dict__.get("decode_from"):
+            new_cls.decode_from = decode_from
+        if not new_cls.__dict__.get("encode_into"):
+            new_cls.encode_into = encode_into
+        if not new_cls.__dict__.get("to_json"):
+            new_cls.to_json = to_json
+        if not new_cls.__dict__.get("from_json"):
+            new_cls.from_json = from_json
 
         new_cls = type(new_cls.__name__, (Codable, new_cls), dict(new_cls.__dict__))
 

{tsrkit_types-0.1.2.dist-info → tsrkit_types-0.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tsrkit-types
-Version: 0.1.2
+Version: 0.1.3
 Summary: Performant Python Typings library for type-safe binary serialization, JSON encoding, and data validation with zero dependencies
 Author-email: chainscore-labs <hello@chainscore.finance>, prasad-kumkar <prasad@chainscore.finance>
 License-Expression: MIT
@@ -299,7 +299,9 @@ restored = StringToInt.from_json(json_data)
 
 ### Bytes Types
 
-#### Bytes (extension of Python in-built bytes)
+The library provides two complementary byte array types: immutable `Bytes` (extending Python's built-in `bytes`) and mutable `ByteArray` (extending Python's `bytearray`). Both types share common functionality through a mixin architecture for bit conversion, JSON serialization, and binary encoding.
+
+#### Bytes (Immutable - extension of Python bytes)
 
 ```python
 from tsrkit_types.bytes import Bytes
@@ -307,47 +309,115 @@ from tsrkit_types.bytes import Bytes
 # Creation
 data = Bytes(b"Hello, binary world!")
 data = Bytes([0x01, 0x02, 0x03, 0x04])
+data = Bytes("48656c6c6f")        # From hex string
 
-# Bytes <-> Bits Operations
-data.to_bits()          # [True, False, True, ...]
-Bytes.from_bits([True, False, True, ...])
+# Shared Operations (via BytesMixin)
+bits = data.to_bits()            # Convert to bit list [True, False, True, ...]
+data2 = Bytes.from_bits(bits)    # Create from bit list
 
-# Operations
+# Properties
 length = len(data)               # Byte length
 raw_bytes = bytes(data)         # Convert to Python bytes
 
-# Encoding
+# Encoding/Decoding
 encoded = data.encode()          # [length][raw_bytes]
 decoded = Bytes.decode(encoded)
 
 # JSON serialization (hex encoded)
 json_str = data.to_json()        # "48656c6c6f2c2062696e61727920776f726c6421"
 restored = Bytes.from_json(json_str)
+restored2 = Bytes.from_json("0x48656c6c6f")  # Supports 0x prefix
 ```
 
-#### Bit Arrays (Sequence of bool)
+#### ByteArray (Mutable - extension of Python bytearray)
 
 ```python
-from tsrkit_types.bits import BitArray
+from tsrkit_types.bytearray import ByteArray
 
 # Creation
-bits = BitArray([True, False, True, True, False])
-bits = BitArray.from_hex("1A3F")    # From hex string
-bits = BitArray.from_int(42, 8)     # From integer with bit width
+data = ByteArray(b"Hello, binary world!")
+data = ByteArray([0x01, 0x02, 0x03, 0x04])
+data = ByteArray("48656c6c6f")   # From hex string
+
+# Mutable Operations
+data.append(0xFF)                # Add single byte
+data.extend([0xAB, 0xCD])       # Add multiple bytes
+data.insert(0, 0x00)            # Insert byte at position
+data.pop()                      # Remove and return last byte
+data.remove(0xFF)               # Remove first occurrence
+data.clear()                    # Remove all bytes
+data.reverse()                  # Reverse in-place
+
+# Indexing and Slicing (mutable)
+data[0] = 0x42                  # Set byte at index
+data[1:3] = [0x43, 0x44]       # Set slice
+del data[0]                     # Delete byte at index
+
+# Shared Operations (via BytesMixin) - same as Bytes
+bits = data.to_bits()           # Convert to bit list
+data2 = ByteArray.from_bits(bits)  # Create from bit list
+
+# Properties and Conversion
+length = len(data)              # Byte length  
+raw_bytes = bytes(data)         # Convert to immutable bytes
+immutable = Bytes(data)         # Convert to immutable Bytes
+
+# Encoding/Decoding (same interface as Bytes)
+encoded = data.encode()         # [length][raw_bytes]
+decoded = ByteArray.decode(encoded)
+
+# JSON serialization (same interface as Bytes)
+json_str = data.to_json()       # "48656c6c6f..."
+restored = ByteArray.from_json(json_str)
+```
+
+**Key Differences:**
+- **Bytes**: Immutable, extends `bytes`, memory-efficient for read-only data
+- **ByteArray**: Mutable, extends `bytearray`, suitable for dynamic byte manipulation
+- **Shared Functionality**: Both support identical bit conversion, JSON serialization, and binary encoding through `BytesMixin`
+
+**Common Features (Both Types):**
+- Bit-level conversion with MSB/LSB support
+- Hex string JSON serialization with 0x prefix support
+- Efficient binary encoding with length prefix
+- String representation and validation
+- Memory-efficient operations
+
+#### Bits (Bit Arrays - Sequence of bool)
+
+```python
+from tsrkit_types.bits import Bits
+
+# Creation
+bits = Bits([True, False, True, True, False])
+bits = Bits.from_hex("1A3F")       # From hex string
+bits = Bits.from_int(42, 8)        # From integer with bit width
+
+# Fixed-size parameterized bits
+FixedBits = Bits[8]                # Exactly 8 bits
+fixed = FixedBits([True, False, True, True, False, False, True, False])
 
 # Operations
-bit_val = bits[0]                # Get bit at index
-bits[1] = True                   # Set bit at index
-bits.append(False)               # Add bit
-bits.extend([True, False])       # Add multiple bits
+bit_val = bits[0]                  # Get bit at index
+bits[1] = True                     # Set bit at index
+bits.append(False)                 # Add bit
+bits.extend([True, False])         # Add multiple bits
 
 # Conversion
-hex_str = bits.to_hex()          # Convert to hex string
-int_val = bits.to_int()          # Convert to integer
+hex_str = bits.to_hex()            # Convert to hex string
+int_val = bits.to_int()            # Convert to integer
+
+# Bit order specification
+bits_msb = Bits([True, False], bit_order="MSB")  # Most significant bit first
+bits_lsb = Bits([True, False], bit_order="LSB")  # Least significant bit first
 
 # Encoding
-encoded = bits.encode()          # [length][packed_bits]
-decoded = BitArray.decode(encoded)
+encoded = bits.encode()            # [length][packed_bits]
+decoded = Bits.decode(encoded)
+
+# JSON serialization
+json_str = bits.to_json()          # Hex string representation
+restored = Bits.from_json(json_str)
 ```
 
 ### Enum (Extension of Python Enum, with Codable + JSON support)
@@ -558,6 +628,16 @@ buffer = bytearray(1024)
 offset = 0
 offset += value1.encode_into(buffer, offset)
 offset += value2.encode_into(buffer, offset)
+
+# Choose appropriate byte type for your use case
+# Use Bytes for immutable binary data (memory efficient, read-only)
+config_data = Bytes(b"static configuration")
+
+# Use ByteArray for dynamic binary buffers (mutable, growing data)
+dynamic_buffer = ByteArray()
+dynamic_buffer.extend([0x01, 0x02])
+dynamic_buffer.append(0x03)
+dynamic_buffer.insert(0, 0x00)  # Result: [0x00, 0x01, 0x02, 0x03]
 ```
 
 ## Examples

tsrkit_types-0.1.3.dist-info/RECORD

@@ -0,0 +1,21 @@
+tsrkit_types/__init__.py,sha256=dPiakZ3q_YZLcj3nW5CLjI8CA9rE8umqtv2camWl3Cs,1956
+tsrkit_types/bits.py,sha256=33WLfuUYdzGscoc-E3InTYdbJRIDeixoe_pG0XAv71c,4213
+tsrkit_types/bool.py,sha256=Veu6KLIeiRFnIW1sbawJ0haF0veyaL-As5mBiypq-uE,1280
+tsrkit_types/bytearray.py,sha256=DaMnACq-7pzEW-pRO2f_IAny_8ldhSt3G5D24Soywk4,1662
+tsrkit_types/bytes.py,sha256=ayuD8AUTbZ4LFnceG8TBzAGAYXGht0pYQcmX-7ZtwyI,2762
+tsrkit_types/bytes_common.py,sha256=b1Zqh_NhkCX718QaZC52J3nEzKAi1Fe8E0nefWVwwmo,2301
+tsrkit_types/choice.py,sha256=zNLvB1jSZERot6Qo9cxxkPcY84DAJss8o0ULyp9D--4,5196
+tsrkit_types/dictionary.py,sha256=GcUvaHC1VOEc3OzUVAH0id--ncLqTJ6ZRz-lucMNRdY,5618
+tsrkit_types/enum.py,sha256=3MyLW15_ToQQdctJjcMY8Xb3OsS_Ad997OOEo8FjVeA,4256
+tsrkit_types/integers.py,sha256=w8WCbzzQP0YX3ky4iP-fbNeOBHsIydsU0Tady8iGQPQ,8026
+tsrkit_types/null.py,sha256=OwHVhWLdazaFLXXR8iHPaHe67NPmYHDCavBxUfcZ53s,1318
+tsrkit_types/option.py,sha256=xwtaAFN20GjaGqzYZAAo1fZqqUZnCYHdy2bjshhY620,1631
+tsrkit_types/sequences.py,sha256=KOT5-4mia5Lc0CMjIF7Yqe34Sei92ZQ2s6GaP13soUg,8090
+tsrkit_types/string.py,sha256=8rvg0BwvyhQnbMW3qornmBFTQHeTQFUfwD7OC0eVgcY,2575
+tsrkit_types/struct.py,sha256=GoXWFc1OqO9CXnxFS7Xkms7J-rtZe8h32LkAIBlzdSM,3497
+tsrkit_types/itf/codable.py,sha256=agx8YSVWGBeEiLrU9eqh3ZoeTgpJsmmIlW622xIKqPI,2810
+tsrkit_types-0.1.3.dist-info/licenses/LICENSE,sha256=TwnDvVCPwHadHWLUuY1sPx03XNw1jzh_ZmoDBNai9Uc,1072
+tsrkit_types-0.1.3.dist-info/METADATA,sha256=W_kNQJPjZnMV4wh3tqG7ggWcec8tL1d6gLWx2K4jvVM,22755
+tsrkit_types-0.1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+tsrkit_types-0.1.3.dist-info/top_level.txt,sha256=pnVhnUsnZ_A0FIj1zHwDw3suMGrfMJwusp-4GPVY1CM,13
+tsrkit_types-0.1.3.dist-info/RECORD,,

tsrkit_types-0.1.2.dist-info/RECORD

@@ -1,19 +0,0 @@
-tsrkit_types/__init__.py,sha256=Vw03Fv9RnfmZGqzBpFhuglyewh4MxKR8T5bdWdal1VU,1870
-tsrkit_types/bits.py,sha256=ggx2lDRWtBBIYQBtKEx-XirwYTJdajctCEpd3VmuXrc,3275
-tsrkit_types/bool.py,sha256=anu5RquxV8xdDMj7aIwOOCP3WnK6vMNst4WUPlfeKm4,1460
-tsrkit_types/bytes.py,sha256=rw0sjw1fO9bOElftWehs8oLCZFMXWeajjCyOH-5kChU,3756
-tsrkit_types/choice.py,sha256=L4Pb0ZBvaoCW2h9VBLclmmgIJvfO0Yeb2khPniFN2Xo,5113
-tsrkit_types/dictionary.py,sha256=EktyMKH27HVoR1xNhrkV8fW6KfcxpbHiiYPYoCrFdoI,5614
-tsrkit_types/enum.py,sha256=3MyLW15_ToQQdctJjcMY8Xb3OsS_Ad997OOEo8FjVeA,4256
-tsrkit_types/integers.py,sha256=GT9xVZYBNMcPpShJIlSazwiZYGhoBowhR0MA_cGO5Q0,7200
-tsrkit_types/null.py,sha256=OwHVhWLdazaFLXXR8iHPaHe67NPmYHDCavBxUfcZ53s,1318
-tsrkit_types/option.py,sha256=V4J8SmhUDjINqMM6Ml3ho0YwTy2UT-avrjoYh32Swyg,879
-tsrkit_types/sequences.py,sha256=6aseAdoAkD3RG20ag6CTzVZPR_YlJfLHo82JrNZY3dE,8092
-tsrkit_types/string.py,sha256=8rvg0BwvyhQnbMW3qornmBFTQHeTQFUfwD7OC0eVgcY,2575
-tsrkit_types/struct.py,sha256=ni8jwZlfT_wehardfImBJ0AsvnO-oCW-3APplLXsqGY,3206
-tsrkit_types/itf/codable.py,sha256=jWfoYZ31MZ6k3nlHb2IwJdjD3G0pVPyZWlF0Sv9MAWs,2794
-tsrkit_types-0.1.2.dist-info/licenses/LICENSE,sha256=TwnDvVCPwHadHWLUuY1sPx03XNw1jzh_ZmoDBNai9Uc,1072
-tsrkit_types-0.1.2.dist-info/METADATA,sha256=Yt9wxA4VDq7jhjzPGrrpcQ4rhjgMUQN3hoTl9rjT3ec,19353
-tsrkit_types-0.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-tsrkit_types-0.1.2.dist-info/top_level.txt,sha256=pnVhnUsnZ_A0FIj1zHwDw3suMGrfMJwusp-4GPVY1CM,13
-tsrkit_types-0.1.2.dist-info/RECORD,,