bytespec 0.1.0__py3-none-any.whl

bytespec/codecs/model.py

@@ -0,0 +1,40 @@
+# Copyright (c) 2026 ink-developer
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from typing_extensions import override
+
+from bytespec.codecs import ICodec
+from bytespec.enums import ByteOrder
+
+if TYPE_CHECKING:
+    from bytespec.core import ProtoModel
+    from bytespec.enums import ByteOrder
+
+
+class ModelCodec(ICodec["ProtoModel"]):
+    """A nested model with its own framing, excluding Constructor, and its own byte order.
+
+    Args:
+        model_type: The concrete class to read via decode_from(). Subclasses are not selected
+            automatically by constructor.
+    """
+
+    def __init__(self, model_type: type[ProtoModel]) -> None:
+        self.model_type = model_type
+
+    @override
+    def encode(self, value: ProtoModel, _: ByteOrder) -> bytes:
+        """Write value using its own settings, skipping Constructor elements."""
+        return value.encode(include_constructor=False)
+
+    @override
+    def decode(self, buffer: bytes, byte_order: ByteOrder, offset: int) -> tuple[ProtoModel, int]:
+        """Read model_type and return the instance with its absolute end offset.
+
+        The outer byte_order is ignored: model_type settings are used. Errors propagate from
+        model_type.decode_from().
+        """
+        return self.model_type.decode_from(buffer, offset, expect_constructor=False)

bytespec/codecs/str.py

@@ -0,0 +1,88 @@
+# Copyright (c) 2026 ink-developer
+
+import codecs
+
+from typing_extensions import override
+
+from bytespec.codecs import ICodec
+from bytespec.enums import ByteOrder
+from bytespec.errors import DecodeError, EncodeError, SchemaError
+from bytespec.models import PrefixLength
+
+from ._utils import check_available
+from .map import UINT_CODEC_MAPPING
+
+
+class StrCodec(ICodec[str]):
+    """Text prefixed with the length in encoded bytes, not characters.
+
+    Args:
+        prefix_length: Prefix size: 1, 2, 4, or 8 bytes, or ``VarUInt``. Defaults to 4 bytes.
+        encoding: Python encoding, UTF-8 by default.
+
+    Raises:
+        SchemaError: Unsupported prefix or unknown encoding.
+    """
+
+    def __init__(self, prefix_length: PrefixLength = 4, encoding: str = "utf-8") -> None:
+        self.prefix_length = prefix_length
+        self.encoding = encoding
+
+        try:
+            codecs.lookup(encoding)
+        except LookupError as exc:
+            raise SchemaError(f"StrCodec: invalid encoding {encoding!r}") from exc
+
+        codec = UINT_CODEC_MAPPING.get(prefix_length)
+        if codec is None:
+            raise SchemaError(f"StrCodec: invalid length prefix {prefix_length!r}")
+
+        self.codec = codec
+
+        super().__init__()
+
+    @override
+    def encode(self, value: str, byte_order: ByteOrder) -> bytes:
+        """Encode text and prefix it with its byte length.
+
+        Raises:
+            EncodeError: The text cannot be represented in the encoding, or its length does not fit
+                in the prefix.
+            SchemaError: The selected Python codec is not a text encoding.
+        """
+        try:
+            encoded = value.encode(self.encoding)
+        except UnicodeError as exc:
+            raise EncodeError(f"StrCodec ({self.encoding}): cannot encode {value!r}") from exc
+        except LookupError as exc:
+            raise SchemaError(f"StrCodec: invalid text encoding {self.encoding!r}") from exc
+        return self.codec.encode(len(encoded), byte_order) + encoded
+
+    @override
+    def decode(
+        self,
+        buffer: bytes,
+        byte_order: ByteOrder,
+        offset: int,
+    ) -> tuple[str, int]:
+        """Read a string and return it with its absolute end offset.
+
+        Raises:
+            DecodeError: There are not enough bytes, or the prefix or text is invalid.
+            SchemaError: The selected Python codec is not a text encoding.
+            ValueError: Negative offset.
+        """
+        length, start = self.codec.decode(buffer, byte_order, offset)
+        end = start + length
+
+        check_available(buffer, start, length, codec=type(self).__name__)
+
+        try:
+            value = buffer[start:end].decode(self.encoding)
+        except UnicodeError as exc:
+            raise DecodeError(
+                f"StrCodec ({self.encoding}) at offset {start}: invalid string bytes"
+            ) from exc
+        except LookupError as exc:
+            raise SchemaError(f"StrCodec: invalid text encoding {self.encoding!r}") from exc
+        return value, end

bytespec/codecs/uuid.py

