swbt-python 0.5.0__py3-none-any.whl → 0.5.2__py3-none-any.whl

swbt/diagnostics.py

@@ -67,21 +67,16 @@ class GamepadStatus:
 
 
 class DiagnosticsRecorder:
-    """Record a small in-memory diagnostics event history."""
+    """Record bounded diagnostics aggregates and optional JSON Lines traces."""
 
     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._last_error: DiagnosticsEvent | 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."""
@@ -100,10 +95,7 @@ class DiagnosticsRecorder:
     @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
+        return self._last_error
 
     def record_event(self, event: str, **fields: object) -> DiagnosticsEvent:
         """Record a diagnostics event with schema fields."""
@@ -155,21 +147,6 @@ class DiagnosticsRecorder:
             **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(
@@ -178,11 +155,11 @@ class DiagnosticsRecorder:
             message=str(error),
             recoverable=recoverable,
         )
+        self._last_error = event
         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}

swbt/gamepad/__init__.py

@@ -2,7 +2,7 @@
 
 from swbt.gamepad.connection import ConnectionResult, ConnectionStatus
 from swbt.gamepad.constants import DISCONNECT_REQUEST_TIMEOUT_SECONDS
-from swbt.gamepad.core import (
+from swbt.gamepad.controllers import (
     DirectJoyConL,
     DirectJoyConR,
     DirectProController,

swbt/gamepad/_config.py

@@ -1,82 +1,14 @@
-"""Configuration models for gamepad construction and runtime setup."""
+"""Normalized configuration for gamepad construction and runtime setup."""
 
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 
 from swbt.errors import InvalidInputError
 from swbt.protocol.profiles.base import ControllerColors, ControllerProfile
-from swbt.protocol.profiles.pro_controller import default_controller_profile
 
 
-@dataclass(frozen=True)
-class _SwitchGamepadConfig:
-    """Configuration used to construct a concrete gamepad.
-
-    Attributes:
-        adapter: Bumble adapter moniker, such as ``"usb:0"``.
-        profile_path: Path to a swbt-owned pairing profile.
-        profile: Fixed controller identity and protocol profile.
-        report_period_us: Periodic input report interval in microseconds.
-        device_name: HID device name advertised to the host.
-        controller_colors: Fixed controller body, button, and grip colors for SPI profile data.
-    """
-
-    adapter: str | None = None
-    profile_path: str | None = None
-    profile: ControllerProfile = field(default_factory=default_controller_profile)
-    report_period_us: int | None = None
-    device_name: str | None = None
-    controller_colors: ControllerColors | None = None
-
-    def __post_init__(self) -> None:
-        """Validate resource configuration."""
-        if not isinstance(self.profile, ControllerProfile):
-            msg = "profile must be a ControllerProfile"
-            raise InvalidInputError(msg)
-        if self.report_period_us is None:
-            object.__setattr__(
-                self,
-                "report_period_us",
-                self.profile.default_report_period_us,
-            )
-        elif self.report_period_us <= 0:
-            msg = "report_period_us must be positive"
-            raise InvalidInputError(msg)
-        if self.device_name is None:
-            object.__setattr__(self, "device_name", self.profile.device_name)
-        if self.controller_colors is not None and not isinstance(
-            self.controller_colors, ControllerColors
-        ):
-            msg = "controller_colors must be a ControllerColors"
-            raise InvalidInputError(msg)
-
-
-@dataclass(frozen=True)
-class _ControllerSpec:
-    """Internal controller identity selected by a concrete controller class."""
-
-    profile: ControllerProfile
-
-    def build_config(
-        self,
-        *,
-        adapter: str | None,
-        report_period_us: int | None,
-        controller_colors: ControllerColors | None,
-        profile_path: str | None = None,
-    ) -> _SwitchGamepadConfig:
-        """Create internal construction config from public constructor options."""
-        return _SwitchGamepadConfig(
-            adapter=adapter,
-            profile_path=profile_path,
-            profile=self.profile,
-            report_period_us=report_period_us,
-            controller_colors=controller_colors,
-        )
-
-
-@dataclass(frozen=True)
-class _RuntimeConfig:
-    """Normalized internal configuration for ControllerRuntime."""
+@dataclass(frozen=True, init=False)
+class _GamepadConfig:
+    """Normalized internal configuration shared by a controller and its runtime."""
 
     adapter: str | None
     profile_path: str | None
@@ -85,17 +17,37 @@ class _RuntimeConfig:
     device_name: str
     controller_colors: ControllerColors | None
 
-    @classmethod
-    def from_public_config(cls, config: _SwitchGamepadConfig) -> "_RuntimeConfig":
-        """Create normalized runtime configuration from public construction config."""
-        if config.report_period_us is None or config.device_name is None:
-            msg = "_SwitchGamepadConfig was not normalized"
+    def __init__(
+        self,
+        *,
+        profile: ControllerProfile,
+        adapter: str | None = None,
+        profile_path: str | None = None,
+        report_period_us: int | None = None,
+        device_name: str | None = None,
+        controller_colors: ControllerColors | None = None,
+    ) -> None:
+        """Validate and normalize controller construction values."""
+        if not isinstance(profile, ControllerProfile):
+            msg = "profile must be a ControllerProfile"
+            raise InvalidInputError(msg)
+        normalized_report_period = (
+            profile.default_report_period_us if report_period_us is None else report_period_us
+        )
+        if normalized_report_period <= 0:
+            msg = "report_period_us must be positive"
             raise InvalidInputError(msg)
-        return cls(
-            adapter=config.adapter,
-            profile_path=config.profile_path,
-            profile=config.profile,
-            report_period_us=config.report_period_us,
-            device_name=config.device_name,
-            controller_colors=config.controller_colors,
+        if controller_colors is not None and not isinstance(controller_colors, ControllerColors):
+            msg = "controller_colors must be a ControllerColors"
+            raise InvalidInputError(msg)
+
+        object.__setattr__(self, "adapter", adapter)
+        object.__setattr__(self, "profile_path", profile_path)
+        object.__setattr__(self, "profile", profile)
+        object.__setattr__(self, "report_period_us", normalized_report_period)
+        object.__setattr__(
+            self,
+            "device_name",
+            profile.device_name if device_name is None else device_name,
         )
+        object.__setattr__(self, "controller_colors", controller_colors)

swbt/gamepad/connection.py

@@ -1,30 +1,11 @@
-"""Connection workflow for SwitchGamepad."""
+"""Public connection result types."""
 
-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:
@@ -33,196 +14,11 @@ class ConnectionResult:
     Args:
         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.
-
-    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.
+        peer_address: Address used for active reconnect, when one was selected.
+        peer_count: Number of current 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
-    profile_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.profile_path is None and not self.transport_was_injected:
-            self.diagnostics.record_event(
-                "reconnect_profile_unavailable",
-                reason="profile_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

swbt/gamepad/controllers.py

@@ -0,0 +1,211 @@
+"""Public concrete gamepad controllers."""
+
+from swbt.diagnostics import DiagnosticsConfig
+from swbt.gamepad.interface import DirectSwitchGamepad, PeriodicSwitchGamepad
+from swbt.protocol.profiles.base import ControllerColors
+from swbt.protocol.profiles.joycon import JoyConLeftProfile, JoyConRightProfile
+from swbt.protocol.profiles.pro_controller import default_controller_profile
+
+
+class ProController(PeriodicSwitchGamepad):
+    """Runtime-backed Pro Controller-compatible gamepad."""
+
+    _profile = default_controller_profile()
+
+    def __init__(
+        self,
+        *,
+        adapter: str | None = None,
+        profile_path: str | None = None,
+        report_period_us: int | None = None,
+        controller_colors: ControllerColors | None = None,
+        diagnostics: DiagnosticsConfig | None = None,
+    ) -> None:
+        """Create a Pro Controller-compatible gamepad.
+
+        Args:
+            adapter: Bumble adapter moniker used for the Bluetooth backend.
+            profile_path: Optional swbt-owned pairing profile path.
+            report_period_us: Optional periodic input report interval in microseconds.
+            controller_colors: Optional fixed controller body, button, and grip colors.
+            diagnostics: Optional diagnostics configuration for trace output.
+
+        Raises:
+            InvalidInputError: adapter is omitted or report_period_us is not positive.
+        """
+        self._initialize_runtime(
+            adapter=adapter,
+            profile_path=profile_path,
+            report_period_us=report_period_us,
+            controller_colors=controller_colors,
+            diagnostics=diagnostics,
+        )
+
+
+class JoyConL(PeriodicSwitchGamepad):
+    """Runtime-backed Joy-Con L-compatible gamepad."""
+
+    _profile = JoyConLeftProfile()
+
+    def __init__(
+        self,
+        *,
+        adapter: str | None = None,
+        profile_path: str | None = None,
+        report_period_us: int | None = None,
+        controller_colors: ControllerColors | None = None,
+        diagnostics: DiagnosticsConfig | None = None,
+    ) -> None:
+        """Create a left Joy-Con-compatible gamepad.
+
+        Args:
+            adapter: Bumble adapter moniker used for the Bluetooth backend.
+            profile_path: Optional swbt-owned pairing profile path.
+            report_period_us: Optional periodic input report interval in microseconds.
+            controller_colors: Optional fixed controller body, button, and grip colors.
+            diagnostics: Optional diagnostics configuration for trace output.
+
+        Raises:
+            InvalidInputError: ``adapter`` is omitted or ``report_period_us`` is not positive.
+        """
+        self._initialize_runtime(
+            adapter=adapter,
+            profile_path=profile_path,
+            report_period_us=report_period_us,
+            controller_colors=controller_colors,
+            diagnostics=diagnostics,
+        )
+
+
+class JoyConR(PeriodicSwitchGamepad):
+    """Runtime-backed Joy-Con R-compatible gamepad."""
+
+    _profile = JoyConRightProfile()
+
+    def __init__(
+        self,
+        *,
+        adapter: str | None = None,
+        profile_path: str | None = None,
+        report_period_us: int | None = None,
+        controller_colors: ControllerColors | None = None,
+        diagnostics: DiagnosticsConfig | None = None,
+    ) -> None:
+        """Create a right Joy-Con-compatible gamepad.
+
+        Args:
+            adapter: Bumble adapter moniker used for the Bluetooth backend.
+            profile_path: Optional swbt-owned pairing profile path.
+            report_period_us: Optional periodic input report interval in microseconds.
+            controller_colors: Optional fixed controller body, button, and grip colors.
+            diagnostics: Optional diagnostics configuration for trace output.
+
+        Raises:
+            InvalidInputError: ``adapter`` is omitted or ``report_period_us`` is not positive.
+        """
+        self._initialize_runtime(
+            adapter=adapter,
+            profile_path=profile_path,
+            report_period_us=report_period_us,
+            controller_colors=controller_colors,
+            diagnostics=diagnostics,
+        )
+
+
+class DirectProController(DirectSwitchGamepad):
+    """Direct-reporting Pro Controller-compatible gamepad."""
+
+    _profile = default_controller_profile()
+
+    def __init__(
+        self,
+        *,
+        adapter: str | None = None,
+        profile_path: str | None = None,
+        controller_colors: ControllerColors | None = None,
+        diagnostics: DiagnosticsConfig | None = None,
+    ) -> None:
+        """Create a direct-reporting Pro Controller-compatible gamepad.
+
+        Args:
+            adapter: Bumble adapter moniker used for the Bluetooth backend.
+            profile_path: Optional swbt-owned pairing profile path.
+            controller_colors: Optional fixed controller body, button, and grip colors.
+            diagnostics: Optional diagnostics configuration for trace output.
+
+        Raises:
+            InvalidInputError: ``adapter`` is omitted.
+        """
+        self._initialize_runtime(
+            adapter=adapter,
+            profile_path=profile_path,
+            report_period_us=None,
+            controller_colors=controller_colors,
+            diagnostics=diagnostics,
+        )
+
+
+class DirectJoyConL(DirectSwitchGamepad):
+    """Direct-reporting Joy-Con L-compatible gamepad."""
+
+    _profile = JoyConLeftProfile()
+
+    def __init__(
+        self,
+        *,
+        adapter: str | None = None,
+        profile_path: str | None = None,
+        controller_colors: ControllerColors | None = None,
+        diagnostics: DiagnosticsConfig | None = None,
+    ) -> None:
+        """Create a direct-reporting Joy-Con L-compatible gamepad.
+
+        Args:
+            adapter: Bumble adapter moniker used for the Bluetooth backend.
+            profile_path: Optional swbt-owned pairing profile path.
+            controller_colors: Optional fixed controller body, button, and grip colors.
+            diagnostics: Optional diagnostics configuration for trace output.
+
+        Raises:
+            InvalidInputError: ``adapter`` is omitted.
+        """
+        self._initialize_runtime(
+            adapter=adapter,
+            profile_path=profile_path,
+            report_period_us=None,
+            controller_colors=controller_colors,
+            diagnostics=diagnostics,
+        )
+
+
+class DirectJoyConR(DirectSwitchGamepad):
+    """Direct-reporting Joy-Con R-compatible gamepad."""
+
+    _profile = JoyConRightProfile()
+
+    def __init__(
+        self,
+        *,
+        adapter: str | None = None,
+        profile_path: str | None = None,
+        controller_colors: ControllerColors | None = None,
+        diagnostics: DiagnosticsConfig | None = None,
+    ) -> None:
+        """Create a direct-reporting Joy-Con R-compatible gamepad.
+
+        Args:
+            adapter: Bumble adapter moniker used for the Bluetooth backend.
+            profile_path: Optional swbt-owned pairing profile path.
+            controller_colors: Optional fixed controller body, button, and grip colors.
+            diagnostics: Optional diagnostics configuration for trace output.
+
+        Raises:
+            InvalidInputError: ``adapter`` is omitted.
+        """
+        self._initialize_runtime(
+            adapter=adapter,
+            profile_path=profile_path,
+            report_period_us=None,
+            controller_colors=controller_colors,
+            diagnostics=diagnostics,
+        )