swbt-python 0.4.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

swbt/__init__.py

@@ -4,11 +4,14 @@ from swbt.adapter_discovery import AdapterInfo, list_adapters
 from swbt.diagnostics import DiagnosticsConfig, GamepadStatus
 from swbt.errors import (
     AdapterDiscoveryError,
+    AdapterIdentityRecoveryRequired,
     ClosedError,
     ConnectionFailedError,
     ConnectionTimeoutError,
     InvalidInputError,
     InvalidKeyStoreError,
+    InvalidProfileError,
+    ProfileControllerMismatchError,
     SwbtError,
     TransportOpenError,
     UnsupportedInputError,
@@ -30,6 +33,7 @@ from swbt.protocol.profiles.base import ControllerColors
 
 __all__ = (
     "AdapterDiscoveryError",
+    "AdapterIdentityRecoveryRequired",
     "AdapterInfo",
     "Button",
     "ClosedError",
@@ -47,10 +51,12 @@ __all__ = (
     "InputState",
     "InvalidInputError",
     "InvalidKeyStoreError",
+    "InvalidProfileError",
     "JoyConL",
     "JoyConR",
     "PeriodicSwitchGamepad",
     "ProController",
+    "ProfileControllerMismatchError",
     "Stick",
     "SwbtError",
     "SwitchGamepad",

swbt/_testing/gamepad.py

@@ -19,7 +19,7 @@ def make_pro_controller(
     *,
     transport: HidDeviceTransport,
     adapter: str | None = None,
-    key_store_path: str | None = None,
+    profile_path: str | None = None,
     report_period_us: int | None = None,
     controller_colors: ControllerColors | None = None,
     diagnostics: DiagnosticsConfig | None = None,
@@ -28,7 +28,7 @@ def make_pro_controller(
     return ProController._from_config(
         _SwitchGamepadConfig(
             adapter=adapter,
-            key_store_path=key_store_path,
+            profile_path=profile_path,
             report_period_us=report_period_us,
             controller_colors=controller_colors,
         ),
@@ -41,7 +41,7 @@ def make_joycon_l(
     *,
     transport: HidDeviceTransport,
     adapter: str | None = None,
-    key_store_path: str | None = None,
+    profile_path: str | None = None,
     report_period_us: int | None = None,
     controller_colors: ControllerColors | None = None,
     diagnostics: DiagnosticsConfig | None = None,
@@ -50,7 +50,7 @@ def make_joycon_l(
     return JoyConL._from_config(
         _SwitchGamepadConfig(
             adapter=adapter,
-            key_store_path=key_store_path,
+            profile_path=profile_path,
             report_period_us=report_period_us,
             controller_colors=controller_colors,
             profile=JoyConLeftProfile(),
@@ -64,7 +64,7 @@ def make_joycon_r(
     *,
     transport: HidDeviceTransport,
     adapter: str | None = None,
-    key_store_path: str | None = None,
+    profile_path: str | None = None,
     report_period_us: int | None = None,
     controller_colors: ControllerColors | None = None,
     diagnostics: DiagnosticsConfig | None = None,
@@ -73,7 +73,7 @@ def make_joycon_r(
     return JoyConR._from_config(
         _SwitchGamepadConfig(
             adapter=adapter,
-            key_store_path=key_store_path,
+            profile_path=profile_path,
             report_period_us=report_period_us,
             controller_colors=controller_colors,
             profile=JoyConRightProfile(),
@@ -87,7 +87,7 @@ def make_direct_pro_controller(
     *,
     transport: HidDeviceTransport,
     adapter: str | None = None,
-    key_store_path: str | None = None,
+    profile_path: str | None = None,
     controller_colors: ControllerColors | None = None,
     diagnostics: DiagnosticsConfig | None = None,
 ) -> DirectProController:
@@ -95,7 +95,7 @@ def make_direct_pro_controller(
     return DirectProController._from_config(
         _SwitchGamepadConfig(
             adapter=adapter,
-            key_store_path=key_store_path,
+            profile_path=profile_path,
             controller_colors=controller_colors,
         ),
         diagnostics=diagnostics,
@@ -107,7 +107,7 @@ def make_direct_joycon_l(
     *,
     transport: HidDeviceTransport,
     adapter: str | None = None,
-    key_store_path: str | None = None,
+    profile_path: str | None = None,
     controller_colors: ControllerColors | None = None,
     diagnostics: DiagnosticsConfig | None = None,
 ) -> DirectJoyConL:
@@ -115,7 +115,7 @@ def make_direct_joycon_l(
     return DirectJoyConL._from_config(
         _SwitchGamepadConfig(
             adapter=adapter,
-            key_store_path=key_store_path,
+            profile_path=profile_path,
             controller_colors=controller_colors,
             profile=JoyConLeftProfile(),
         ),
@@ -128,7 +128,7 @@ def make_direct_joycon_r(
     *,
     transport: HidDeviceTransport,
     adapter: str | None = None,
-    key_store_path: str | None = None,
+    profile_path: str | None = None,
     controller_colors: ControllerColors | None = None,
     diagnostics: DiagnosticsConfig | None = None,
 ) -> DirectJoyConR:
@@ -136,7 +136,7 @@ def make_direct_joycon_r(
     return DirectJoyConR._from_config(
         _SwitchGamepadConfig(
             adapter=adapter,
-            key_store_path=key_store_path,
+            profile_path=profile_path,
             controller_colors=controller_colors,
             profile=JoyConRightProfile(),
         ),

swbt/diagnostics.py

@@ -112,7 +112,7 @@ class DiagnosticsRecorder:
         return diagnostics_event
 
     def record_report_tx(self, *, report_id: int, reason: str) -> DiagnosticsEvent:
-        """Record one sent report and increment its counter."""
+        """Record one transport-accepted report and increment its counter."""
         counter = self._report_counters.get(report_id, 0) + 1
         self._report_counters[report_id] = counter
         return self.record_event(
@@ -139,9 +139,7 @@ class DiagnosticsRecorder:
         self,
         *,
         adapter: str,
-        key_store_exists: bool | None = None,
-        key_store_path: str | None = None,
-        key_store_previous_exists: bool | None = None,
+        profile_path: str | None = None,
     ) -> DiagnosticsEvent:
         """Record environment metadata for one diagnostics run."""
         fields: dict[str, object] = {
@@ -150,12 +148,8 @@ class DiagnosticsRecorder:
             "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
+        if profile_path is not None:
+            fields["profile_path"] = profile_path
         return self.record_event(
             "run_metadata",
             **fields,

swbt/errors.py

@@ -63,6 +63,43 @@ class InvalidKeyStoreError(SwbtError):
     """Raised when a key store has an unsupported or invalid shape."""
 
 
+class InvalidProfileError(SwbtError):
+    """Raised when a pairing profile is invalid or unsupported."""
+
+
+class ProfileControllerMismatchError(InvalidProfileError):
+    """Raised when a profile belongs to a different concrete controller kind."""
+
+    def __init__(
+        self,
+        *,
+        expected_controller_kind: str,
+        actual_controller_kind: str,
+    ) -> None:
+        """Initialize expected and actual profile controller kinds."""
+        message = (
+            "profile controller_kind mismatch: "
+            f"expected {expected_controller_kind!r}, got {actual_controller_kind!r}"
+        )
+        super().__init__(message)
+        self.expected_controller_kind = expected_controller_kind
+        self.actual_controller_kind = actual_controller_kind
+
+
+class AdapterIdentityRecoveryRequired(SwbtError):  # noqa: N818
+    """Raised when a volatile write may have changed the adapter identity."""
+
+    def __init__(self, *, target_address: str, stage: str) -> None:
+        """Initialize the target and failure stage requiring physical recovery."""
+        message = (
+            "adapter identity preparation became uncertain after write started; "
+            "unplug and reconnect the USB dongle before retrying"
+        )
+        super().__init__(message)
+        self.target_address = target_address
+        self.stage = stage
+
+
 class ProtocolError(SwbtError):
     """Raised when protocol bytes cannot be parsed or produced."""
 

swbt/gamepad/_config.py

@@ -13,7 +13,7 @@ class _SwitchGamepadConfig:
 
     Attributes:
         adapter: Bumble adapter moniker, such as ``"usb:0"``.
-        key_store_path: Path used by the default transport to persist pairing keys.
+        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.
@@ -21,7 +21,7 @@ class _SwitchGamepadConfig:
     """
 
     adapter: str | None = None
-    key_store_path: 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
@@ -60,14 +60,14 @@ class _ControllerSpec:
         self,
         *,
         adapter: str | None,
-        key_store_path: 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,
-            key_store_path=key_store_path,
+            profile_path=profile_path,
             profile=self.profile,
             report_period_us=report_period_us,
             controller_colors=controller_colors,
@@ -79,7 +79,7 @@ class _RuntimeConfig:
     """Normalized internal configuration for ControllerRuntime."""
 
     adapter: str | None
-    key_store_path: str | None
+    profile_path: str | None
     profile: ControllerProfile
     report_period_us: int
     device_name: str
@@ -93,7 +93,7 @@ class _RuntimeConfig:
             raise InvalidInputError(msg)
         return cls(
             adapter=config.adapter,
-            key_store_path=config.key_store_path,
+            profile_path=config.profile_path,
             profile=config.profile,
             report_period_us=config.report_period_us,
             device_name=config.device_name,

swbt/gamepad/connection.py

@@ -58,7 +58,7 @@ class ConnectionWorkflow:
     diagnostics: DiagnosticsRecorder
     ensure_open: EnsureOpen
     get_transport: TransportProvider
-    key_store_path: str | None
+    profile_path: str | None
     pair: PairWithTimeout
     set_connection_state: StateSetter
     transport_was_injected: bool
@@ -71,10 +71,10 @@ class ConnectionWorkflow:
         """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:
+        if self.profile_path is None and not self.transport_was_injected:
             self.diagnostics.record_event(
-                "reconnect_key_store_unavailable",
-                reason="key_store_path_none",
+                "reconnect_profile_unavailable",
+                reason="profile_path_none",
                 route="active_reconnect",
             )
         peers = await transport.list_bonded_peers()
@@ -113,11 +113,19 @@ class ConnectionWorkflow:
             route="active_reconnect",
         )
         try:
-            await transport.connect_bonded_peer(
-                peer.address,
-                connect_timeout=timeout,
-            )
-            await self.wait_for_connected(timeout)
+
+            async def reconnect_and_wait() -> None:
+                await transport.connect_bonded_peer(
+                    peer.address,
+                    connect_timeout=timeout,
+                )
+                await self.wait_for_connected(None)
+
+            if timeout is None:
+                await reconnect_and_wait()
+            else:
+                async with asyncio.timeout(timeout):
+                    await reconnect_and_wait()
         except TimeoutError:
             self.diagnostics.record_event(
                 "active_reconnect_result",
@@ -172,6 +180,8 @@ class ConnectionWorkflow:
             await self.pair(timeout)
         except ConnectionTimeoutError:
             return ConnectionResult(route="pairing", status="timeout")
+        except ConnectionFailedError:
+            return ConnectionResult(route="pairing", status="failed")
         return ConnectionResult(route="pairing", status="connected")
 
     def _transport(self) -> HidDeviceTransport: