serialforge 0.0.1__py3-none-any.whl

serialforge/connection/response_parser.py

@@ -0,0 +1,92 @@
+"""Parse command responses and device events into declared data shapes."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import fields, is_dataclass
+from enum import Enum
+from typing import Any, get_type_hints
+
+from ..errors import CommandError
+from ..models import CommandSpec, EventSpec
+
+
+# Parsing branches correspond to the public result data-shape table.
+# pylint: disable=too-few-public-methods
+class ResponseParser:
+    """Apply a declaration's pattern and optional result conversion."""
+
+    # Each shape returns its own data type or a contextual conversion error.
+    # pylint: disable=too-many-branches,too-many-return-statements
+    @staticmethod
+    def match(spec: CommandSpec | EventSpec, text: str) -> tuple[bool, Any]:
+        """Return whether a frame matches and its parsed data.
+
+        Args:
+            spec: Original immutable declaration.
+            text: A complete decoded frame without framing bytes.
+
+        Returns:
+            A match flag and data, or ``(False, None)``.
+
+        Raises:
+            CommandError: If a matched frame cannot be converted.
+        """
+        if spec.pattern is None:
+            if spec.parser is not None:
+                try:
+                    return True, spec.parser(text)
+                except (ValueError, TypeError) as exc:
+                    raise CommandError(
+                        f"response parser failed: {exc}"
+                    ) from exc
+            return True, text
+        match = re.fullmatch(spec.pattern, text)
+        if match is None:
+            return False, None
+        if isinstance(spec, CommandSpec) and spec.parser is not None:
+            try:
+                return True, spec.parser(text)
+            except (ValueError, TypeError) as exc:
+                raise CommandError(f"response parser failed: {exc}") from exc
+        result_type = spec.result_type
+        captures = match.groupdict()
+        if result_type is None:
+            return True, captures if captures else match.group(0)
+        if result_type in {str, int, float}:
+            value = (
+                next(iter(captures.values())) if captures else match.group(0)
+            )
+            try:
+                return True, result_type(value)
+            except (ValueError, TypeError) as exc:
+                raise CommandError(
+                    f"response conversion failed: {exc}"
+                ) from exc
+        if not is_dataclass(result_type):
+            raise CommandError("result_type must be a scalar or dataclass")
+        hints = get_type_hints(result_type)
+        converted: dict[str, Any] = {}
+        try:
+            for field in fields(result_type):
+                raw = captures[field.name]
+                field_type = hints[field.name]
+                if field_type in {str, int, float}:
+                    converted[field.name] = field_type(raw)
+                elif isinstance(field_type, type) and issubclass(
+                    field_type, Enum
+                ):
+                    try:
+                        converted[field.name] = field_type(raw)
+                    except ValueError:
+                        converted[field.name] = field_type[raw]
+                else:
+                    raise CommandError(
+                        f"unsupported result field type: {field.name}"
+                    )
+            return True, result_type(**converted)
+        except (KeyError, ValueError, TypeError) as exc:
+            raise CommandError(f"response conversion failed: {exc}") from exc
+
+
+__all__ = ["ResponseParser"]

serialforge/connection/serial_handler.py

