bytespec 0.1.0__py3-none-any.whl

bytespec/__init__.py

@@ -0,0 +1,21 @@
+# Copyright (c) 2026 ink-developer
+
+__version__ = "0.1.0"
+
+from .core import ProtoModel, field
+from .enums import ByteOrder
+from .errors import BytespecError, DecodeError, EncodeError, SchemaError
+from .headers import Constructor, Flags, PayloadLength
+
+__all__ = [
+    "ByteOrder",
+    "BytespecError",
+    "Constructor",
+    "DecodeError",
+    "EncodeError",
+    "Flags",
+    "PayloadLength",
+    "ProtoModel",
+    "SchemaError",
+    "field",
+]

bytespec/base.py

@@ -0,0 +1,52 @@
+# Copyright (c) 2026 ink-developer
+
+from types import NoneType, UnionType
+from typing import Annotated, Any, ClassVar, Final, Union, get_args, get_origin
+
+from bytespec.enums import ByteOrder
+from bytespec.headers import Constructor, Flags, HeaderElement, PayloadLength
+from bytespec.resolvers import CodecFactory
+from bytespec.schema import ModelSchema
+
+DEFAULT_HEADER: Final[tuple[HeaderElement, ...]] = (Constructor(2), Flags(8), PayloadLength(4))
+
+
+class ProtoModelBase:
+    __constructor__: int = 0x1
+    __byte_order__: ByteOrder = ByteOrder.BIG
+    __header__: ClassVar[tuple[HeaderElement, ...]] = DEFAULT_HEADER
+    __schema__: ModelSchema
+
+    @classmethod
+    def _is_valid_value(cls, value: Any, annotation: Any) -> bool:
+        origin = get_origin(annotation)
+
+        if origin is Annotated:
+            base_type, *_ = get_args(annotation)
+            return cls._is_valid_value(value, base_type)
+
+        if origin in (Union, UnionType):
+            return any(
+                (arg is NoneType and value is None)
+                or (arg is not NoneType and cls._is_valid_value(value, arg))
+                for arg in get_args(annotation)
+            )
+
+        if origin is list:
+            return isinstance(value, list)
+
+        return isinstance(value, annotation)
+
+    @classmethod
+    def configure_codecs(cls) -> dict[type, CodecFactory]:
+        """Define additional codec selection rules for field types.
+
+        Override this classmethod in the model. Rules apply at class declaration, extending
+        inherited rules and replacing matching keys.
+
+        Returns:
+            A mapping from Python types to codec factories. A factory receives the annotation and
+            ``FieldInfo`` and returns a ready-to-use codec instance. There are no additional rules
+            by default.
+        """
+        return {}

bytespec/codecs/__init__.py

@@ -0,0 +1,48 @@
+# Copyright (c) 2026 ink-developer
+
+from .base import ICodec
+from .bool import BoolCodec
+from .bytes import BytesCodec, FixedBytesCodec
+from .datetime import DatetimeCodec
+from .enum import EnumCodec
+from .float import Float32Codec, Float64Codec
+from .int import (
+    Int8Codec,
+    Int16Codec,
+    Int32Codec,
+    Int64Codec,
+    UInt8Codec,
+    UInt16Codec,
+    UInt32Codec,
+    UInt64Codec,
+)
+from .list import ListCodec
+from .model import ModelCodec
+from .str import StrCodec
+from .uuid import UUIDCodec
+from .varint import VarIntCodec, VarUIntCodec
+
+__all__ = [
+    "BoolCodec",
+    "BytesCodec",
+    "DatetimeCodec",
+    "EnumCodec",
+    "FixedBytesCodec",
+    "Float32Codec",
+    "Float64Codec",
+    "ICodec",
+    "Int8Codec",
+    "Int16Codec",
+    "Int32Codec",
+    "Int64Codec",
+    "ListCodec",
+    "ModelCodec",
+    "StrCodec",
+    "UInt8Codec",
+    "UInt16Codec",
+    "UInt32Codec",
+    "UInt64Codec",
+    "UUIDCodec",
+    "VarIntCodec",
+    "VarUIntCodec",
+]

