swbt-python 0.5.3__py3-none-any.whl → 0.6.0__py3-none-any.whl

swbt/gamepad/interface.py

@@ -121,11 +121,11 @@ class SwitchGamepad(ABC):
         await self._runtime.open()
 
     async def pair(self, timeout: float | None = None) -> None:  # noqa: ASYNC109
-        """Start pairing advertising and wait until the controller is ready for input.
+        """Start pairing and wait until the controller can accept normal input.
 
         Args:
-            timeout: Maximum seconds for link connection and protocol initialization.
-                ``None`` waits without a deadline.
+            timeout: Maximum seconds for link connection, protocol initialization,
+                and normal-input readiness. ``None`` waits without a deadline.
 
         Raises:
             ConnectionTimeoutError: The timeout elapsed before a connection completed.
@@ -134,15 +134,15 @@ class SwitchGamepad(ABC):
         await self._runtime.pair(timeout=timeout)
 
     async def reconnect(self, timeout: float | None = None) -> None:  # noqa: ASYNC109
-        """Reconnect with exactly one bonded peer and raise on failure.
+        """Reconnect with one bonded peer and wait until normal input can begin.
 
         Args:
-            timeout: Maximum seconds for the active reconnect attempt. ``None`` uses
-                the transport default.
+            timeout: Maximum seconds for the active reconnect attempt and
+                normal-input readiness. ``None`` uses the transport default.
 
         Raises:
             ConnectionFailedError: No single bonded peer was available or reconnect failed.
-            ConnectionTimeoutError: The active reconnect attempt timed out.
+            ConnectionTimeoutError: The reconnect or normal-input readiness timed out.
             InvalidKeyStoreError: The key store cannot identify one current peer.
         """
         await self._runtime.reconnect(timeout=timeout)
@@ -154,11 +154,12 @@ class SwitchGamepad(ABC):
         """Try active reconnect with exactly one bonded peer.
 
         Args:
-            timeout: Maximum seconds for the active reconnect attempt. ``None`` uses
-                the transport default.
+            timeout: Maximum seconds for the active reconnect attempt and
+                normal-input readiness. ``None`` uses the transport default.
 
         Returns:
-            Reconnect route, status, selected peer, and peer count.
+            Reconnect route, status, selected peer, and peer count. ``connected``
+            means that normal input can begin.
 
         Raises:
             InvalidKeyStoreError: The key store cannot identify one current peer.
@@ -171,7 +172,7 @@ class SwitchGamepad(ABC):
         timeout: float | None = None,  # noqa: ASYNC109
         allow_pairing: bool = False,
     ) -> None:
-        """Connect using bonded reconnect first, then optional pairing fallback.
+        """Connect by bonded reconnect or pairing and wait for normal-input readiness.
 
         Args:
             timeout: Maximum seconds for each connection attempt. ``None`` uses the
@@ -199,7 +200,8 @@ class SwitchGamepad(ABC):
             allow_pairing: If ``True``, run pairing when no bonded peer is available.
 
         Returns:
-            Route and status chosen by reconnect or pairing fallback.
+            Route and status chosen by reconnect or pairing fallback. ``connected``
+            means that normal input can begin.
 
         Raises:
             InvalidKeyStoreError: The key store cannot identify one current peer.
@@ -375,7 +377,8 @@ class PeriodicSwitchGamepad(SwitchGamepad):
             diagnostics: Optional diagnostics configuration for trace output.
 
         Returns:
-            The protocol-ready periodic controller. The caller owns its lifetime.
+            A periodic controller ready to accept normal input. The caller owns
+            its lifetime.
 
         Raises:
             ValueError: ``local_address`` is invalid.
@@ -440,7 +443,8 @@ class DirectSwitchGamepad(SwitchGamepad):
             diagnostics: Optional diagnostics configuration for trace output.
 
         Returns:
-            The protocol-ready direct controller. The caller owns its lifetime.
+            A direct controller ready to accept normal input. The caller owns
+            its lifetime.
 
         Raises:
             ValueError: ``local_address`` is invalid.

