swbt-python 0.1.0__py3-none-any.whl

swbt/__init__.py

@@ -0,0 +1,37 @@
+"""Python API for virtual NX-compatible input devices."""
+
+from swbt.diagnostics import DiagnosticsConfig, GamepadStatus
+from swbt.errors import (
+    ClosedError,
+    ConnectionFailedError,
+    ConnectionTimeoutError,
+    InvalidInputError,
+    InvalidKeyStoreError,
+    SwbtError,
+    TransportOpenError,
+)
+from swbt.gamepad import ConnectionResult, SwitchGamepad, SwitchGamepadConfig
+from swbt.input import Button, IMUFrame, InputState, Stick
+from swbt.transport.base import BondedPeer, DisconnectRequestResult, HidDeviceTransport
+
+__all__ = (
+    "BondedPeer",
+    "Button",
+    "ClosedError",
+    "ConnectionFailedError",
+    "ConnectionResult",
+    "ConnectionTimeoutError",
+    "DiagnosticsConfig",
+    "DisconnectRequestResult",
+    "GamepadStatus",
+    "HidDeviceTransport",
+    "IMUFrame",
+    "InputState",
+    "InvalidInputError",
+    "InvalidKeyStoreError",
+    "Stick",
+    "SwbtError",
+    "SwitchGamepad",
+    "SwitchGamepadConfig",
+    "TransportOpenError",
+)

swbt/diagnostics.py