@@ -0,0 +1,284 @@
+"""One-device QtCore facade for serial connection and command lifecycle."""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import replace
+from typing import TYPE_CHECKING
+
+# PySide6 exposes these C++ types through generated bindings, which pylint
+# cannot resolve even though ty and Python imports can.
+# pylint: disable=no-name-in-module
+from PySide6.QtCore import QCoreApplication, QObject, Qt, QThread, Signal
+
+# pylint: enable=no-name-in-module
+from ..advanced import CommandPriority, CommandTicket, HandlerStats
+from ..diagnostics import TrafficLogger
+from ..enums import CommandStatus, ConnectionState, SendRoute
+from ..errors import CommandError, SerialForgeError
+from ..models import (
+    CommandResult,
+    CommandSpec,
+    DeviceInfo,
+    DeviceProfile,
+    EventSpec,
+    LogConfig,
+)
+from .command_registry import CommandRegistry
+from .connection_worker import ConnectionWorker
+
+# The facade owns the complete lifecycle state for one serial connection.
+# pylint: disable=too-many-instance-attributes
+
+if TYPE_CHECKING:
+    from .command_dispatcher import CommandDispatcher
+
+
+class SerialHandler(QObject):
+    """Coordinate one connection, its command registry, and Qt signals."""
+
+    connection_state_changed = Signal(ConnectionState)
+    command_finished = Signal(object)
+    event_received = Signal(object)
+    traffic_logged = Signal(object)
+    error_occurred = Signal(object)
+
+    def __init__(
+        self,
+        profile: DeviceProfile,
+        *,
+        log: LogConfig | None = None,
+        allow_raw_text: bool = True,
+    ) -> None:
+        """Create a disconnected handler with no open serial resources."""
+        application = QCoreApplication.instance()
+        if application is None:
+            raise SerialForgeError("SerialHandler requires a QCoreApplication")
+        super().__init__()
+        self._profile: DeviceProfile = profile
+        self._log: LogConfig = log or LogConfig()
+        self._allow_raw_text: bool = allow_raw_text
+        self._state: ConnectionState = ConnectionState.DISCONNECTED
+        self._state_lock: threading.RLock = threading.RLock()
+        self._worker: ConnectionWorker | None = None
+        self._traffic: TrafficLogger = TrafficLogger(
+            self._log, profile.runtime, encoding=profile.encoding
+        )
+        self._traffic.traffic_logged.connect(
+            self.traffic_logged.emit, Qt.ConnectionType.DirectConnection
+        )
+        self._traffic.error_occurred.connect(
+            self._report_error, Qt.ConnectionType.DirectConnection
+        )
+        self._registry: CommandRegistry = CommandRegistry(profile.terminator)
+        # Keep the top-level package import free of advanced implementation.
+        # pylint: disable=import-outside-toplevel
+        from .command_dispatcher import CommandDispatcher
+
+        self._dispatcher: CommandDispatcher = CommandDispatcher(
+            profile, self._registry, self._write
+        )
+        self._dispatcher.command_finished.connect(
+            self.command_finished.emit, Qt.ConnectionType.DirectConnection
+        )
+        self._dispatcher.event_received.connect(
+            self.event_received.emit, Qt.ConnectionType.DirectConnection
+        )
+        self._dispatcher.error_occurred.connect(
+            self.error_occurred.emit, Qt.ConnectionType.DirectConnection
+        )
+        self._dispatcher.tx_written.connect(
+            self._record_tx, Qt.ConnectionType.DirectConnection
+        )
+        self._init_sequence: tuple[CommandSpec | str, ...] = ()
+        application.aboutToQuit.connect(self.disconnect)
+
+    def _write(self, data: bytes) -> int:
+        """Send bytes through the active connection worker."""
+        worker = self._worker
+        if worker is None:
+            raise RuntimeError("serial transport is not connected")
+        return worker.write(data)
+
+    @property
+    def state(self) -> ConnectionState:
+        """Return the current connection state."""
+        with self._state_lock:
+            return self._state
+
+    # ty: ignore[invalid-method-override, missing-override-decorator] --
+    # QObject has an unrelated C++ signal-connect overload with the same name.
+    def connect(self, target: str | DeviceInfo | None = None) -> None:
+        """Start an asynchronous connection to a device or matching profile."""
+        with self._state_lock:
+            if self._state not in {
+                ConnectionState.DISCONNECTED,
+                ConnectionState.FAILED,
+            }:
+                raise SerialForgeError(
+                    f"cannot connect while {self._state.value}"
+                )
+            worker = self._worker
+            if worker is not None and worker.isRunning():
+                raise SerialForgeError(
+                    "previous connection worker is still running"
+                )
+            self._worker = ConnectionWorker(self, target)
+        self._transition(
+            ConnectionState.CONNECTING
+            if isinstance(target, DeviceInfo)
+            else ConnectionState.PROBING
+        )
+        assert self._worker is not None
+        self._worker.start()
+
+    # ty: ignore[invalid-method-override, missing-override-decorator] --
+    # This public facade method intentionally shadows QObject.disconnect().
+    def disconnect(self) -> None:
+        """Stop the connection and join its I/O threads idempotently."""
+        worker = self._worker
+        if worker is not None:
+            worker.request_stop()
+            for _ in range(50):
+                if worker.wait(100):
+                    break
+                worker.request_stop()
+            else:
+                raise SerialForgeError("connection worker did not stop")
+            self._worker = None
+        self._dispatcher.set_connected(False, user_initiated=True)
+        self._traffic.end_connection()
+        self._transition(ConnectionState.DISCONNECTED)
+
+    def _transition(self, state: ConnectionState) -> None:
+        """Publish a state change from either connection thread."""
+        with self._state_lock:
+            if self._state is state:
+                return
+            self._state = state
+        self.connection_state_changed.emit(state)
+
+    def _report_error(self, error: Exception) -> None:
+        """Normalize I/O failures to the public exception hierarchy."""
+        payload = (
+            error
+            if isinstance(error, SerialForgeError)
+            else SerialForgeError(str(error))
+        )
+        self.error_occurred.emit(payload)
+
+    def _receive_frame(self, frame: bytes) -> None:
+        """Record and dispatch one completed receive frame."""
+        worker = self._worker
+        port = worker.port if worker is not None else None
+        self._traffic.record_rx(port or "-", frame)
+        self._dispatcher.receive_frame(frame)
+
+    def _record_tx(
+        self, data: bytes, route: SendRoute, spec: CommandSpec | None
+    ) -> None:
+        """Record a successful command write with its original spec."""
+        worker = self._worker
+        port = worker.port if worker is not None else None
+        self._traffic.record_tx(port or "-", data, route, spec)
+
+    def register(self, *specs: CommandSpec | EventSpec) -> None:
+        """Register command and event declarations by object identity."""
+        self._registry.register(*specs)
+
+    def unregister(self, spec: CommandSpec | EventSpec) -> None:
+        """Remove a declaration from future sends and event matches."""
+        self._registry.unregister(spec)
+
+    def set_init_sequence(self, items: list[CommandSpec | str]) -> None:
+        """Validate and retain steps for M5 connection initialization."""
+        for item in items:
+            if isinstance(item, CommandSpec):
+                if not self._registry.contains(item):
+                    raise CommandError(
+                        f"init command {item.name!r} is not registered"
+                    )
+                if item.placeholders:
+                    raise CommandError(
+                        "init command with placeholders requires text"
+                    )
+            elif isinstance(item, str):
+                if (
+                    self._registry.resolve_text(item, self._profile.terminator)
+                    is None
+                ):
+                    raise CommandError(
+                        f"init command text is not registered: {item!r}"
+                    )
+            else:
+                raise CommandError("init sequence accepts CommandSpec or str")
+        self._init_sequence = tuple(items)
+
+    def send(
+        self,
+        target: CommandSpec | str,
+        /,
+        *,
+        priority: CommandPriority | None = None,
+        **params: object,
+    ) -> CommandTicket:
+        """Queue a registered command or safe raw text without blocking."""
+        if priority is None:
+            priority = CommandPriority.NORMAL
+        return self._dispatcher.submit(
+            target,
+            priority=priority,
+            allow_raw_text=self._allow_raw_text,
+            **params,
+        )
+
+    def send_and_wait(
+        self, target: CommandSpec | str, /, *, timeout: float, **params: object
+    ) -> CommandResult:
+        """Wait in a script thread that has no running Qt event loop."""
+        if QThread.currentThread().loopLevel() > 0:
+            raise CommandError("send_and_wait cannot run in a Qt event loop")
+        if timeout <= 0:
+            raise CommandError("timeout must be positive")
+        received: list[CommandResult] = []
+        done = threading.Event()
+        request_id: str | None = None
+
+        def on_finished(result: CommandResult) -> None:
+            received.append(result)
+            if result.request_id == request_id:
+                done.set()
+
+        self.command_finished.connect(
+            on_finished, Qt.ConnectionType.DirectConnection
+        )
+        try:
+            # ty: ignore[invalid-argument-type] -- send validates variadic parameters.
+            ticket = self.send(target, **params)
+            request_id = ticket.request_id
+            if not any(
+                result.request_id == ticket.request_id for result in received
+            ):
+                done.wait(timeout)
+            for result in received:
+                if result.request_id == ticket.request_id:
+                    return result
+            self._dispatcher.cancel_ticket(ticket, CommandStatus.TIMEOUT)
+            for result in received:
+                if result.request_id == ticket.request_id:
+                    return result
+            raise CommandError("command timeout could not be resolved")
+        finally:
+            self.command_finished.disconnect(on_finished)
+
+    def set_log_config(self, config: LogConfig) -> None:
+        """Apply log switches and retain file policy for this session."""
+        self._log = config
+        self._traffic.set_log_config(config)
+
+    def stats(self) -> HandlerStats:
+        """Return latency, event, and file traffic drop counters."""
+        return replace(
+            self._dispatcher.stats(),
+            dropped_traffic_lines=self._traffic.dropped_traffic_lines,
+        )

serialforge/diagnostics/__init__.py

@@ -0,0 +1,6 @@
+"""Traffic logging and per-connection log file management."""
+
+from .log_file_manager import LogFileManager
+from .traffic_logger import TrafficLogger
+
+__all__ = ["LogFileManager", "TrafficLogger"]