serial-toolkit 0.1.2__py3-none-any.whl

serialkit/framing.py

@@ -0,0 +1,195 @@
+"""serialkit.framing: split a byte stream into protocol frames.
+
+A :class:`Framer` is a small stateful object owned by the runtime for the
+lifetime of one connection. It buffers incoming bytes and yields complete
+frames. On unrecoverable garbage it raises :class:`ResyncError` (carrying any
+frames it managed to complete first); the runtime — never the framer — calls
+:meth:`Framer.reset` to recover.
+
+Three general framers are provided:
+
+- :class:`DelimiterFramer` — frames terminated by a delimiter (anthem ``;``,
+  newline-terminated ASCII protocols).
+- :class:`RegexResyncFramer` — frames located by a regex, so leading garbage
+  between matches is skipped (LG's ``x``-terminator, where the terminator can
+  also appear inside a command).
+- :class:`LengthPrefixedFramer` — a fixed-size header whose payload length is
+  derived from the header bytes.
+
+A protocol the general framers can't express (e.g. sony's checksum-
+discriminated short-ack vs long frame) ships its own :class:`Framer`.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from typing import Protocol, runtime_checkable
+
+from .errors import ResyncError
+
+
+@runtime_checkable
+class Framer(Protocol):
+    """Turns a byte stream into frames; one instance per connection."""
+
+    def feed(self, data: bytes) -> list[bytes]:
+        """Buffer ``data`` and return every complete frame now available.
+
+        Raises :class:`ResyncError` (with ``frames=`` for anything completed
+        before the desync) when the buffer is unrecoverable.
+        """
+        ...
+
+    def reset(self) -> None:
+        """Drop residual buffer (reconnect / desync recovery)."""
+        ...
+
+
+class DelimiterFramer:
+    """Splits a byte stream into frames on a delimiter.
+
+    - ``strip`` bytes (default NUL) are scrubbed from *incoming* data before
+      buffering, so NUL glue between/inside frames never reaches a frame.
+    - Residual (undelimited) data larger than ``max_frame``, or a single
+      delimited frame larger than ``max_frame``, raises :class:`ResyncError`.
+      The buffer is left intact; the caller must call :meth:`reset` to recover.
+    """
+
+    def __init__(
+        self,
+        delimiter: bytes,
+        *,
+        strip: bytes = b"\x00",
+        max_frame: int = 4096,
+    ) -> None:
+        if not delimiter:
+            raise ValueError("delimiter must be non-empty")
+        self._delimiter = delimiter
+        self._strip = strip
+        self._max_frame = max_frame
+        self._buffer = bytearray()
+
+    def feed(self, data: bytes) -> list[bytes]:
+        if self._strip:
+            data = bytes(data).translate(None, delete=self._strip)
+        self._buffer += data
+        frames: list[bytes] = []
+        while True:
+            idx = self._buffer.find(self._delimiter)
+            if idx < 0:
+                break
+            if idx > self._max_frame:
+                raise ResyncError(
+                    f"frame of {idx} bytes exceeds max_frame={self._max_frame}",
+                    frames=frames,
+                )
+            frame = bytes(self._buffer[:idx])
+            del self._buffer[: idx + len(self._delimiter)]
+            if frame:  # skip empty frames (e.g. doubled delimiters)
+                frames.append(frame)
+        if len(self._buffer) > self._max_frame:
+            raise ResyncError(
+                f"residual of {len(self._buffer)} bytes exceeds "
+                f"max_frame={self._max_frame} with no delimiter",
+                frames=frames,
+            )
+        return frames
+
+    def reset(self) -> None:
+        self._buffer.clear()
+
+
+class RegexResyncFramer:
+    """Locates complete frames with a regex, skipping garbage between matches.
+
+    The pattern must match a whole frame; ``feed`` returns the captured group
+    (group 1 if the pattern has one, else the whole match) for each match, and
+    discards everything up to the end of the last match. Bytes before the
+    first match are dropped — this is the resync behaviour (LG's read loop
+    finds ``...x``-terminated responses even when framing noise precedes them).
+
+    Residual larger than ``max_frame`` with no match raises
+    :class:`ResyncError`.
+    """
+
+    def __init__(
+        self,
+        pattern: bytes | re.Pattern[bytes],
+        *,
+        strip: bytes = b"",
+        max_frame: int = 4096,
+    ) -> None:
+        self._pattern = re.compile(pattern) if isinstance(pattern, bytes) else pattern
+        self._strip = strip
+        self._max_frame = max_frame
+        self._buffer = bytearray()
+
+    def feed(self, data: bytes) -> list[bytes]:
+        if self._strip:
+            data = bytes(data).translate(None, delete=self._strip)
+        self._buffer += data
+        frames: list[bytes] = []
+        end = 0
+        for match in self._pattern.finditer(bytes(self._buffer)):
+            frames.append(match.group(1) if match.groups() else match.group(0))
+            end = match.end()
+        if end:
+            del self._buffer[:end]
+        if len(self._buffer) > self._max_frame:
+            raise ResyncError(
+                f"residual of {len(self._buffer)} bytes exceeds "
+                f"max_frame={self._max_frame} with no frame match",
+                frames=frames,
+            )
+        return frames
+
+    def reset(self) -> None:
+        self._buffer.clear()
+
+
+class LengthPrefixedFramer:
+    """Frames whose payload length is encoded in a fixed-size header.
+
+    The frame on the wire is ``header + payload``; ``length_of(header)``
+    returns the payload byte count. ``feed`` yields ``header + payload`` for
+    each complete frame (the header is preserved — most protocols checksum or
+    address on it). A declared payload length larger than ``max_frame`` raises
+    :class:`ResyncError`.
+    """
+
+    def __init__(
+        self,
+        header_size: int,
+        length_of: "Callable[[bytes], int]",
+        *,
+        max_frame: int = 4096,
+    ) -> None:
+        if header_size < 1:
+            raise ValueError("header_size must be >= 1")
+        self._header_size = header_size
+        self._length_of = length_of
+        self._max_frame = max_frame
+        self._buffer = bytearray()
+
+    def feed(self, data: bytes) -> list[bytes]:
+        self._buffer += data
+        frames: list[bytes] = []
+        while len(self._buffer) >= self._header_size:
+            header = bytes(self._buffer[: self._header_size])
+            payload_len = self._length_of(header)
+            if payload_len > self._max_frame:
+                raise ResyncError(
+                    f"declared payload of {payload_len} bytes exceeds "
+                    f"max_frame={self._max_frame}",
+                    frames=frames,
+                )
+            total = self._header_size + payload_len
+            if len(self._buffer) < total:
+                break
+            frames.append(bytes(self._buffer[:total]))
+            del self._buffer[:total]
+        return frames
+
+    def reset(self) -> None:
+        self._buffer.clear()

serialkit/pacing.py

@@ -0,0 +1,93 @@
+"""serialkit.pacing: centrally enforced minimum spacing between sends."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
+from contextlib import asynccontextmanager
+
+
+class Pacing:
+    """Minimum spacing between sends, enforced in a locked send path.
+
+    Interval semantics (settle-after): the interval selected for a frame is
+    the minimum delay *after that frame is sent* before the next send may go
+    out (a power-on command needs settle time after it). Selection order:
+    per-send ``pace`` override > longest matching ``per_command`` prefix >
+    ``min_interval``.
+
+    A chained command (e.g. ``b"PW?;MV?"``) sent as one frame passes through
+    :meth:`send_slot` once and is therefore one pacing unit — it inherits the
+    interval of whichever prefix it starts with.
+
+    ``time_func``/``sleep_func`` are injectable for deterministic tests.
+    """
+
+    def __init__(
+        self,
+        min_interval: float = 0.0,
+        per_command: Mapping[bytes, float] | None = None,
+        *,
+        time_func: Callable[[], float] | None = None,
+        sleep_func: Callable[[float], Awaitable[None]] | None = None,
+    ) -> None:
+        self._min_interval = min_interval
+        self._per_command = dict(per_command or {})
+        self._time_func = time_func
+        self._sleep_func = sleep_func
+        self._sleep = sleep_func or asyncio.sleep
+        self._lock = asyncio.Lock()
+        self._next_allowed = float("-inf")
+
+    def clone(self) -> Pacing:
+        """A fresh Pacing with the same config but its own lock and clock.
+
+        Used by :class:`SerialDevice` so a ``Pacing`` declared as a class
+        attribute is never shared (its lock and next-allowed timestamp) across
+        instances or event loops.
+        """
+        return Pacing(
+            self._min_interval,
+            self._per_command,
+            time_func=self._time_func,
+            sleep_func=self._sleep_func,
+        )
+
+    def interval_for(self, frame: bytes, *, pace: float | None = None) -> float:
+        """Interval to hold after ``frame`` before the next send."""
+        if pace is not None:
+            return pace
+        best: float | None = None
+        best_len = -1
+        for prefix, interval in self._per_command.items():
+            if frame.startswith(prefix) and len(prefix) > best_len:
+                best, best_len = interval, len(prefix)
+        return self._min_interval if best is None else best
+
+    @asynccontextmanager
+    async def send_slot(
+        self, frame: bytes, *, pace: float | None = None
+    ) -> AsyncIterator[None]:
+        """Locked send path: delay until pacing allows, the caller writes
+        inside the ``with`` body, then the frame's settle interval is recorded
+        for the next sender.
+
+        The settle interval is recorded whether or not the caller actually
+        wrote (an abandoned paced write still reserves the slot — conservative
+        and harmless).
+        """
+        async with self._lock:
+            now = self._now()
+            if self._next_allowed > now:
+                await self._sleep(self._next_allowed - now)
+            try:
+                yield
+            finally:
+                self._next_allowed = self._now() + self.interval_for(
+                    frame, pace=pace
+                )
+
+    def _now(self) -> float:
+        if self._time_func is not None:
+            return self._time_func()
+        return asyncio.get_running_loop().time()