@@ -0,0 +1,202 @@
+"""Minimal diagnostics state for gamepad lifecycle and callback errors."""
+
+import json
+import platform
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, version
+from typing import TextIO
+
+
+@dataclass(frozen=True)
+class DiagnosticsConfig:
+    """Diagnostics configuration accepted by SwitchGamepad.
+
+    Attributes:
+        trace_writer: Text stream that receives one JSON Lines diagnostics event per line.
+    """
+
+    trace_writer: TextIO | None = None
+
+
+@dataclass(frozen=True)
+class DiagnosticsEvent:
+    """One diagnostics event recorded by the gamepad.
+
+    Attributes:
+        event: Stable event name.
+        error_type: Exception type name for error events.
+        message: Human-readable error message for error events.
+        recoverable: Whether the error can be treated as recoverable.
+        fields: Event-specific structured fields.
+    """
+
+    event: str
+    error_type: str | None = None
+    message: str | None = None
+    recoverable: bool | None = None
+    fields: dict[str, object] | None = None
+
+
+@dataclass(frozen=True)
+class GamepadStatus:
+    """Snapshot of gamepad status exposed by SwitchGamepad.status().
+
+    Attributes:
+        connection_state: Current lifecycle state name.
+        report_counters: Sent report counts keyed by numeric report ID.
+        last_subcommand_id: Last observed subcommand ID, if any.
+        raw_rumble: Last raw rumble payload received from the host.
+        last_error: Latest diagnostics error event, if any.
+    """
+
+    connection_state: str
+    report_counters: dict[int, int]
+    last_subcommand_id: int | None
+    raw_rumble: bytes | None
+    last_error: DiagnosticsEvent | None
+
+
+class DiagnosticsRecorder:
+    """Record a small in-memory diagnostics event history."""
+
+    def __init__(self, trace_writer: TextIO | None = None) -> None:
+        """Create an empty recorder."""
+        self._events: list[DiagnosticsEvent] = []
+        self._report_counters: dict[int, int] = {}
+        self._last_subcommand_id: int | None = None
+        self._raw_rumble: bytes | None = None
+        self._trace_writer = trace_writer
+
+    @property
+    def events(self) -> tuple[DiagnosticsEvent, ...]:
+        """Return recorded events in order."""
+        return tuple(self._events)
+
+    @property
+    def report_counters(self) -> dict[int, int]:
+        """Return sent report counters keyed by report ID."""
+        return dict(self._report_counters)
+
+    @property
+    def last_subcommand_id(self) -> int | None:
+        """Return the last observed subcommand ID."""
+        return self._last_subcommand_id
+
+    @property
+    def raw_rumble(self) -> bytes | None:
+        """Return the last observed raw rumble payload."""
+        return self._raw_rumble
+
+    @property
+    def last_error(self) -> DiagnosticsEvent | None:
+        """Return the latest error event."""
+        for event in reversed(self._events):
+            if event.event == "error":
+                return event
+        return None
+
+    def record_event(self, event: str, **fields: object) -> DiagnosticsEvent:
+        """Record a diagnostics event with schema fields."""
+        diagnostics_event = DiagnosticsEvent(event=event, fields=dict(fields))
+        self._append(diagnostics_event)
+        return diagnostics_event
+
+    def record_report_tx(self, *, report_id: int, reason: str) -> DiagnosticsEvent:
+        """Record one sent report and increment its counter."""
+        counter = self._report_counters.get(report_id, 0) + 1
+        self._report_counters[report_id] = counter
+        return self.record_event(
+            "report_tx",
+            counter=counter,
+            reason=reason,
+            report_id=f"0x{report_id:02x}",
+        )
+
+    def record_subcommand_rx(self, *, packet_id: int | None, subcommand_id: int) -> None:
+        """Record the latest observed subcommand ID."""
+        self._last_subcommand_id = subcommand_id
+        self.record_event(
+            "subcommand_rx",
+            packet_id=packet_id,
+            subcommand_id=f"0x{subcommand_id:02x}",
+        )
+
+    def record_raw_rumble(self, raw_rumble: bytes) -> None:
+        """Record the latest raw rumble bytes."""
+        self._raw_rumble = bytes(raw_rumble)
+
+    def record_run_metadata(
+        self,
+        *,
+        adapter: str,
+        key_store_exists: bool | None = None,
+        key_store_path: str | None = None,
+        key_store_previous_exists: bool | None = None,
+    ) -> DiagnosticsEvent:
+        """Record environment metadata for one diagnostics run."""
+        fields: dict[str, object] = {
+            "adapter": adapter,
+            "os": platform.system(),
+            "package_version": self._package_version(),
+            "python_version": platform.python_version(),
+        }
+        if key_store_path is not None:
+            fields["key_store_path"] = key_store_path
+        if key_store_exists is not None:
+            fields["key_store_exists"] = key_store_exists
+        if key_store_previous_exists is not None:
+            fields["key_store_previous_exists"] = key_store_previous_exists
+        return self.record_event(
+            "run_metadata",
+            **fields,
+        )
+
+    def record_state_transition(
+        self,
+        *,
+        previous: str,
+        next_state: str,
+        reason: str,
+    ) -> DiagnosticsEvent:
+        """Record one lifecycle state transition."""
+        return self.record_event(
+            "state_transition",
+            previous=previous,
+            next=next_state,
+            reason=reason,
+        )
+
+    def record_error(self, error: BaseException, *, recoverable: bool) -> DiagnosticsEvent:
+        """Record an exception as an error event."""
+        event = DiagnosticsEvent(
+            event="error",
+            error_type=type(error).__name__,
+            message=str(error),
+            recoverable=recoverable,
+        )
+        self._append(event)
+        return event
+
+    def _append(self, event: DiagnosticsEvent) -> None:
+        self._events.append(event)
+        if self._trace_writer is None:
+            return
+        payload: dict[str, object] = {"event": event.event}
+        if event.fields is not None:
+            payload.update(event.fields)
+        if event.error_type is not None:
+            payload["error_type"] = event.error_type
+        if event.message is not None:
+            payload["message"] = event.message
+        if event.recoverable is not None:
+            payload["recoverable"] = event.recoverable
+        self._trace_writer.write(json.dumps(payload, separators=(",", ":"), sort_keys=True))
+        self._trace_writer.write("\n")
+        self._trace_writer.flush()
+
+    @staticmethod
+    def _package_version() -> str:
+        try:
+            return version("swbt-python")
+        except PackageNotFoundError:
+            return "unknown"

swbt/errors.py