bytespec/codecs/_utils.py

@@ -0,0 +1,16 @@
+# Copyright (c) 2026 ink-developer
+
+from bytespec.errors import DecodeError
+
+
+def check_available(buffer: bytes, offset: int, size: int, *, codec: str) -> None:
+    if offset < 0:
+        raise ValueError(f"offset must be non-negative, got {offset}")
+    if size < 0:
+        raise ValueError(f"size must be non-negative, got {size}")
+
+    available = max(0, len(buffer) - offset)
+    if available < size:
+        raise DecodeError(
+            f"{codec} at offset {offset}: expected {size} bytes, available {available}"
+        )

bytespec/codecs/base.py

@@ -0,0 +1,60 @@
+# Copyright (c) 2026 ink-developer
+
+from typing import Any, Generic, Protocol, TypeVar
+
+from typing_extensions import runtime_checkable
+
+from bytespec.enums import ByteOrder
+
+T = TypeVar("T")
+
+
+@runtime_checkable
+class ICodec(Protocol, Generic[T]):
+    """Interface for writing and reading a single value of type T.
+
+    An instance can be passed to ``field(codec=...)``. Inheriting from ICodec is optional: encode
+    and decode methods that follow this contract are sufficient. A codec can be reused; the read
+    position is passed through offset.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__()
+
+    def encode(self, value: T, byte_order: ByteOrder, /) -> bytes:
+        """Write a single value in the selected representation.
+
+        Args:
+            value: The value to write.
+            byte_order: The byte order of fixed-width numbers and prefixes.
+
+        Returns:
+            The binary representation of the value.
+
+        Raises:
+            EncodeError: The value cannot be represented. A custom codec must raise this error
+                itself for data errors.
+        """
+        ...
+
+    def decode(self, buffer: bytes, byte_order: ByteOrder, offset: int, /) -> tuple[T, int]:
+        """Read a single value starting at offset.
+
+        Args:
+            buffer: The buffer containing the encoded value.
+            byte_order: The byte order of fixed-width numbers and prefixes.
+            offset: The nonnegative absolute position where the value starts.
+
+        Returns:
+            The value and the absolute position after it in the same buffer. The remaining bytes do
+            not have to be consumed.
+
+        Raises:
+            DecodeError: There are not enough bytes, or the value is invalid. The implementation
+                must check bounds and contents itself.
+
+        Note:
+            A list item codec must advance offset by a positive number of bytes while staying within
+            the supplied buffer.
+        """
+        ...

bytespec/codecs/bool.py

@@ -0,0 +1,45 @@
+# Copyright (c) 2026 ink-developer
+
+import struct
+
+from typing_extensions import override
+
+from bytespec.codecs import ICodec
+from bytespec.enums import ByteOrder
+from bytespec.errors import DecodeError
+
+from ._utils import check_available
+
+
+class BoolCodec(ICodec[bool]):
+    """A Boolean value in one byte: 0 or 1."""
+
+    @override
+    def encode(
+        self,
+        value: bool,
+        byte_order: ByteOrder,
+    ) -> bytes:
+        """Write the truth value of value as 0/1 without strict type checking."""
+        return struct.pack(byte_order.value + "B", 1 if value else 0)
+
+    @override
+    def decode(
+        self,
+        buffer: bytes,
+        byte_order: ByteOrder,
+        offset: int,
+    ) -> tuple[bool, int]:
+        """Read a bool and return it with its absolute end offset.
+
+        Raises:
+            DecodeError: The byte is missing or is neither 0 nor 1.
+            ValueError: Negative offset.
+        """
+        check_available(buffer, offset, 1, codec=type(self).__name__)
+        value = struct.unpack_from(byte_order.value + "B", buffer, offset)[0]
+
+        if value not in (0, 1):
+            raise DecodeError(f"BoolCodec at offset {offset}: invalid bool value {value}")
+
+        return bool(value), offset + 1

bytespec/codecs/bytes.py

@@ -0,0 +1,105 @@
+# Copyright (c) 2026 ink-developer
+
+from typing_extensions import override
+
+from bytespec.codecs import ICodec
+from bytespec.enums import ByteOrder
+from bytespec.errors import EncodeError, SchemaError
+from bytespec.models import PrefixLength
+
+from ._utils import check_available
+from .map import UINT_CODEC_MAPPING
+
+
+class BytesCodec(ICodec[bytes]):
+    """Bytes prefixed with their length.
+
+    Args:
+        prefix_length: Prefix size: 1, 2, 4, or 8 bytes, or ``VarUInt``. Defaults to 4 bytes. The
+            prefix itself is not included in the stored length.
+
+    Raises:
+        SchemaError: Unsupported prefix, including ``VarInt``.
+    """
+
+    def __init__(self, prefix_length: PrefixLength = 4) -> None:
+        self.prefix_length = prefix_length
+
+        codec = UINT_CODEC_MAPPING.get(prefix_length)
+        if codec is None:
+            raise SchemaError(f"BytesCodec: invalid length prefix {prefix_length!r}")
+
+        self.codec = codec
+
+        super().__init__()
+
+    @override
+    def encode(self, value: bytes, byte_order: ByteOrder) -> bytes:
+        """Write the length of value followed by the bytes themselves.
+
+        Raises:
+            EncodeError: The length does not fit in the selected prefix.
+        """
+        return self.codec.encode(len(value), byte_order) + value
+
+    @override
+    def decode(self, buffer: bytes, byte_order: ByteOrder, offset: int) -> tuple[bytes, int]:
+        """Read the prefix and return the bytes with their absolute end offset.
+
+        Raises:
+            DecodeError: The prefix or declared data is incomplete or invalid.
+            ValueError: Negative offset.
+        """
+        length, start = self.codec.decode(buffer, byte_order, offset)
+        end = start + length
+
+        check_available(buffer, start, length, codec=type(self).__name__)
+
+        return buffer[start:end], end
+
+
+class FixedBytesCodec(BytesCodec):
+    """Exactly length bytes without a length prefix.
+
+    Args:
+        length: The nonnegative fixed size of the value.
+
+    Raises:
+        SchemaError: Negative length.
+    """
+
+    def __init__(self, length: int) -> None:
+        if length < 0:
+            raise SchemaError(f"FixedBytesCodec: length must be non-negative, got {length}")
+        self.length = length
+
+    @override
+    def encode(self, value: bytes, byte_order: ByteOrder) -> bytes:
+        """Return value after checking its length; byte order has no effect.
+
+        Raises:
+            EncodeError: The size of value is not equal to length.
+        """
+        if len(value) != self.length:
+            raise EncodeError(f"FixedBytesCodec: expected {self.length} bytes, got {len(value)}")
+
+        return value
+
+    @override
+    def decode(
+        self,
+        buffer: bytes,
+        byte_order: ByteOrder,
+        offset: int,
+    ) -> tuple[bytes, int]:
+        """Read length bytes and return them with their absolute end offset.
+
+        Raises:
+            DecodeError: There are not enough bytes.
+            ValueError: Negative offset.
+        """
+        end = offset + self.length
+
+        check_available(buffer, offset, self.length, codec=type(self).__name__)
+
+        return buffer[offset:end], end

bytespec/codecs/datetime.py

@@ -0,0 +1,59 @@
+# Copyright (c) 2026 ink-developer
+
+from datetime import datetime
+
+from typing_extensions import override
+
+from bytespec.codecs import ICodec
+from bytespec.enums import ByteOrder
+from bytespec.errors import DecodeError
+from bytespec.models import PrefixLength
+
+from .str import StrCodec
+
+
+class DatetimeCodec(ICodec[datetime]):
+    """A datetime as a length-prefixed ISO 8601 string.
+
+    Preserves the UTC offset from isoformat(), but not the time zone name. A datetime without tzinfo
+    remains naive after reading.
+
+    Args:
+        prefix_length: Prefix size: 1, 2, 4, or 8 bytes, or ``VarUInt``.
+        encoding: Encoding of the ISO string, UTF-8 by default.
+
+    Raises:
+        SchemaError: Unsupported prefix or unknown encoding.
+    """
+
+    def __init__(self, prefix_length: PrefixLength = 4, encoding: str = "utf-8") -> None:
+        self.codec = StrCodec(prefix_length, encoding=encoding)
+
+    @override
+    def encode(self, value: datetime, byte_order: ByteOrder) -> bytes:
+        """Write value.isoformat() as a length-prefixed string.
+
+        Raises:
+            EncodeError: The string cannot be represented in the encoding, or its length does not
+                fit in the prefix.
+            SchemaError: The selected codec is not a text encoding.
+        """
+        return self.codec.encode(value.isoformat(), byte_order)
+
+    @override
+    def decode(self, buffer: bytes, byte_order: ByteOrder, offset: int) -> tuple[datetime, int]:
+        """Restore a datetime and return it with its absolute end offset.
+
+        Raises:
+            DecodeError: There are not enough bytes, or the string or ISO date is invalid.
+            SchemaError: The selected codec is not a text encoding.
+            ValueError: Negative offset.
+        """
+        value, end = self.codec.decode(buffer, byte_order, offset)
+        try:
+            decoded = datetime.fromisoformat(value)
+        except ValueError as exc:
+            raise DecodeError(
+                f"DatetimeCodec at offset {offset}: invalid datetime {value!r}"
+            ) from exc
+        return decoded, end

bytespec/codecs/enum.py

@@ -0,0 +1,49 @@
+# Copyright (c) 2026 ink-developer
+
+from enum import Enum
+from typing import Any
+
+from typing_extensions import override
+
+from bytespec.codecs import ICodec
+from bytespec.enums import ByteOrder
+from bytespec.errors import DecodeError
+
+
+class EnumCodec(ICodec[Enum]):
+    """An enum encoded using a codec for its value.
+
+    Args:
+        enum_type: The enum class used to reconstruct members via enum_type(value).
+        value_codec: The codec for .value, such as StrCodec or UInt8Codec.
+    """
+
+    def __init__(
+        self,
+        enum_type: type[Enum],
+        value_codec: ICodec[Any],
+    ) -> None:
+        self.enum_type = enum_type
+        self.value_codec = value_codec
+
+    @override
+    def encode(self, value: Enum, byte_order: ByteOrder) -> bytes:
+        """Write value.value using the selected value codec."""
+        return self.value_codec.encode(value.value, byte_order)
+
+    @override
+    def decode(self, buffer: bytes, byte_order: ByteOrder, offset: int) -> tuple[Enum, int]:
+        """Read an enum member and return it with its absolute end offset.
+
+        Raises:
+            DecodeError: The decoded value is not an enum member, or the value codec rejected the
+                data.
+        """
+        value, end = self.value_codec.decode(buffer, byte_order, offset)
+        try:
+            decoded = self.enum_type(value)
+        except ValueError as exc:
+            raise DecodeError(
+                f"EnumCodec ({self.enum_type.__name__}) at offset {offset}: invalid value {value!r}"
+            ) from exc
+        return decoded, end

bytespec/codecs/float.py

@@ -0,0 +1,17 @@
+# Copyright (c) 2026 ink-developer
+
+from .int import IntegerCodec
+
+
+class Float32Codec(IntegerCodec[float]):
+    """IEEE 754 binary32: four bytes, rounding the Python float."""
+
+    def __init__(self, struct_format: str = "f", length: int = 4) -> None:
+        super().__init__(struct_format, length)
+
+
+class Float64Codec(Float32Codec):
+    """IEEE 754 binary64: eight bytes in the model's byte order."""
+
+    def __init__(self, struct_format: str = "d", length: int = 8) -> None:
+        super().__init__(struct_format, length)