serialkit/testing.py

@@ -0,0 +1,165 @@
+"""serialkit.testing: in-memory transport doubles for driver tests.
+
+Replaces the hand-rolled ``MockSerialConnection`` each device library ships.
+Nothing here touches real hardware:
+
+- :class:`FakeLink` is an injected ``connect`` factory (pass ``link.connect``
+  to a :class:`~serialkit.SerialDevice`). It hands out a fresh reader/writer
+  pair per connection, records every written frame, scripts device responses,
+  and injects desync faults (dropped connection, garbled bytes).
+- :class:`FakeClock` makes :class:`~serialkit.Pacing` deterministic by
+  advancing a virtual clock on ``sleep`` instead of waiting.
+
+Typical driver test::
+
+    link = FakeLink()
+    link.respond({b"POW?\\r": b"POW1\\r"})   # script an answer
+    dev = MyDevice(link.connect)
+    await dev.start()
+    assert await dev.query_power() is PowerState.ON
+    assert link.sent == [b"POW?\\r"]
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Mapping
+
+
+class FakeClock:
+    """Deterministic clock: ``sleep`` advances virtual time instead of waiting.
+
+    Wire it into :class:`~serialkit.Pacing` with
+    ``Pacing(..., time_func=clock.time, sleep_func=clock.sleep)``.
+    """
+
+    def __init__(self) -> None:
+        self.now = 0.0
+        self.sleeps: list[float] = []
+
+    def time(self) -> float:
+        return self.now
+
+    async def sleep(self, delay: float) -> None:
+        self.sleeps.append(delay)
+        self.now += delay
+
+
+class FakeReader:
+    """Duck-typed ``StreamReader``: ``read()`` pops injected chunks; ``b""``
+    signals EOF."""
+
+    def __init__(self) -> None:
+        self._chunks: asyncio.Queue[bytes] = asyncio.Queue()
+
+    def feed(self, data: bytes) -> None:
+        self._chunks.put_nowait(bytes(data))
+
+    def feed_eof(self) -> None:
+        self._chunks.put_nowait(b"")
+
+    async def read(self, _n: int = -1) -> bytes:
+        return await self._chunks.get()
+
+
+class FakeWriter:
+    """Duck-typed ``StreamWriter``: records writes, with an optional
+    ``on_write`` hook used to script synchronous device responses."""
+
+    def __init__(
+        self, on_write: Callable[[bytes], None] | None = None
+    ) -> None:
+        self.written: list[bytes] = []
+        self.drains = 0
+        self.closed = False
+        self._on_write = on_write
+
+    def write(self, data: bytes) -> None:
+        if self.closed:
+            raise RuntimeError("write to closed writer")
+        self.written.append(bytes(data))
+        if self._on_write is not None:
+            self._on_write(bytes(data))
+
+    async def drain(self) -> None:
+        self.drains += 1
+
+    def close(self) -> None:
+        self.closed = True
+
+
+class FakeLink:
+    """Injected async connect factory: a fresh reader/writer per call.
+
+    - ``preload``: chunks pre-queued on every new reader (unsolicited data
+      already on the wire when the connection opens).
+    - ``on_write`` / :meth:`respond`: script device responses to written
+      frames (echo transports).
+    - :meth:`rx` / :meth:`garble` / :meth:`drop`: inject received bytes, a
+      corrupt burst, or a connection loss for desync/reconnect tests.
+    """
+
+    def __init__(self, *, preload: list[bytes] | None = None) -> None:
+        self.connects = 0
+        self.readers: list[FakeReader] = []
+        self.writers: list[FakeWriter] = []
+        self.on_write: Callable[[bytes], None] | None = None
+        self._preload = list(preload or [])
+
+    async def connect(self) -> tuple[FakeReader, FakeWriter]:
+        self.connects += 1
+        reader = FakeReader()
+        for chunk in self._preload:
+            reader.feed(chunk)
+        writer = FakeWriter(self._dispatch_write)
+        self.readers.append(reader)
+        self.writers.append(writer)
+        return reader, writer
+
+    def respond(self, answers: Mapping[bytes, bytes]) -> None:
+        """Script exact ``command -> response`` echoes.
+
+        Installs an ``on_write`` hook that feeds ``answers[frame]`` back on the
+        current reader whenever a written frame matches a key exactly. Replaces
+        the per-test echo closures with a declarative table.
+        """
+        table = dict(answers)
+
+        def _echo(data: bytes) -> None:
+            response = table.get(data)
+            if response is not None:
+                self.rx(response)
+
+        self.on_write = _echo
+
+    def _dispatch_write(self, data: bytes) -> None:
+        if self.on_write is not None:
+            self.on_write(data)
+
+    @property
+    def reader(self) -> FakeReader:
+        return self.readers[-1]
+
+    @property
+    def writer(self) -> FakeWriter:
+        return self.writers[-1]
+
+    @property
+    def sent(self) -> list[bytes]:
+        """Frames written on the CURRENT connection."""
+        return self.writers[-1].written
+
+    def rx(self, data: bytes) -> None:
+        """Inject received bytes on the current connection."""
+        self.readers[-1].feed(data)
+
+    def garble(self, data: bytes = b"\xff\xff\xff\xff") -> None:
+        """Inject a corrupt byte burst (desync / resync tests)."""
+        self.rx(data)
+
+    def drop(self) -> None:
+        """Simulate the device/link going away (EOF -> reconnect)."""
+        self.readers[-1].feed_eof()
+
+
+__all__ = ["FakeClock", "FakeLink", "FakeReader", "FakeWriter"]