swbt/gamepad/runtime.py

@@ -2,7 +2,9 @@
 
 import asyncio
 from collections.abc import Awaitable, Callable
+from contextlib import suppress
 from dataclasses import replace
+from time import monotonic
 from typing import Literal
 
 import swbt.gamepad as gamepad_module
@@ -48,6 +50,8 @@ class ControllerRuntime:
         diagnostics: DiagnosticsConfig | None = None,
         reporting_mode: Literal["periodic", "direct"] = "periodic",
         transport: HidDeviceTransport | None = None,
+        _report_sender_monotonic_time: Callable[[], float] = monotonic,
+        _report_sender_sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
     ) -> None:
         """Create a fully initialized gamepad runtime.
 
@@ -57,6 +61,8 @@ class ControllerRuntime:
             reporting_mode: Owner of normal input report scheduling.
             transport: Optional HID transport instance. When supplied, no Bumble
                 transport is created by the constructor.
+            _report_sender_monotonic_time: Internal holdoff clock override for tests.
+            _report_sender_sleep: Internal holdoff sleep override for tests.
 
         Raises:
             InvalidInputError: ``adapter`` is omitted for the default transport.
@@ -68,6 +74,8 @@ class ControllerRuntime:
         self._reporting_mode = reporting_mode
         self._transport = transport
         self._transport_was_injected = transport is not None
+        self._report_sender_monotonic_time = _report_sender_monotonic_time
+        self._report_sender_sleep = _report_sender_sleep
         self._pairing_profile: PairingProfile | None = None
         self._state_store = InputStateStore()
         self._diagnostics = DiagnosticsRecorder(
@@ -94,6 +102,7 @@ class ControllerRuntime:
         self._report_loop: ReportLoop | None = None
         self._report_sender: ReportSender | None = None
         self._protocol_handshake: ProtocolHandshake | None = None
+        self._input_readiness_task: asyncio.Task[None] | None = None
         self._input_operation_lock = asyncio.Lock()
         self._lifecycle_lock = asyncio.Lock()
         self._connected_event = asyncio.Event()
@@ -139,6 +148,8 @@ class ControllerRuntime:
                     ),
                     session=self._protocol_session,
                     diagnostics=self._diagnostics,
+                    monotonic_time=self._report_sender_monotonic_time,
+                    _sleep=self._report_sender_sleep,
                 )
                 self._report_sender = report_sender
                 self._connection_state = "opened"
@@ -161,14 +172,14 @@ class ControllerRuntime:
         self._configured_device_info_bluetooth_address = None
 
     async def pair(self, timeout: float | None = None) -> None:  # noqa: ASYNC109
-        """Start pairing advertising and wait until the controller is ready for input.
+        """Start pairing and wait until the controller can accept normal input.
 
         Args:
-            timeout: Maximum seconds for link connection and protocol initialization.
-                ``None`` waits without a deadline.
+            timeout: Maximum seconds for link connection, protocol initialization,
+                and normal-input readiness. ``None`` waits without a deadline.
 
         Raises:
-            ConnectionTimeoutError: The deadline elapsed before protocol readiness.
+            ConnectionTimeoutError: The deadline elapsed before normal-input readiness.
             ConnectionFailedError: Protocol initialization or the link failed.
             ClosedError: The transport was unavailable after opening.
         """
@@ -186,7 +197,7 @@ class ControllerRuntime:
                 raise ClosedError(msg)
             await self._transport.start_advertising()
             self._configure_device_info_bluetooth_address(self._transport)
-            await self._wait_for_protocol_ready(None)
+            await self._wait_for_input_ready(None)
 
         try:
             if timeout is None:
@@ -194,6 +205,9 @@ class ControllerRuntime:
             else:
                 async with asyncio.timeout(timeout):
                     await advertise_and_wait()
+        except asyncio.CancelledError:
+            await self._stop_input_readiness_wait()
+            raise
         except TimeoutError as error:
             msg = "connection timed out"
             connection_error = ConnectionTimeoutError(msg)
