sdk/python: adopt remaining fixes from PR #1 (nrathaus)

PR #1 was opened against the original root-level scripts in 2023 and
no longer applies cleanly to the refactored sdk/python/ tree, but two
of its fixes are still real and weren't ported during the refactor.

- ClientSettings: connect_retries (default 5) and connect_backoff_seconds
  (default 1.0). Mirrors the discovery_retries / discovery_backoff_seconds
  pattern already in place.
- ClientSocketManager.connect(): wrap the connect call in a retry loop
  with the configured backoff. Bluetooth connect() is genuinely flaky
  in practice; the original PR did this with a hardcoded attempt > 5
  guard, here it is config-driven and logs per attempt. Last error is
  preserved as the raised BluetoothServerError's cause.
- install_dependencies.sh + sdk/python/README: install pybluez from
  github.com/pybluez/pybluez instead of PyPI. The PyPI distribution
  hasn't been updated in years and fails to build on Python 3.10+.

Not adopted from PR #1:
- Binary 2-byte little-endian length framing — caps payloads at 64KB
  and would regress the current decimal-string framing on both sides.
- bare-Exception catches and sys.exit(0) on failure — the current
  module raises typed BluetoothClientError / BluetoothServerError,
  which is strictly better for callers and tests.

Smoke-tested the retry path with a stubbed bluetooth module (3 attempts
with 0.01s backoff completed in ~20ms; each attempt logged; final
exception carried the BluetoothError cause).

Author: claude

sdk/python/README.md

@@ -21,6 +21,14 @@ python3 run_client.py      # sender
 
 Run from within `sdk/python` or adjust your `PYTHONPATH` if launching elsewhere.
 
+> **PyBluez install note.** PyPI's `pybluez` package hasn't been updated
+> in years and no longer builds on Python 3.10+. Install from the GitHub
+> source instead (the helper script does this for you):
+>
+> ```bash
+> sudo python3 -m pip install git+https://github.com/pybluez/pybluez.git
+> ```
+
 ## Tests
 
 ```bash
@@ -32,7 +40,7 @@ pytest tests/
 
 - Update `bluetooth_service/config.py` (`ServerSettings`) for server behavior.
 - Update `bluetooth_service/client_config.py` (`ClientSettings`) for discovery,
-  retries, and payload source.
+  retries (both `discovery_retries` and `connect_retries`), and payload source.
 - Swap serializers/sinks/sources by injecting your own implementations when
   constructing `BluetoothServer` / `BluetoothClient`.
 

sdk/python/bluetooth_service/client_config.py

@@ -16,6 +16,10 @@ class ClientSettings:
     buffer_size: int = 1024
     discovery_retries: int = 3
     discovery_backoff_seconds: float = 0.5
+    # Bluetooth connect() is flaky in practice — retry the connect step
+    # with a short backoff before giving up. (Adapted from PR #1.)
+    connect_retries: int = 5
+    connect_backoff_seconds: float = 1.0
     resend_empty_message: str = "EmptyBufferResend"
     resend_corrupt_message: str = "CorruptedBufferResend"
     delimiter_missing_message: str = "DelimiterMissingBufferResend"

sdk/python/bluetooth_service/client_socket.py

@@ -47,26 +47,45 @@ def connect(self) -> None:
         if not self._service_info:
             raise BluetoothServerError("Service discovery must run before connect")
 
-        try:
-            self._socket = BluetoothSocket(RFCOMM)
-            if self._settings.connect_timeout is not None:
-                self._socket.settimeout(self._settings.connect_timeout)
-            endpoint = (self._service_info["host"], self._service_info["port"])
-            logger.info("Connecting to %s:%s", *endpoint)
-            self._socket.connect(endpoint)
-            logger.info("Connected to %s", self._service_info["name"])
-        except (BluetoothError, OSError) as exc:
-            if self._socket is not None:
-                try:
-                    self._socket.close()
-                except BluetoothError as close_exc:
-                    logger.warning("Failed to close socket after connect error: %s", close_exc)
-                finally:
-                    self._socket = None
-            raise BluetoothServerError("Unable to connect to Bluetooth service", cause=exc)
-        finally:
-            if self._socket is not None:
+        endpoint = (self._service_info["host"], self._service_info["port"])
+        retries = max(1, self._settings.connect_retries)
+        last_exc: Optional[BaseException] = None
+
+        for attempt in range(1, retries + 1):
+            try:
+                self._socket = BluetoothSocket(RFCOMM)
+                if self._settings.connect_timeout is not None:
+                    self._socket.settimeout(self._settings.connect_timeout)
+                logger.info(
+                    "Connecting to %s:%s (attempt %s/%s)",
+                    *endpoint,
+                    attempt,
+                    retries,
+                )
+                self._socket.connect(endpoint)
+                logger.info("Connected to %s", self._service_info["name"])
                 self._socket.settimeout(None)
+                return
+            except (BluetoothError, OSError) as exc:
+                last_exc = exc
+                logger.warning(
+                    "Connect attempt %s/%s to %s:%s failed: %s",
+                    attempt,
+                    retries,
+                    *endpoint,
+                    exc,
+                )
+                if self._socket is not None:
+                    try:
+                        self._socket.close()
+                    except BluetoothError as close_exc:
+                        logger.warning("Failed to close socket after connect error: %s", close_exc)
+                    finally:
+                        self._socket = None
+                if attempt < retries:
+                    time.sleep(self._settings.connect_backoff_seconds)
+
+        raise BluetoothServerError("Unable to connect to Bluetooth service", cause=last_exc)
 
     def send(self, payload: bytes) -> None:
         if not self._socket:

sdk/python/scripts/install_dependencies.sh

@@ -20,7 +20,11 @@ apt-get install -y \
   blueman
 
 python3 -m pip install --upgrade pip
-python3 -m pip install pybluez pytest
+# pybluez on PyPI hasn't been updated in years and fails to build on
+# modern Python (3.10+). Install from the GitHub source instead — this
+# is the workaround maintained by the pybluez project itself. (PR #1.)
+python3 -m pip install pytest
+python3 -m pip install git+https://github.com/pybluez/pybluez.git
 
 echo "Dependencies installed. You can now run run_server.py and run_client.py"