bytespec/codecs/int.py

@@ -0,0 +1,118 @@
+# Copyright (c) 2026 ink-developer
+
+import struct
+from typing import Generic, TypeVar
+
+from typing_extensions import override
+
+from bytespec.codecs import ICodec
+from bytespec.enums import ByteOrder
+from bytespec.errors import EncodeError, SchemaError
+
+from ._utils import check_available
+
+T = TypeVar("T")
+
+
+class IntegerCodec(ICodec[T], Generic[T]):
+    def __init__(self, struct_format: str, length: int) -> None:
+        try:
+            struct.calcsize(ByteOrder.BIG.value + struct_format)
+        except struct.error as exc:
+            raise SchemaError(
+                f"{type(self).__name__}: invalid struct format {struct_format!r}"
+            ) from exc
+        self.struct_format = struct_format
+        self.length = length
+
+    @override
+    def encode(
+        self,
+        value: T,
+        byte_order: ByteOrder,
+    ) -> bytes:
+        """Write a fixed-width number in the specified byte order.
+
+        Raises:
+            EncodeError: The value cannot be packed in the selected numeric format.
+        """
+        try:
+            return struct.pack(byte_order.value + self.struct_format, value)
+        except (struct.error, OverflowError) as exc:
+            raise EncodeError(
+                f"{type(self).__name__} ({self.struct_format}): cannot encode {value!r}"
+            ) from exc
+
+    @override
+    def decode(
+        self,
+        buffer: bytes,
+        byte_order: ByteOrder,
+        offset: int,
+    ) -> tuple[T, int]:
+        """Read a number and return it with its absolute end offset.
+
+        Raises:
+            DecodeError: There are not enough bytes for the number.
+            ValueError: Negative offset.
+        """
+        size = struct.calcsize(byte_order.value + self.struct_format)
+        check_available(buffer, offset, size, codec=type(self).__name__)
+        value = struct.unpack_from(byte_order.value + self.struct_format, buffer, offset)[0]
+        return value, offset + self.length
+
+
+class UInt8Codec(IntegerCodec[int]):
+    """Unsigned 8-bit integer: 0–255, one byte by default."""
+
+    def __init__(self, struct_format: str = "B", length: int = 1) -> None:
+        super().__init__(struct_format, length)
+
+
+class Int8Codec(UInt8Codec):
+    """Signed 8-bit integer: -128–127, one byte by default."""
+
+    def __init__(self, struct_format: str = "b", length: int = 1) -> None:
+        super().__init__(struct_format, length)
+
+
+class UInt16Codec(IntegerCodec[int]):
+    """Unsigned 16-bit integer: 0–65535, two bytes by default."""
+
+    def __init__(self, struct_format: str = "H", length: int = 2) -> None:
+        super().__init__(struct_format, length)
+
+
+class Int16Codec(UInt16Codec):
+    """Signed 16-bit integer: -32768–32767, two bytes by default."""
+
+    def __init__(self, struct_format: str = "h", length: int = 2) -> None:
+        super().__init__(struct_format, length)
+
+
+class UInt32Codec(IntegerCodec[int]):
+    """Unsigned 32-bit integer: 0 .. 2**32 - 1, four bytes."""
+
+    def __init__(self, struct_format: str = "I", length: int = 4) -> None:
+        super().__init__(struct_format, length)
+
+
+class Int32Codec(UInt32Codec):
+    """Signed 32-bit integer: -2**31 .. 2**31 - 1, four bytes."""
+
+    def __init__(self, struct_format: str = "i", length: int = 4) -> None:
+        super().__init__(struct_format, length)
+
+
+class UInt64Codec(IntegerCodec[int]):
+    """Unsigned 64-bit integer: 0 .. 2**64 - 1, eight bytes."""
+
+    def __init__(self, struct_format: str = "Q", length: int = 8) -> None:
+        super().__init__(struct_format, length)
+
+
+class Int64Codec(UInt64Codec):
+    """Signed 64-bit integer: -2**63 .. 2**63 - 1, eight bytes."""
+
+    def __init__(self, struct_format: str = "q", length: int = 8) -> None:
+        super().__init__(struct_format, length)