@@ -204,7 +218,7 @@ class ControllerRuntime:
                 ),
                 player_lights=_format_optional_byte(self._protocol_session.state.player_lights),
                 report_mode=_format_optional_byte(self._protocol_session.state.report_mode),
-                stage="protocol_initialization",
+                stage=self._connection_readiness_stage(),
                 state=self._connection_state,
                 timeout=timeout,
             )
@@ -216,15 +230,15 @@ class ControllerRuntime:
             raise
 
     async def reconnect(self, timeout: float | None = None) -> None:  # noqa: ASYNC109
-        """Reconnect with exactly one bonded peer and raise on failure.
+        """Reconnect with one bonded peer and wait until normal input can begin.
 
         Args:
-            timeout: Maximum seconds for the active reconnect attempt. ``None`` uses
-                the transport default.
+            timeout: Maximum seconds for the active reconnect attempt and
+                normal-input readiness. ``None`` uses the transport default.
 
         Raises:
             ConnectionFailedError: No single bonded peer was available or reconnect failed.
-            ConnectionTimeoutError: The active reconnect attempt timed out.
+            ConnectionTimeoutError: The reconnect or normal-input readiness timed out.
         """
         result = await self.try_reconnect(timeout=timeout)
         self._raise_if_connection_failed(result)
@@ -236,8 +250,8 @@ class ControllerRuntime:
         """Try active reconnect with exactly one bonded peer.
 
         Args:
-            timeout: Maximum seconds for the active reconnect attempt. ``None`` uses
-                the transport default.
+            timeout: Maximum seconds for the active reconnect attempt and
+                normal-input readiness. ``None`` uses the transport default.
 
         Returns:
             ConnectionResult: Reconnect route, status, selected peer, and peer count.
@@ -308,6 +322,7 @@ class ControllerRuntime:
             )
         except asyncio.CancelledError as error:
             if _current_task_is_cancelling():
