python-homely 0.1.2__tar.gz → 0.1.3__tar.gz

{python_homely-0.1.2/src/python_homely.egg-info → python_homely-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-homely
-Version: 0.1.2
+Version: 0.1.3
 Summary: Async Python client for the Homely cloud API, built for Home Assistant but usable anywhere.
 Author: Ludvik Blichfeldt Rød
 License-Expression: MIT

{python_homely-0.1.2 → python_homely-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-homely"
-version = "0.1.2"
+version = "0.1.3"
 description = "Async Python client for the Homely cloud API, built for Home Assistant but usable anywhere."
 readme = "README.md"
 requires-python = ">=3.12"

{python_homely-0.1.2 → python_homely-0.1.3}/src/homely/__init__.py

@@ -1,6 +1,6 @@
 """Reusable Homely client package extracted from the integration."""
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 
 from .client import (
     BASE_URL,
@@ -16,7 +16,12 @@ from .exceptions import (
     HomelyWebSocketError,
 )
 from .models import TokenEndpointResult, TokenResponse
-from .websocket import HomelyWebSocket
+from .websocket import (
+    WEBSOCKET_STATUS_OPTIONS,
+    HomelyWebSocket,
+    WebSocketConnectionState,
+    normalize_websocket_status,
+)
 
 __all__ = [
     "__version__",
@@ -24,6 +29,7 @@ __all__ = [
     "REQUEST_TIMEOUT",
     "HomelyClient",
     "HomelyWebSocket",
+    "WebSocketConnectionState",
     "HomelyError",
     "HomelyConnectionError",
     "HomelyAuthError",
@@ -31,5 +37,7 @@ __all__ = [
     "HomelyWebSocketError",
     "TokenEndpointResult",
     "TokenResponse",
+    "WEBSOCKET_STATUS_OPTIONS",
     "auth_header_value",
+    "normalize_websocket_status",
 ]

{python_homely-0.1.2 → python_homely-0.1.3}/src/homely/websocket.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 import asyncio
 import logging
 from collections.abc import Callable
+from dataclasses import dataclass
 from typing import Any
 from urllib.parse import urlencode
 
@@ -12,6 +13,25 @@ import aiohttp
 from .exceptions import HomelyWebSocketError
 
 _LOGGER = logging.getLogger(__name__)
+WEBSOCKET_STATUS_OPTIONS = (
+    "not_initialized",
+    "connecting",
+    "connected",
+    "disconnected",
+    "unknown",
+)
+_WEBSOCKET_STATUS_OPTION_SET = frozenset(WEBSOCKET_STATUS_OPTIONS)
+
+
+@dataclass(frozen=True)
+class WebSocketConnectionState:
+    """Normalized websocket status shared across integrations and tooling."""
+
+    connected: bool
+    reported_status: str
+    effective_status: str
+    reason: str | None
+    status_mismatch: bool
 
 
 def _log_identifier(value: str | int | None) -> str | None:
@@ -25,6 +45,37 @@ def _log_identifier(value: str | int | None) -> str | None:
     return f"{text[:8]}..."
 
 
+def normalize_websocket_status(value: Any) -> str:
+    """Convert websocket labels to stable enum values."""
+    if not isinstance(value, str):
+        return "unknown"
+
+    normalized = value.strip().lower().replace(" ", "_")
+    return (
+        normalized
+        if normalized in _WEBSOCKET_STATUS_OPTION_SET
+        else "unknown"
+    )
+
+
+def _socket_transport_is_connected(socket: Any | None) -> bool:
+    """Return True when the Socket.IO or Engine.IO transport is still alive."""
+    if socket is None:
+        return False
+
+    try:
+        if bool(socket.connected):
+            return True
+    except Exception:
+        pass
+
+    engineio_client = getattr(socket, "eio", None)
+    try:
+        return str(getattr(engineio_client, "state", "")).lower() == "connected"
+    except Exception:
+        return False
+
+
 class HomelyWebSocket:
     """WebSocket client for Homely using Socket.IO."""
 
@@ -48,7 +99,7 @@ class HomelyWebSocket:
         self.socket: Any | None = None
         self._is_closing = False
         self._reconnect_task: asyncio.Task[None] | None = None
-        self._reconnect_interval = 300
+        self._reconnect_interval = self._reconnect_interval_for_attempt(1)
         self._reconnect_warn_every = 12
         self._status_update_callback = status_update_callback
         self._status = "Not initialized"
@@ -64,6 +115,14 @@ class HomelyWebSocket:
             return f"{base} device_id={_log_identifier(device_id)}"
         return base
 
+    def _reconnect_interval_for_attempt(self, attempt: int) -> int:
+        """Return reconnect delay for the given attempt number."""
+        if attempt <= 3:
+            return 10
+        if attempt <= 8:
+            return 60
+        return 300
+
     @property
     def websocket_url(self) -> str:
         """WebSocket base URL."""
@@ -205,6 +264,8 @@ class HomelyWebSocket:
         if self._reconnect_task and not self._reconnect_task.done():
             return
 
+        self._reconnect_interval = self._reconnect_interval_for_attempt(1)
+
         try:
             loop = asyncio.get_running_loop()
         except RuntimeError:
@@ -232,7 +293,7 @@ class HomelyWebSocket:
         self._reconnect_task = None
 
     async def _reconnect_loop(self) -> None:
-        """Try reconnect forever at fixed interval."""
+        """Reconnect with a short burst first, then slower retries."""
         attempt = 0
         while not self._is_closing:
             if self.is_connected():
@@ -245,6 +306,7 @@ class HomelyWebSocket:
                 _LOGGER.debug("WebSocket reconnect attempt %s succeeded %s", attempt, self._ctx())
                 return
 
+            self._reconnect_interval = self._reconnect_interval_for_attempt(attempt + 1)
             if attempt % self._reconnect_warn_every == 0:
                 _LOGGER.info(
                     "WebSocket reconnect attempt %s failed %s. Retrying in %s seconds",
@@ -390,15 +452,46 @@ class HomelyWebSocket:
 
     async def reconnect_with_token(self, token: str) -> None:
         """Update token and request reconnect if currently disconnected."""
-        self.update_token(token, reconnect_if_disconnected=True)
+        self.sync_token(token)
 
     def is_connected(self) -> bool:
-        """Return True if socket client reports connected."""
+        """Return True when the websocket transport looks alive."""
         try:
-            return self.socket is not None and bool(self.socket.connected)
+            return _socket_transport_is_connected(self.socket)
         except Exception:
             return False
 
+    def reported_connection_status(self) -> str:
+        """Return normalized status reported by the websocket client itself."""
+        status = normalize_websocket_status(self.status)
+        if status != "unknown" and not (
+            status == "not_initialized" and self.is_connected()
+        ):
+            return status
+        return "connected" if self.is_connected() else "disconnected"
+
+    def connection_state(self) -> WebSocketConnectionState:
+        """Return a normalized view of websocket health."""
+        reported_status = self.reported_connection_status()
+        connected = self.is_connected()
+
+        if connected:
+            effective_status = "connected"
+        elif reported_status in {"connecting", "not_initialized"}:
+            effective_status = reported_status
+        elif reported_status == "unknown":
+            effective_status = "disconnected"
+        else:
+            effective_status = "disconnected"
+
+        return WebSocketConnectionState(
+            connected=connected,
+            reported_status=reported_status,
+            effective_status=effective_status,
+            reason=self.status_reason,
+            status_mismatch=reported_status != effective_status,
+        )
+
     def update_token(self, token: str, reconnect_if_disconnected: bool = False) -> None:
         """Update token used by next connect/reconnect attempt."""
         if not token:
@@ -409,6 +502,22 @@ class HomelyWebSocket:
         if reconnect_if_disconnected and not self.is_connected() and not self._is_closing:
             self._start_reconnect_loop("token changed while disconnected")
 
+    def sync_token(self, token: str) -> str:
+        """Update token and request reconnect only when the socket is actually down."""
+        if not token:
+            return "ignored_empty"
+
+        reconnect_if_disconnected = not self.is_connected()
+        self.update_token(
+            token,
+            reconnect_if_disconnected=reconnect_if_disconnected,
+        )
+        return (
+            "reconnect_if_disconnected"
+            if reconnect_if_disconnected
+            else "no_reconnect"
+        )
+
     def set_token(self, token: str, reconnect_if_disconnected: bool = False) -> None:
         """Alias for update_token, matching common client-library conventions."""
         self.update_token(token, reconnect_if_disconnected=reconnect_if_disconnected)

{python_homely-0.1.2 → python_homely-0.1.3/src/python_homely.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-homely
-Version: 0.1.2
+Version: 0.1.3
 Summary: Async Python client for the Homely cloud API, built for Home Assistant but usable anywhere.
 Author: Ludvik Blichfeldt Rød
 License-Expression: MIT

{python_homely-0.1.2 → python_homely-0.1.3}/tests/test_sdk.py

@@ -1,10 +1,13 @@
 """Tests for the public python-homely SDK package."""
 from __future__ import annotations
 
+from types import SimpleNamespace
+
 import aiohttp
 import pytest
 
 from homely import (
+    WEBSOCKET_STATUS_OPTIONS,
     HomelyAuthError,
     HomelyClient,
     HomelyConnectionError,
@@ -15,6 +18,7 @@ from homely import (
     TokenResponse,
     __version__,
     auth_header_value,
+    normalize_websocket_status,
 )
 
 
@@ -89,7 +93,7 @@ class _FakeAsyncCallable:
 async def test_sdk_exports_public_symbols():
     """The SDK should expose a clean public surface."""
     assert auth_header_value("token") == "Bearer token"
-    assert __version__ == "0.1.2"
+    assert __version__ == "0.1.3"
 
 
 async def test_authenticate_returns_typed_token():
@@ -462,6 +466,62 @@ async def test_websocket_public_aliases_cover_package_api():
         "device_id=99999999..."
     )
 
+    assert normalize_websocket_status(" Connected ") == "connected"
+    assert tuple(WEBSOCKET_STATUS_OPTIONS) == (
+        "not_initialized",
+        "connecting",
+        "connected",
+        "disconnected",
+        "unknown",
+    )
+
+
+async def test_websocket_connection_state_uses_engineio_transport_health():
+    """Connection state should treat a live Engine.IO transport as connected."""
+    ws = HomelyWebSocket(
+        location_id="loc-1",
+        token="token",
+        on_data_update=lambda _data: None,
+    )
+    ws._status = "Connected"
+    ws.socket = SimpleNamespace(
+        connected=False,
+        eio=SimpleNamespace(state="connected"),
+    )
+
+    state = ws.connection_state()
+
+    assert state.connected is True
+    assert state.reported_status == "connected"
+    assert state.effective_status == "connected"
+    assert state.status_mismatch is False
+
+
+async def test_websocket_sync_token_only_reconnects_when_transport_is_down():
+    """Token sync should not nudge healthy sockets, but should reconnect dead ones."""
+    ws = HomelyWebSocket(
+        location_id="loc-1",
+        token="old-token",
+        on_data_update=lambda _data: None,
+    )
+
+    ws.socket = SimpleNamespace(connected=True)
+    assert ws.sync_token("fresh-token") == "no_reconnect"
+    assert ws.token == "fresh-token"
+
+    ws.socket = SimpleNamespace(connected=False, eio=SimpleNamespace(state="closed"))
+    with pytest.MonkeyPatch.context() as monkeypatch:
+        reconnect_reasons: list[str | None] = []
+        monkeypatch.setattr(
+            ws,
+            "_start_reconnect_loop",
+            lambda reason=None: reconnect_reasons.append(reason),
+        )
+        result = ws.sync_token("newer-token")
+
+    assert result == "reconnect_if_disconnected"
+    assert reconnect_reasons == ["token changed while disconnected"]
+
 
 async def test_websocket_connect_or_raise_uses_typed_exception():
     """Websocket connection failures should raise a typed exception."""