bytespec/codecs/list.py

@@ -0,0 +1,77 @@
+# Copyright (c) 2026 ink-developer
+
+from typing import Any
+
+from typing_extensions import override
+
+from bytespec.codecs import ICodec
+from bytespec.enums import ByteOrder
+from bytespec.errors import SchemaError
+from bytespec.models import PrefixLength
+
+from ._utils import check_available
+from .map import UINT_CODEC_MAPPING
+
+
+class ListCodec(ICodec[list[Any]]):
+    """A list prefixed with the total size of its encoded items in bytes.
+
+    Args:
+        item_codec: The codec for a single item. When reading, it must advance offset by a positive
+            number of bytes within the supplied buffer.
+        prefix_length: Prefix size: 1, 2, 4, or 8 bytes, or ``VarUInt``. Defaults to 4 bytes. The
+            prefix does not store the item count.
+
+    Raises:
+        SchemaError: Unsupported length prefix.
+    """
+
+    def __init__(self, item_codec: ICodec[Any], prefix_length: PrefixLength = 4) -> None:
+        self.item_codec = item_codec
+        self.prefix_length = prefix_length
+
+        codec = UINT_CODEC_MAPPING.get(prefix_length)
+        if codec is None:
+            raise SchemaError(f"ListCodec: invalid length prefix {prefix_length!r}")
+
+        self.codec = codec
+
+    @override
+    def encode(self, data: list[Any], byte_order: ByteOrder) -> bytes:
+        """Write consecutive items prefixed with their total byte length.
+
+        Raises:
+            EncodeError: The size does not fit in the prefix, or an item cannot be encoded by the
+                selected codec.
+        """
+        payload = bytearray()
+
+        for value in data:
+            payload.extend(self.item_codec.encode(value, byte_order))
+
+        return self.codec.encode(len(payload), byte_order) + payload
+
+    @override
+    def decode(self, buffer: bytes, byte_order: ByteOrder, offset: int) -> tuple[list[Any], int]:
+        """Read a list and return it with its absolute end offset.
+
+        Items are read from a separate buffer containing the list contents; offsets in their errors
+        refer to that buffer.
+
+        Raises:
+            DecodeError: The prefix or data is incomplete, or the item codec rejected the data.
+            ValueError: Negative offset.
+        """
+        length, start = self.codec.decode(buffer, byte_order, offset)
+        end = start + length
+
+        check_available(buffer, start, length, codec=type(self).__name__)
+
+        values = buffer[start:end]
+        data = []
+        item_offset = 0
+        while item_offset < len(values):
+            value, item_offset = self.item_codec.decode(values, byte_order, item_offset)
+            data.append(value)
+
+        return data, end

bytespec/codecs/map.py

@@ -0,0 +1,17 @@
+# Copyright (c) 2026 ink-developer
+
+from typing import Annotated, Any
+
+from bytespec.codecs.base import ICodec
+from bytespec.codecs.varint import VarUIntCodec
+from bytespec.types import VarUInt
+
+from .int import UInt8Codec, UInt16Codec, UInt32Codec, UInt64Codec
+
+UINT_CODEC_MAPPING: dict[int | Annotated[Any, Any], ICodec[Any]] = {
+    1: UInt8Codec(),
+    2: UInt16Codec(),
+    4: UInt32Codec(),
+    8: UInt64Codec(),
+    VarUInt: VarUIntCodec(),
+}