@@ -0,0 +1,36 @@
+# Copyright (c) 2026 ink-developer
+
+from uuid import UUID
+
+from typing_extensions import override
+
+from bytespec.codecs import ICodec
+from bytespec.enums import ByteOrder
+
+from .bytes import FixedBytesCodec
+
+
+class UUIDCodec(ICodec[UUID]):
+    """A UUID as exactly 16 bytes from UUID.bytes, without a length prefix.
+
+    The model's byte order does not switch this representation to bytes_le.
+    """
+
+    def __init__(self) -> None:
+        self.codec = FixedBytesCodec(length=16)
+
+    @override
+    def encode(self, value: UUID, byte_order: ByteOrder) -> bytes:
+        """Return the 16 bytes of value.bytes regardless of byte_order."""
+        return self.codec.encode(value.bytes, byte_order)
+
+    @override
+    def decode(self, buffer: bytes, byte_order: ByteOrder, offset: int) -> tuple[UUID, int]:
+        """Read a UUID and return it with the position offset + 16.
+
+        Raises:
+            DecodeError: There are not enough bytes for a UUID.
+            ValueError: Negative offset.
+        """
+        value, offset = self.codec.decode(buffer, byte_order, offset)
+        return UUID(bytes=value), offset

bytespec/codecs/varint.py

@@ -0,0 +1,122 @@
+# Copyright (c) 2026 ink-developer
+
+from typing_extensions import override
+
+from bytespec.enums import ByteOrder
+from bytespec.errors import DecodeError, EncodeError
+
+from ._utils import check_available
+from .base import ICodec
+
+
+class VarUIntCodec(ICodec[int]):
+    """Canonical unsigned varint: 0 .. 2**64 - 1, 1 to 10 bytes.
+
+    Groups of 7 bits are written starting with the least significant. The model's byte order does
+    not affect this representation.
+    """
+
+    @override
+    def encode(self, value: int, _: ByteOrder) -> bytes:
+        """Write a nonnegative integer in canonical varint form.
+
+        Raises:
+            EncodeError: The value is outside the UInt64 range.
+        """
+        if value < 0:
+            raise EncodeError(f"VarUIntCodec cannot encode negative value {value}")
+
+        if value > 2**64 - 1:
+            raise EncodeError(f"VarUIntCodec overflow: {value}")
+
+        result = bytearray()
+
+        while True:
+            byte = value & 0x7F
+            value >>= 7
+
+            if value:
+                byte |= 0x80
+
+            result.append(byte)
+
+            if not value:
+                break
+
+        return bytes(result)
+
+    @override
+    def decode(self, buffer: bytes, _: ByteOrder, offset: int) -> tuple[int, int]:
+        """Read a varint and return the number with its absolute end offset.
+
+        Raises:
+            DecodeError: The varint is truncated, overflows, or is not in canonical form.
+            ValueError: Negative offset.
+        """
+        value = 0
+        count = 0
+        shift = 0
+
+        while True:
+            check_available(buffer, offset, 1, codec=type(self).__name__)
+
+            byte = buffer[offset]
+            offset += 1
+            count += 1
+
+            if count == 10:
+                if byte & 0x80:
+                    raise DecodeError(f"VarUIntCodec at offset {offset - 1}: varint is too long")
+
+                if byte & 0x7F > 1:
+                    raise DecodeError(
+                        f"VarUIntCodec at offset {offset - 1}: overflow byte {byte:#x}"
+                    )
+
+            data = byte & 0x7F
+            value |= data << shift
+
+            if not byte & 0x80:
+                if count > 1 and data == 0:
+                    raise DecodeError(f"VarUIntCodec at offset {offset - 1}: non-canonical varint")
+
+                break
+
+            shift += 7
+
+        return value, offset
+
+
+class VarIntCodec(VarUIntCodec):
+    """Signed varint: ZigZag + unsigned varint in the Int64 range.
+
+    Uses 1–10 bytes regardless of the model's byte order.
+    """
+
+    @override
+    def encode(self, value: int, _: ByteOrder) -> bytes:
+        """Apply ZigZag and write the integer as an unsigned varint.
+
+        Raises:
+            EncodeError: The value is outside the range -2**63 .. 2**63 - 1.
+        """
+        if value >= 0:
+            value *= 2
+        else:
+            value = abs(value) * 2 - 1
+
+        return super().encode(value, _)
+
+    @override
+    def decode(self, buffer: bytes, _: ByteOrder, offset: int) -> tuple[int, int]:
+        """Read a ZigZag varint and return the number with its absolute end offset.
+
+        Raises:
+            DecodeError: The varint is truncated, overflows, or is not in canonical form.
+            ValueError: Negative offset.
+        """
+        encoded, offset = super().decode(buffer, _, offset)
+
+        value = encoded // 2 if encoded & 1 == 0 else -(encoded // 2) - 1
+
+        return value, offset