+                await self._stop_input_readiness_wait()
                 raise
             return await self._record_active_reconnect_transport_error(
                 error,
@@ -406,6 +421,7 @@ class ControllerRuntime:
                     except Exception as error:  # noqa: BLE001
                         self._diagnostics.record_error(error, recoverable=True)
                 await self._stop_protocol_handshake()
+                await self._stop_input_readiness_wait()
                 if self._report_loop is not None:
                     await self._report_loop.stop()
                 self._disconnect_event.clear()
@@ -820,7 +836,7 @@ class ControllerRuntime:
 
     async def _wait_for_reconnect_connected(self, *, max_wait: float | None) -> None:
         try:
-            await self._wait_for_protocol_ready(max_wait)
+            await self._wait_for_input_ready(max_wait)
         except TimeoutError as error:
             self._diagnostics.record_event(
                 "connection_timeout",
@@ -830,13 +846,13 @@ class ControllerRuntime:
                 player_lights=_format_optional_byte(self._protocol_session.state.player_lights),
                 report_mode=_format_optional_byte(self._protocol_session.state.report_mode),
                 route="active_reconnect",
-                stage="protocol_initialization",
+                stage=self._connection_readiness_stage(),
                 state=self._connection_state,
                 timeout=max_wait,
             )
             raise TimeoutError from error
 
-    async def _wait_for_protocol_ready(self, max_wait: float | None) -> None:
+    async def _wait_for_input_ready(self, max_wait: float | None) -> None:
         if max_wait is None:
             await self._connection_attempt_event.wait()
         else:
@@ -844,9 +860,14 @@ class ControllerRuntime:
                 await self._connection_attempt_event.wait()
         if self._connected_event.is_set():
             return
-        msg = "protocol initialization failed"
+        msg = "connection initialization failed"
         raise ConnectionFailedError(msg) from self._connection_attempt_error
 
+    def _connection_readiness_stage(self) -> str:
+        if self._protocol_session.state.protocol_ready:
+            return "input_readiness"
+        return "protocol_initialization"
+
     def _record_disconnect_request_result(self, result: DisconnectRequestResult) -> None:
         fields: dict[str, object] = {"status": result.status}
         if result.channels:
@@ -917,6 +938,15 @@ class ControllerRuntime:
         if handshake is not None:
             await handshake.stop()
 
+    async def _stop_input_readiness_wait(self) -> None:
+        task = self._input_readiness_task
+        self._input_readiness_task = None
+        if task is None or task is asyncio.current_task():
+            return
+        task.cancel()
+        with suppress(asyncio.CancelledError):
+            await task
+
     def _start_periodic_report_loop(self) -> None:
         if self._transport is None or self._report_loop is not None:
             return
@@ -950,12 +980,7 @@ class ControllerRuntime:
             return
         if self._connected_event.is_set():
             return
-        self._connection_state = "connected"
-        self._connected_event.set()
-        self._connection_attempt_event.set()
         self._protocol_handshake = None
-        if self._reporting_mode == "periodic":
-            self._start_periodic_report_loop()
         session_state = self._protocol_session.state
         self._diagnostics.record_event(
             "protocol_ready",
@@ -965,6 +990,50 @@ class ControllerRuntime:
             route=self._connection_route,
             observed_subcommands=_format_subcommands(session_state.observed_subcommands),
         )
+        if self._reporting_mode == "direct":
+            self._publish_input_ready()
+            return
+        if self._input_readiness_task is not None:
+            return
+        self._input_readiness_task = asyncio.create_task(
+            self._complete_periodic_input_readiness(),
+            name="swbt-input-readiness",
+        )
+
+    async def _complete_periodic_input_readiness(self) -> None:
+        task = asyncio.current_task()
+        sender = self._require_report_sender()
+        try:
+            await sender.wait_until_automatic_input_ready()
+            if (
+                self._close_in_progress
+                or self._connection_attempt_event.is_set()
+                or self._report_sender is not sender
+            ):
+                return
+            self._start_periodic_report_loop()
+            self._publish_input_ready()
+        except asyncio.CancelledError:
+            raise
+        except Exception as error:  # noqa: BLE001
+            if not self._close_in_progress:
+                self._record_protocol_initialization_failure(error)
+        finally:
+            if self._input_readiness_task is task:
+                self._input_readiness_task = None
+
+    def _publish_input_ready(self) -> None:
+        if self._connected_event.is_set() or self._connection_attempt_event.is_set():
+            return
+        self._connection_state = "connected"
+        self._connected_event.set()
+        self._connection_attempt_event.set()
+        self._diagnostics.record_event(
+            "input_ready",
+            profile_kind=self._controller_profile.kind.value,
+            reporting_mode=self._reporting_mode,
+            route=self._connection_route,
+        )
 
     async def _fail_protocol_initialization(self, error: Exception) -> None:
         if self._protocol_handshake is not None:
@@ -987,7 +1056,7 @@ class ControllerRuntime:
             profile_kind=self._controller_profile.kind.value,
             report_mode=_format_optional_byte(self._protocol_session.state.report_mode),
             route=self._connection_route,
-            stage="protocol_initialization",
+            stage=self._connection_readiness_stage(),
         )
         self._diagnostics.record_error(error, recoverable=False)
 
@@ -999,7 +1068,7 @@ class ControllerRuntime:
             and not self._connection_attempt_event.is_set()
             and not self._close_in_progress
         ):
-            msg = "disconnected before protocol initialization completed"
+            msg = "disconnected before connection initialization completed"
             handshake_failure = ConnectionFailedError(msg)
             if self._protocol_handshake is not None:
                 self._protocol_handshake.fail(handshake_failure)
@@ -1014,6 +1083,7 @@ class ControllerRuntime:
                 self._protocol_handshake = None
             else:
                 await self._stop_protocol_handshake()
+            await self._stop_input_readiness_wait()
             if self._report_loop is not None:
                 await self._report_loop.stop()
                 self._report_loop = None

swbt/report_loop.py