@@ -0,0 +1,33 @@
+"""Exception types exposed by swbt."""
+
+
+class SwbtError(Exception):
+    """Base exception for swbt errors."""
+
+
+class TransportOpenError(SwbtError):
+    """Raised when a transport cannot be opened."""
+
+
+class ConnectionTimeoutError(SwbtError):
+    """Raised when waiting for a connection times out."""
+
+
+class ConnectionFailedError(SwbtError):
+    """Raised when a connection attempt finishes without a connection."""
+
+
+class InvalidKeyStoreError(SwbtError):
+    """Raised when a key store has an unsupported or invalid shape."""
+
+
+class ProtocolError(SwbtError):
+    """Raised when protocol bytes cannot be parsed or produced."""
+
+
+class ClosedError(SwbtError):
+    """Raised when an operation requires an open controller."""
+
+
+class InvalidInputError(SwbtError):
+    """Raised when user-provided input values are outside the supported range."""

swbt/gamepad/__init__.py

@@ -0,0 +1,14 @@
+"""Public gamepad facade."""
+
+from swbt.gamepad.connection import ConnectionResult, ConnectionStatus
+from swbt.gamepad.core import SwitchGamepad, SwitchGamepadConfig
+
+DISCONNECT_REQUEST_TIMEOUT_SECONDS = 0.25
+
+__all__ = (
+    "DISCONNECT_REQUEST_TIMEOUT_SECONDS",
+    "ConnectionResult",
+    "ConnectionStatus",
+    "SwitchGamepad",
+    "SwitchGamepadConfig",
+)

swbt/gamepad/connection.py

@@ -0,0 +1,222 @@
+"""Connection workflow for SwitchGamepad."""
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Literal
+
+from swbt.diagnostics import DiagnosticsRecorder
+from swbt.errors import (
+    ClosedError,
+    ConnectionFailedError,
+    ConnectionTimeoutError,
+    InvalidKeyStoreError,
+)
+from swbt.transport.base import HidDeviceTransport
+
+ConnectionRoute = Literal["active_reconnect", "pairing"]
+ConnectionStatus = Literal["connected", "no_bond", "timeout", "failed"]
+
+EnsureOpen = Callable[[], Awaitable[None]]
+TransportProvider = Callable[[], HidDeviceTransport | None]
+StateSetter = Callable[[str], None]
+EventClearer = Callable[[], None]
+WaitForConnected = Callable[[float | None], Awaitable[None]]
+CloseNeutral = Callable[[], Awaitable[None]]
+PairWithTimeout = Callable[[float | None], Awaitable[None]]
+
+
+@dataclass(frozen=True)
+class ConnectionResult:
+    """Result of an explicit connection strategy.
+
+    Attributes:
+        route: Connection path that produced the result.
+        status: Outcome of the connection attempt.
+        peer_address: Address of the bonded peer used for reconnect, when one was selected.
+        peer_count: Number of bonded peers observed while selecting a reconnect target.
+    """
+
+    route: ConnectionRoute
+    status: ConnectionStatus
+    peer_address: str | None = None
+    peer_count: int | None = None
+
+
+@dataclass
+class ConnectionWorkflow:
+    """Run active reconnect and pairing fallback workflows."""
+
+    clear_connected: EventClearer
+    close_neutral: CloseNeutral
+    diagnostics: DiagnosticsRecorder
+    ensure_open: EnsureOpen
+    get_transport: TransportProvider
+    key_store_path: str | None
+    pair: PairWithTimeout
+    set_connection_state: StateSetter
+    transport_was_injected: bool
+    wait_for_connected: WaitForConnected
+
+    async def try_reconnect(
+        self,
+        timeout: float | None = None,  # noqa: ASYNC109
+    ) -> ConnectionResult:
+        """Try active reconnect with exactly one bonded peer."""
+        await self.ensure_open()
+        transport = self._transport()
+        if self.key_store_path is None and not self.transport_was_injected:
+            self.diagnostics.record_event(
+                "reconnect_key_store_unavailable",
+                reason="key_store_path_none",
+                route="active_reconnect",
+            )
+        peers = await transport.list_bonded_peers()
+        if len(peers) > 1:
+            self.diagnostics.record_event(
+                "invalid_key_store",
+                peer_count=len(peers),
+                reason="multiple_current_peers",
+            )
+            msg = "key store contains multiple current peers"
+            raise InvalidKeyStoreError(msg)
+        selection = _bonded_peer_selection(len(peers))
+        self.diagnostics.record_event(
+            "bonded_peers_discovered",
+            peer_count=len(peers),
+            selection=selection,
+        )
+        if not peers:
+            self.diagnostics.record_event(
+                "active_reconnect_result",
+                peer_count=0,
+                route="active_reconnect",
+                status="no_bond",
+            )
+            return ConnectionResult(
+                route="active_reconnect",
+                status="no_bond",
+                peer_count=0,
+            )
+        peer = peers[0]
+        self.set_connection_state("reconnecting")
+        self.clear_connected()
+        self.diagnostics.record_event(
+            "active_reconnect_attempt",
+            peer_address=peer.address,
+            route="active_reconnect",
+        )
+        try:
+            await transport.connect_bonded_peer(
+                peer.address,
+                connect_timeout=timeout,
+            )
+            await self.wait_for_connected(timeout)
+        except TimeoutError:
+            self.diagnostics.record_event(
+                "active_reconnect_result",
+                failure_reason="connection_timeout",
+                peer_address=peer.address,
+                route="active_reconnect",
+                status="timeout",
+            )
+            await self.close_neutral()
+            return ConnectionResult(
+                route="active_reconnect",
+                status="timeout",
+                peer_address=peer.address,
+                peer_count=1,
+            )
+        except asyncio.CancelledError as error:
+            if _current_task_is_cancelling():
+                raise
+            return await self._record_transport_error(error, peer_address=peer.address)
+        except Exception as error:  # noqa: BLE001
+            return await self._record_transport_error(error, peer_address=peer.address)
+
+        self.diagnostics.record_event(
+            "active_reconnect_result",
+            peer_address=peer.address,
+            route="active_reconnect",
+            status="connected",
+        )
+        return ConnectionResult(
+            route="active_reconnect",
+            status="connected",
+            peer_address=peer.address,
+            peer_count=1,
+        )
+
+    async def try_connect(
+        self,
+        *,
+        timeout: float | None = None,  # noqa: ASYNC109
+        allow_pairing: bool = False,
+    ) -> ConnectionResult:
+        """Try bonded reconnect first, then optional pairing fallback."""
+        reconnect_result = await self.try_reconnect(timeout=timeout)
+        if reconnect_result.status != "no_bond" or not allow_pairing:
+            return reconnect_result
+        self.diagnostics.record_event(
+            "connect_pairing_fallback",
+            reason="no_bond",
+            route="pairing",
+        )
+        try:
+            await self.pair(timeout)
+        except ConnectionTimeoutError:
+            return ConnectionResult(route="pairing", status="timeout")
+        return ConnectionResult(route="pairing", status="connected")
+
+    def _transport(self) -> HidDeviceTransport:
+        transport = self.get_transport()
+        if transport is None:
+            msg = "gamepad is not open"
+            raise ClosedError(msg)
+        return transport
+
+    async def _record_transport_error(
+        self,
+        error: BaseException,
+        *,
+        peer_address: str,
+    ) -> ConnectionResult:
+        self.diagnostics.record_event(
+            "active_reconnect_result",
+            error_type=type(error).__name__,
+            failure_reason="transport_error",
+            message=str(error),
+            peer_address=peer_address,
+            route="active_reconnect",
+            status="failed",
+        )
+        self.diagnostics.record_error(error, recoverable=True)
+        await self.close_neutral()
+        return ConnectionResult(
+            route="active_reconnect",
+            status="failed",
+            peer_address=peer_address,
+            peer_count=1,
+        )
+
+
+def raise_if_connection_failed(result: ConnectionResult) -> None:
+    """Raise the public connection error for a non-connected result."""
+    if result.status == "connected":
+        return
+    if result.status == "timeout":
+        msg = "connection timed out"
+        raise ConnectionTimeoutError(msg)
+    msg = f"connection failed: {result.status}"
+    raise ConnectionFailedError(msg)
+
+
+def _bonded_peer_selection(peer_count: int) -> str:
+    if peer_count == 0:
+        return "none"
+    return "selected"
+
+
+def _current_task_is_cancelling() -> bool:
+    task = asyncio.current_task()
+    return task is not None and task.cancelling() > 0