rombob 1.0.0__py3-none-any.whl

rombob/__init__.py

@@ -0,0 +1,153 @@
+"""rombob: binary serialization using type hints and annotations."""
+
+from .aliases import F16_B as F16_B
+from .aliases import F16_L as F16_L
+from .aliases import F32_B as F32_B
+from .aliases import F32_L as F32_L
+from .aliases import F64_B as F64_B
+from .aliases import F64_L as F64_L
+from .aliases import I8_B as I8_B
+from .aliases import I8_L as I8_L
+from .aliases import I16_B as I16_B
+from .aliases import I16_L as I16_L
+from .aliases import I24_B as I24_B
+from .aliases import I24_L as I24_L
+from .aliases import I32_B as I32_B
+from .aliases import I32_L as I32_L
+from .aliases import I48_B as I48_B
+from .aliases import I48_L as I48_L
+from .aliases import I64_B as I64_B
+from .aliases import I64_L as I64_L
+from .aliases import U8_B as U8_B
+from .aliases import U8_L as U8_L
+from .aliases import U16_B as U16_B
+from .aliases import U16_L as U16_L
+from .aliases import U24_B as U24_B
+from .aliases import U24_L as U24_L
+from .aliases import U32_B as U32_B
+from .aliases import U32_L as U32_L
+from .aliases import U48_B as U48_B
+from .aliases import U48_L as U48_L
+from .aliases import U64_B as U64_B
+from .aliases import U64_L as U64_L
+from .aliases import IVInt as IVInt
+from .aliases import Raw as Raw
+from .aliases import UVInt as UVInt
+from .buffers import Reader as Reader
+from .buffers import Writer as Writer
+from .codecs import BytesCodec as BytesCodec
+from .codecs import Codec as Codec
+from .codecs import CollectionCodec as CollectionCodec
+from .codecs import EnumCodec as EnumCodec
+from .codecs import IntCodec as IntCodec
+from .codecs import LiteralCodec as LiteralCodec
+from .codecs import NamedCodec as NamedCodec
+from .codecs import OptionalCodec as OptionalCodec
+from .codecs import RawCodec as RawCodec
+from .codecs import RefLenCodec as RefLenCodec
+from .codecs import StringCodec as StringCodec
+from .codecs import StructCodec as StructCodec
+from .codecs import ValidatorCodec as ValidatorCodec
+from .codecs import VarIntCodec as VarIntCodec
+from .compiler import ClassCodec as ClassCodec
+from .compiler import DynamicSegment as DynamicSegment
+from .compiler import OptionalSegment as OptionalSegment
+from .compiler import StructSegment as StructSegment
+from .errors import BytesOperationError as BytesOperationError
+from .factory import Factory as Factory
+from .factory import decode as decode
+from .factory import encode as encode
+from .metadata import Ge as Ge
+from .metadata import Gt as Gt
+from .metadata import Le as Le
+from .metadata import Len as Len
+from .metadata import Lt as Lt
+from .metadata import Named as Named
+from .metadata import Predicate as Predicate
+from .metadata import Prefix as Prefix
+from .metadata import Range as Range
+from .metadata import Skip as Skip
+from .metadata import When as When
+from .parser import get_codec as get_codec
+from .typing import BE as BE
+from .typing import LE as LE
+from .typing import Args as Args
+from .typing import ByteOrder as ByteOrder
+from .typing import ParserContext as ParserContext
+
+__all__ = [
+    "Named",
+    "Skip",
+    "Len",
+    "Prefix",
+    "Gt",
+    "Ge",
+    "Lt",
+    "Le",
+    "Range",
+    "Predicate",
+    "When",
+    "RefLenCodec",
+    "BytesOperationError",
+    "Reader",
+    "Writer",
+    "ByteOrder",
+    "LE",
+    "BE",
+    "Codec",
+    "StructCodec",
+    "IntCodec",
+    "VarIntCodec",
+    "StringCodec",
+    "BytesCodec",
+    "CollectionCodec",
+    "RawCodec",
+    "OptionalCodec",
+    "ValidatorCodec",
+    "EnumCodec",
+    "Factory",
+    "LiteralCodec",
+    "NamedCodec",
+    "ClassCodec",
+    "StructSegment",
+    "DynamicSegment",
+    "OptionalSegment",
+    "I8_L",
+    "I8_B",
+    "U8_L",
+    "U8_B",
+    "I16_L",
+    "I16_B",
+    "U16_L",
+    "U16_B",
+    "I24_L",
+    "I24_B",
+    "U24_L",
+    "U24_B",
+    "I32_L",
+    "I32_B",
+    "U32_L",
+    "U32_B",
+    "I48_L",
+    "I48_B",
+    "U48_L",
+    "U48_B",
+    "I64_L",
+    "I64_B",
+    "U64_L",
+    "U64_B",
+    "F16_L",
+    "F16_B",
+    "F32_L",
+    "F32_B",
+    "F64_L",
+    "F64_B",
+    "IVInt",
+    "UVInt",
+    "Raw",
+    "ParserContext",
+    "Args",
+    "get_codec",
+    "encode",
+    "decode",
+]

rombob/aliases.py