@@ -34,6 +34,7 @@ class ReportSender:
         diagnostics: DiagnosticsRecorder | None = None,
         clock_ns: Callable[[], int] = monotonic_ns,
         monotonic_time: Callable[[], float] = monotonic,
+        _sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
     ) -> None:
         """Create a session-scoped serialized report sender."""
         self._transport = transport
@@ -42,6 +43,7 @@ class ReportSender:
         self._diagnostics = diagnostics
         self._clock_ns = clock_ns
         self._monotonic_time = monotonic_time
+        self._sleep = _sleep
         self._timer = 0
         self._send_lock = asyncio.Lock()
         self._automatic_input_holdoff_until = 0.0
@@ -80,6 +82,15 @@ class ReportSender:
             await self._send_input_locked(state, reason=reason)
             return True
 
+    async def wait_until_automatic_input_ready(self) -> None:
+        """Wait until automatic input is no longer held off by an accepted reply."""
+        while True:
+            async with self._send_lock:
+                remaining = self._automatic_input_holdoff_until - self._monotonic_time()
+                if remaining <= 0:
+                    return
+            await self._sleep(remaining)
+
     async def send_subcommand_reply(self, build_report: ReplyBuilder) -> bytes:
         """Build and send a subcommand reply under the shared send lock."""
         async with self._send_lock:

{swbt_python-0.5.3.dist-info → swbt_python-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swbt-python
-Version: 0.5.3
+Version: 0.6.0
 Summary: Python library for presenting an NX-compatible virtual Bluetooth HID input device.
 Keywords: bluetooth,bluetooth-hid,controller,gamepad,hid,nx
 Author: niart120
@@ -14,14 +14,14 @@ Classifier: Operating System :: MacOS
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Dist: bumble==0.0.233
 Maintainer: niart120
 Maintainer-email: niart120 <38847256+niart120@users.noreply.github.com>
-Requires-Python: >=3.12
+Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 
 # swbt-python
@@ -32,7 +32,7 @@ NX 向けの仮想 Bluetooth HID 入力デバイスを Python から扱うため
 
 ## 必要なもの
 
-- Python 3.12 以降
+- Python 3.13 以降
 - uv
 - Bumble が利用可能な専用 USB Bluetooth ドングル
 

{swbt_python-0.5.3.dist-info → swbt_python-0.6.0.dist-info}/RECORD

@@ -7,10 +7,10 @@ swbt/gamepad/_config.py,sha256=VjYrR4erPhEohjZ1Pw5ElxryNEa8dRfsKhz2EsjpEUs,2050
 swbt/gamepad/connection.py,sha256=8EUeKYvdV_n1OIq11MFAVNhKmIbJHUoijaK6xUx6Y4g,753
 swbt/gamepad/constants.py,sha256=gDesRFvVxZ3SMSiP4qzd42em_Dt9M5hIu3-2exgKEus,84
 swbt/gamepad/controllers.py,sha256=G6EMi82F_36wSi2pm5QMFLJSZSakRogVcDeygqJJ8gI,7487
-swbt/gamepad/interface.py,sha256=quHOOj5nWzBz_W3qYMBEWglo-3zR_I9zxNqlA7HznGI,17525
+swbt/gamepad/interface.py,sha256=HWABzdzrVPAumTZPOrUjiku-mKvAPIhqTE-pvqAIgSU,17793
 swbt/gamepad/output.py,sha256=NeOp-NwYshEkuelge_POwk_i7orqOQc4SXm9t9Njs1s,5361
 swbt/gamepad/protocol_handshake.py,sha256=9vAdE0PIpSpWk9oXhStOTq0XxDlE8DejE1SLBh21rx4,6217
-swbt/gamepad/runtime.py,sha256=7QrhoqyHx5jy9cjnlNUlJ4xxnQp5_vxfE2SVGZ1Dvtk,44102
+swbt/gamepad/runtime.py,sha256=HVuhQxPtpVpcyxVo2RnWOM5Vkmn2kc9NjhJ9PPWwG4o,47170
 swbt/gamepad/transport_factory.py,sha256=0eiC-HqtNG0CJuHR8TlSPWtpInW03A4ojnBccqpryN0,921
 swbt/imu.py,sha256=sT1_MsYECQlQ-pSfayD8gojD9l3w9zEtOI3xP1IovQM,4237
 swbt/input.py,sha256=7gv75lzrcmoV8Sijz7f1pvsheRrmUi_TCIMW3DjUVjw,22275
@@ -30,7 +30,7 @@ swbt/protocol/session.py,sha256=SVkF0jaJPbnKCAWswRQsrdoCxZwjHPEMz4lktVBcXc4,4811
 swbt/protocol/spi.py,sha256=buKyNYYOHOSYbpVh3Wa2968FL4VIO_43QcSXNowNfJs,2594
 swbt/protocol/subcommand.py,sha256=NRtp9-lB8IBimC0kO8oyJnel_qSSPx65XlmGWTARB0E,8662
 swbt/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-swbt/report_loop.py,sha256=jEnwlxdWQgPwbIXvJfyhgMaJdrGYLNYzlZNotOMKiKw,7853
+swbt/report_loop.py,sha256=zGaKStCsupzkmSTF8YZOL9H2DbH1Nf15yHtI3POJiTY,8350
 swbt/state_store.py,sha256=jE1TeNpqynbVpxFp0Xt3m1Dfl1LUKR-uqV4f14qntuM,1402
 swbt/transport/__init__.py,sha256=b_Vqsg0k_g7XclN9XHQrcJxqCwGIklxG5NqzISal4_I,68
 swbt/transport/_adapter_identity.py,sha256=xOECQBlGAZJoyKrfxrIPt88kXoksHWmWzzVo1-x5XmA,6621
@@ -46,8 +46,8 @@ swbt/transport/_pairing_profile.py,sha256=95tISeYHnllHfFpNs0oBsaYb5uAffXfi9eFkjb
 swbt/transport/base.py,sha256=eI0hs1wTwJf2ppzqda4ok-tUXF1hE9dwpb0p-lpvwmo,5163
 swbt/transport/bumble.py,sha256=VufUEo4aUeVebSFvZPJaVe_G7nNz5fKQMCbjgqmBbRs,33414
 swbt/transport/fake.py,sha256=4O5zlsg1TO61Ai54FGCn_xM8TEA9yi938Fso-XHdh1w,12891
-swbt_python-0.5.3.dist-info/licenses/LICENSE,sha256=FzzUoYjuIh5DzpeaujIbDUTylYnyzcHRVU-_ZMyowyk,1065
-swbt_python-0.5.3.dist-info/WHEEL,sha256=uOqnPWqgFlbov4NeTCercq7cBQ2UN7xh5fiW55lOnAg,81
-swbt_python-0.5.3.dist-info/entry_points.txt,sha256=YYQc7VgoSy74iZ6s8Qr6iJpnvFoDpp8G4-v0KJH5TGo,48
-swbt_python-0.5.3.dist-info/METADATA,sha256=W59IobyxaCz0_nIchUTIqNv24T9XjR9d7CuarGeItW0,5902
-swbt_python-0.5.3.dist-info/RECORD,,
+swbt_python-0.6.0.dist-info/licenses/LICENSE,sha256=FzzUoYjuIh5DzpeaujIbDUTylYnyzcHRVU-_ZMyowyk,1065
+swbt_python-0.6.0.dist-info/WHEEL,sha256=uOqnPWqgFlbov4NeTCercq7cBQ2UN7xh5fiW55lOnAg,81
+swbt_python-0.6.0.dist-info/entry_points.txt,sha256=YYQc7VgoSy74iZ6s8Qr6iJpnvFoDpp8G4-v0KJH5TGo,48
+swbt_python-0.6.0.dist-info/METADATA,sha256=uYO6HjCv9WQ4YTzUKV4gIn-L4LvMOeVWAzEh37GL6RA,5902
+swbt_python-0.6.0.dist-info/RECORD,,