@@ -0,0 +1,42 @@
+"""
+Public `Annotated` aliases for the common binary types.
+"""
+
+import typing as t
+
+from .codecs import IntCodec, RawCodec, StructCodec, VarIntCodec
+from .typing import BE, LE
+
+I8_L = t.Annotated[int, StructCodec("<b")]
+I8_B = t.Annotated[int, StructCodec(">b")]
+U8_L = t.Annotated[int, StructCodec("<B")]
+U8_B = t.Annotated[int, StructCodec(">B")]
+I16_L = t.Annotated[int, StructCodec("<h")]
+I16_B = t.Annotated[int, StructCodec(">h")]
+U16_L = t.Annotated[int, StructCodec("<H")]
+U16_B = t.Annotated[int, StructCodec(">H")]
+I24_L = t.Annotated[int, IntCodec(length=3, byteorder=LE, signed=True)]
+I24_B = t.Annotated[int, IntCodec(length=3, byteorder=BE, signed=True)]
+U24_L = t.Annotated[int, IntCodec(length=3, byteorder=LE, signed=False)]
+U24_B = t.Annotated[int, IntCodec(length=3, byteorder=BE, signed=False)]
+I32_L = t.Annotated[int, StructCodec("<i")]
+I32_B = t.Annotated[int, StructCodec(">i")]
+U32_L = t.Annotated[int, StructCodec("<I")]
+U32_B = t.Annotated[int, StructCodec(">I")]
+I48_L = t.Annotated[int, IntCodec(length=6, byteorder=LE, signed=True)]
+I48_B = t.Annotated[int, IntCodec(length=6, byteorder=BE, signed=True)]
+U48_L = t.Annotated[int, IntCodec(length=6, byteorder=LE, signed=False)]
+U48_B = t.Annotated[int, IntCodec(length=6, byteorder=BE, signed=False)]
+I64_L = t.Annotated[int, StructCodec("<q")]
+I64_B = t.Annotated[int, StructCodec(">q")]
+U64_L = t.Annotated[int, StructCodec("<Q")]
+U64_B = t.Annotated[int, StructCodec(">Q")]
+F16_L = t.Annotated[float, StructCodec("<e")]
+F16_B = t.Annotated[float, StructCodec(">e")]
+F32_L = t.Annotated[float, StructCodec("<f")]
+F32_B = t.Annotated[float, StructCodec(">f")]
+F64_L = t.Annotated[float, StructCodec("<d")]
+F64_B = t.Annotated[float, StructCodec(">d")]
+IVInt = t.Annotated[int, VarIntCodec(signed=True)]
+UVInt = t.Annotated[int, VarIntCodec(signed=False)]
+Raw = t.Annotated[bytes, RawCodec()]

rombob/buffers.py

@@ -0,0 +1,109 @@
+import struct as s
+import typing as t
+
+from .errors import BytesOperationError
+from .typing import Buffer
+
+
+class Reader:
+    """
+    Cursor over an input buffer.
+
+    The reader never slices-and-reassigns the buffer: the position is the
+    `offset` only. All values handed out by codecs are copies.
+    """
+
+    __slots__ = ("view", "offset", "data")
+
+    def __init__(
+        self,
+        data: Buffer,
+        offset: int = 0,
+        shared: dict[str, t.Any] | None = None,
+    ) -> None:
+        view = memoryview(data)
+        if view.format != "B" or view.ndim != 1:
+            view = view.cast("B")
+        self.view = view
+        self.offset = offset
+        self.data: dict[str, t.Any] = {} if shared is None else shared
+
+    def __repr__(self) -> str:
+        return f"Reader(offset={self.offset}, size={len(self.view)})"
+
+    @property
+    def remaining(self) -> int:
+        return len(self.view) - self.offset
+
+    def take(self, n: int) -> memoryview:
+        "Return a view of the next n bytes and advance"
+        start = self.offset
+        end = start + n
+        if n < 0 or end > len(self.view):
+            raise BytesOperationError(
+                f"Not enough data: need {n} bytes at offset {start}, "
+                f"only {len(self.view) - start} left"
+            )
+        self.offset = end
+        return self.view[start:end]
+
+    def peek(self, n: int, skip: int = 0) -> memoryview:
+        "Return a view of n bytes starting `skip` bytes ahead, don't advance"
+        start = self.offset + skip
+        end = start + n
+        if n < 0 or skip < 0 or end > len(self.view):
+            raise BytesOperationError(
+                f"Not enough data: need {n} bytes at offset {start}, "
+                f"only {max(len(self.view) - start, 0)} left"
+            )
+        return self.view[start:end]
+
+    def rest(self) -> bytes:
+        "Copy of everything left; advances to the end"
+        rv = bytes(self.view[self.offset :])
+        self.offset = len(self.view)
+        return rv
+
+    def unpack(self, st: s.Struct) -> tuple:
+        rv = st.unpack_from(self.view, self.offset)
+        self.offset += st.size
+        return rv
+
+    def to_writer(self) -> "Writer":
+        return Writer(shared=self.data)
+
+    def release(self) -> None:
+        try:
+            self.view.release()
+        except BufferError:
+            pass
+
+
+class Writer:
+    "Append-only output buffer. `buffer` is always a bytearray."
+
+    __slots__ = ("buffer", "data")
+
+    def __init__(
+        self,
+        buffer: bytearray | None = None,
+        shared: dict[str, t.Any] | None = None,
+    ) -> None:
+        self.buffer = bytearray() if buffer is None else buffer
+        self.data: dict[str, t.Any] = {} if shared is None else shared
+
+    def __repr__(self) -> str:
+        return f"Writer(length={len(self.buffer)})"
+
+    def write(self, b: Buffer) -> None:
+        self.buffer += b
+
+    def pack(self, st: s.Struct, *values: t.Any) -> None:
+        self.buffer += st.pack(*values)
+
+    def getvalue(self) -> bytes:
+        return bytes(self.buffer)
+
+    def to_reader(self) -> Reader:
+        "Reader over a snapshot of the buffer, sharing `data`"
+        return Reader(bytes(self.buffer), shared=self.data)