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

{python_homely-0.1.1/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.1
+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
@@ -102,14 +102,23 @@ async def main() -> None:
 
 - `authenticate(username, password) -> TokenResponse`
 - `refresh_access_token(refresh_token) -> TokenResponse`
+- `fetch_token_details(username, password) -> TokenEndpointResult`
+- `fetch_refresh_token_details(refresh_token) -> TokenEndpointResult`
 - `get_locations_or_raise(token) -> list[dict]`
 - `get_home_data_or_raise(token, location_id) -> dict`
 - `HomelyWebSocket(...).connect_or_raise()`
 
+Legacy compatibility helpers remain available:
+
+- `fetch_token_with_reason(username, password) -> tuple[dict | None, str | None]`
+- `fetch_token(username, password) -> dict | None`
+- `fetch_refresh_token(refresh_token) -> dict | None`
+
 Main exports:
 
 - `HomelyClient`
 - `HomelyWebSocket`
+- `TokenEndpointResult`
 - `TokenResponse`
 - `HomelyConnectionError`
 - `HomelyAuthError`
@@ -121,12 +130,33 @@ Main exports:
 - `HomelyConnectionError`: network or service unavailable
 - `HomelyAuthError`: invalid credentials or rejected token
 - `HomelyResponseError`: unexpected response or HTTP failure
+  Carries `status` and `body_preview` when available.
 - `HomelyWebSocketError`: websocket could not be established
 
+## Token Diagnostics
+
+If you need more than success/failure, use the detailed token helpers:
+
+```python
+result = await client.fetch_refresh_token_details(refresh_token)
+if result.ok:
+    print(result.token.access_token)
+else:
+    print(result.reason, result.status, result.detail, result.body_preview)
+```
+
+`TokenEndpointResult.reason` can distinguish between invalid credentials, invalid refresh
+tokens, network errors, timeouts, malformed JSON, malformed payloads, empty responses, and
+unexpected HTTP failures.
+
+## Websocket Note
+
+Refreshing an access token does not require forcing an already-connected websocket to reconnect.
+The websocket token only matters when a new websocket connection is established or re-established.
+
 ## License
 
 MIT. See [LICENSE](LICENSE).
 
 
-⭐ If you find this integration useful, please consider giving it a star on [GitHub](https://github.com/ludvikroed/python-homely)! ⭐
-
+⭐ If you find this package useful, please consider giving it a star on [GitHub](https://github.com/ludvikroed/python-homely)! ⭐

{python_homely-0.1.1 → python_homely-0.1.3}/README.md

@@ -69,14 +69,23 @@ async def main() -> None:
 
 - `authenticate(username, password) -> TokenResponse`
 - `refresh_access_token(refresh_token) -> TokenResponse`
+- `fetch_token_details(username, password) -> TokenEndpointResult`
+- `fetch_refresh_token_details(refresh_token) -> TokenEndpointResult`
 - `get_locations_or_raise(token) -> list[dict]`
 - `get_home_data_or_raise(token, location_id) -> dict`
 - `HomelyWebSocket(...).connect_or_raise()`
 
+Legacy compatibility helpers remain available:
+
+- `fetch_token_with_reason(username, password) -> tuple[dict | None, str | None]`
+- `fetch_token(username, password) -> dict | None`
+- `fetch_refresh_token(refresh_token) -> dict | None`
+
 Main exports:
 
 - `HomelyClient`
 - `HomelyWebSocket`
+- `TokenEndpointResult`
 - `TokenResponse`
 - `HomelyConnectionError`
 - `HomelyAuthError`
@@ -88,12 +97,33 @@ Main exports:
 - `HomelyConnectionError`: network or service unavailable
 - `HomelyAuthError`: invalid credentials or rejected token
 - `HomelyResponseError`: unexpected response or HTTP failure
+  Carries `status` and `body_preview` when available.
 - `HomelyWebSocketError`: websocket could not be established
 
+## Token Diagnostics
+
+If you need more than success/failure, use the detailed token helpers:
+
+```python
+result = await client.fetch_refresh_token_details(refresh_token)
+if result.ok:
+    print(result.token.access_token)
+else:
+    print(result.reason, result.status, result.detail, result.body_preview)
+```
+
+`TokenEndpointResult.reason` can distinguish between invalid credentials, invalid refresh
+tokens, network errors, timeouts, malformed JSON, malformed payloads, empty responses, and
+unexpected HTTP failures.
+
+## Websocket Note
+
+Refreshing an access token does not require forcing an already-connected websocket to reconnect.
+The websocket token only matters when a new websocket connection is established or re-established.
+
 ## License
 
 MIT. See [LICENSE](LICENSE).
 
 
-⭐ If you find this integration useful, please consider giving it a star on [GitHub](https://github.com/ludvikroed/python-homely)! ⭐
-
+⭐ If you find this package useful, please consider giving it a star on [GitHub](https://github.com/ludvikroed/python-homely)! ⭐

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-homely"
-version = "0.1.1"
+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"
@@ -51,6 +51,9 @@ package-dir = {"" = "src"}
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+homely = ["py.typed"]
+
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]

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

@@ -1,6 +1,6 @@
 """Reusable Homely client package extracted from the integration."""
 
-__version__ = "0.1.1"
+__version__ = "0.1.3"
 
 from .client import (
     BASE_URL,
@@ -15,8 +15,13 @@ from .exceptions import (
     HomelyResponseError,
     HomelyWebSocketError,
 )
-from .models import TokenResponse
-from .websocket import HomelyWebSocket
+from .models import TokenEndpointResult, TokenResponse
+from .websocket import (
+    WEBSOCKET_STATUS_OPTIONS,
+    HomelyWebSocket,
+    WebSocketConnectionState,
+    normalize_websocket_status,
+)
 
 __all__ = [
     "__version__",
@@ -24,11 +29,15 @@ __all__ = [
     "REQUEST_TIMEOUT",
     "HomelyClient",
     "HomelyWebSocket",
+    "WebSocketConnectionState",
     "HomelyError",
     "HomelyConnectionError",
     "HomelyAuthError",
     "HomelyResponseError",
     "HomelyWebSocketError",
+    "TokenEndpointResult",
     "TokenResponse",
+    "WEBSOCKET_STATUS_OPTIONS",
     "auth_header_value",
+    "normalize_websocket_status",
 ]

{python_homely-0.1.1 → python_homely-0.1.3}/src/homely/client.py

@@ -2,7 +2,7 @@
 from __future__ import annotations
 
 import logging
-from typing import Any
+from typing import Any, NoReturn
 
 import aiohttp
 
@@ -11,7 +11,7 @@ from .exceptions import (
     HomelyConnectionError,
     HomelyResponseError,
 )
-from .models import TokenResponse
+from .models import TokenEndpointResult, TokenFailureReason, TokenResponse
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -46,6 +46,36 @@ def _response_preview(payload: Any) -> str:
     return f"{text[:200]}..."
 
 
+def _text_preview(text: str | None) -> str | None:
+    """Return a trimmed short preview of response text."""
+    if text is None:
+        return None
+
+    preview = text.strip()
+    if not preview:
+        return None
+    if len(preview) <= 200:
+        return preview
+    return f"{preview[:200]}..."
+
+
+def _error_detail(err: BaseException) -> str:
+    """Return a compact detail string for logs and typed results."""
+    detail = str(err).strip()
+    if detail:
+        return detail
+    return err.__class__.__name__
+
+
+def _coarse_token_reason(reason: TokenFailureReason | None) -> str | None:
+    """Map detailed token failure reasons to the legacy coarse reason set."""
+    if reason == "invalid_auth":
+        return "invalid_auth"
+    if reason is None:
+        return None
+    return "cannot_connect"
+
+
 class HomelyClient:
     """Small reusable async client for the Homely cloud API."""
 
@@ -80,24 +110,17 @@ class HomelyClient:
 
         Raises a typed SDK exception on failure.
         """
-        response, status = await self._fetch_token_payload(username, password)
-        if response is not None:
-            try:
-                return TokenResponse.from_dict(response)
-            except (KeyError, TypeError, ValueError) as err:
-                raise HomelyResponseError(
-                    "Homely authentication response missing required fields",
-                    status=status,
-                    body=_response_preview(response),
-                ) from err
-        if status in (400, 401, 403):
-            raise HomelyAuthError("Invalid Homely username or password")
-        if status in (200, 201):
-            raise HomelyResponseError(
-                "Homely authentication response could not be parsed",
-                status=status,
-            )
-        raise HomelyConnectionError("Could not connect to Homely")
+        result = await self.fetch_token_details(username, password)
+        if result.token is not None:
+            return result.token
+        self._raise_token_endpoint_failure(
+            result,
+            invalid_reason="invalid_auth",
+            invalid_message="Invalid Homely username or password",
+            connection_message="Could not connect to Homely",
+            malformed_message="Homely authentication response could not be parsed",
+            response_message="Homely authentication failed",
+        )
 
     async def _fetch_token_payload(
         self,
@@ -105,39 +128,25 @@ class HomelyClient:
         password: str,
     ) -> tuple[dict[str, Any] | None, int | None]:
         """Fetch access token payload and include HTTP status when available."""
-        url = f"{self._base_url}oauth/token"
+        result = await self.fetch_token_details(username, password)
+        return result.raw, result.status
+
+    async def fetch_token_details(
+        self,
+        username: str,
+        password: str,
+    ) -> TokenEndpointResult:
+        """Fetch a token and return a detailed typed result."""
         payload = {
             "username": username,
             "password": password,
         }
-
-        try:
-            async with self._session.post(url, json=payload, timeout=self._timeout) as response:
-                if response.status in (200, 201):
-                    try:
-                        parsed = await response.json()
-                    except (aiohttp.ContentTypeError, TypeError, ValueError) as err:
-                        _LOGGER.debug(
-                            "Token fetch returned invalid JSON status=%s: %s",
-                            response.status,
-                            err,
-                        )
-                        return None, response.status
-                    if not isinstance(parsed, dict):
-                        _LOGGER.debug(
-                            "Token fetch returned unexpected payload type status=%s payload_type=%s",
-                            response.status,
-                            type(parsed).__name__,
-                        )
-                        return None, response.status
-                    _LOGGER.debug("Token fetch successful")
-                    return parsed, response.status
-
-                _LOGGER.debug("Token fetch failed with status=%s", response.status)
-                return None, response.status
-        except (aiohttp.ClientError, TimeoutError) as err:
-            _LOGGER.debug("Token fetch network error: %s", err)
-            return None, None
+        return await self._post_token_endpoint(
+            endpoint="oauth/token",
+            payload=payload,
+            invalid_reason="invalid_auth",
+            action="Token fetch",
+        )
 
     async def fetch_token_with_reason(
         self,
@@ -145,12 +154,10 @@ class HomelyClient:
         password: str,
     ) -> tuple[dict[str, Any] | None, str | None]:
         """Fetch access token and return optional reason key on failure."""
-        response, status = await self._fetch_token_payload(username, password)
-        if response is not None:
-            return response, None
-        if status in (400, 401, 403):
-            return None, "invalid_auth"
-        return None, "cannot_connect"
+        result = await self.fetch_token_details(username, password)
+        if result.raw is not None:
+            return result.raw, None
+        return None, _coarse_token_reason(result.reason)
 
     async def fetch_token(
         self,
@@ -158,71 +165,185 @@ class HomelyClient:
         password: str,
     ) -> dict[str, Any] | None:
         """Fetch access token from API."""
-        response, _reason = await self.fetch_token_with_reason(username, password)
-        return response
+        result = await self.fetch_token_details(username, password)
+        return result.raw
 
     async def _fetch_refresh_token_payload(
         self,
         refresh_token: str,
     ) -> tuple[dict[str, Any] | None, int | None]:
         """Refresh access token payload and include HTTP status when available."""
-        url = f"{self._base_url}oauth/refresh-token"
+        result = await self.fetch_refresh_token_details(refresh_token)
+        return result.raw, result.status
+
+    async def fetch_refresh_token_details(
+        self,
+        refresh_token: str,
+    ) -> TokenEndpointResult:
+        """Refresh a token and return a detailed typed result."""
         payload = {
             "refresh_token": refresh_token,
         }
+        return await self._post_token_endpoint(
+            endpoint="oauth/refresh-token",
+            payload=payload,
+            invalid_reason="invalid_refresh_token",
+            action="Token refresh",
+        )
+
+    async def fetch_refresh_token(self, refresh_token: str) -> dict[str, Any] | None:
+        """Refresh access token using refresh token."""
+        result = await self.fetch_refresh_token_details(refresh_token)
+        return result.raw
+
+    async def refresh_access_token(self, refresh_token: str) -> TokenResponse:
+        """Refresh access token and return a typed token response."""
+        result = await self.fetch_refresh_token_details(refresh_token)
+        if result.token is not None:
+            return result.token
+        self._raise_token_endpoint_failure(
+            result,
+            invalid_reason="invalid_refresh_token",
+            invalid_message="Homely rejected the supplied refresh token",
+            connection_message="Could not refresh Homely access token",
+            malformed_message="Homely refresh response could not be parsed",
+            response_message="Homely refresh request failed",
+        )
+
+    async def _post_token_endpoint(
+        self,
+        *,
+        endpoint: str,
+        payload: dict[str, Any],
+        invalid_reason: TokenFailureReason,
+        action: str,
+    ) -> TokenEndpointResult:
+        """Post to a token endpoint and return a detailed typed result."""
+        url = f"{self._base_url}{endpoint}"
 
         try:
             async with self._session.post(url, json=payload, timeout=self._timeout) as response:
+                body_preview = await self._response_text_preview(response)
                 if response.status in (200, 201):
                     try:
                         parsed = await response.json()
                     except (aiohttp.ContentTypeError, TypeError, ValueError) as err:
+                        detail = _error_detail(err)
                         _LOGGER.debug(
-                            "Token refresh returned invalid JSON status=%s: %s",
+                            "%s returned invalid JSON status=%s: %s",
+                            action,
                             response.status,
-                            err,
+                            detail,
+                        )
+                        return TokenEndpointResult(
+                            reason="invalid_json",
+                            status=response.status,
+                            detail=detail,
+                            body_preview=body_preview,
                         )
-                        return None, response.status
                     if not isinstance(parsed, dict):
+                        detail = f"payload_type={type(parsed).__name__}"
                         _LOGGER.debug(
-                            "Token refresh returned unexpected payload type status=%s payload_type=%s",
+                            "%s returned unexpected payload type status=%s payload_type=%s",
+                            action,
                             response.status,
                             type(parsed).__name__,
                         )
-                        return None, response.status
-                    _LOGGER.debug("Token refresh successful")
-                    return parsed, response.status
-                _LOGGER.debug("Token refresh failed with status=%s", response.status)
-                return None, response.status
-        except (aiohttp.ClientError, TimeoutError) as err:
-            _LOGGER.debug("Token refresh network error: %s", err)
-            return None, None
-
-    async def fetch_refresh_token(self, refresh_token: str) -> dict[str, Any] | None:
-        """Refresh access token using refresh token."""
-        response, _status = await self._fetch_refresh_token_payload(refresh_token)
-        return response
+                        return TokenEndpointResult(
+                            reason="invalid_payload",
+                            status=response.status,
+                            detail=detail,
+                            body_preview=_response_preview(parsed),
+                        )
+                    if not parsed:
+                        _LOGGER.debug(
+                            "%s returned an empty payload status=%s",
+                            action,
+                            response.status,
+                        )
+                        return TokenEndpointResult(
+                            reason="empty_response",
+                            status=response.status,
+                            body_preview=_response_preview(parsed),
+                        )
+                    try:
+                        token = TokenResponse.from_dict(parsed)
+                    except (KeyError, TypeError, ValueError) as err:
+                        detail = _error_detail(err)
+                        _LOGGER.debug(
+                            "%s returned malformed payload status=%s: %s",
+                            action,
+                            response.status,
+                            detail,
+                        )
+                        return TokenEndpointResult(
+                            reason="invalid_payload",
+                            status=response.status,
+                            detail=detail,
+                            body_preview=_response_preview(parsed),
+                        )
+                    _LOGGER.debug("%s successful", action)
+                    return TokenEndpointResult(token=token, status=response.status)
+
+                if response.status in (400, 401, 403):
+                    _LOGGER.debug("%s rejected with status=%s", action, response.status)
+                    return TokenEndpointResult(
+                        reason=invalid_reason,
+                        status=response.status,
+                        body_preview=body_preview,
+                    )
+
+                _LOGGER.debug("%s failed with status=%s", action, response.status)
+                return TokenEndpointResult(
+                    reason="http_error",
+                    status=response.status,
+                    body_preview=body_preview,
+                )
+        except TimeoutError as err:
+            detail = _error_detail(err)
+            _LOGGER.debug("%s timeout: %s", action, detail)
+            return TokenEndpointResult(reason="timeout", detail=detail)
+        except aiohttp.ClientError as err:
+            detail = _error_detail(err)
+            _LOGGER.debug("%s network error: %s", action, detail)
+            return TokenEndpointResult(reason="network_error", detail=detail)
+
+    async def _response_text_preview(self, response: aiohttp.ClientResponse) -> str | None:
+        """Read and shorten response text for diagnostics when available."""
+        try:
+            return _text_preview(await response.text())
+        except (TypeError, ValueError, UnicodeDecodeError) as err:
+            _LOGGER.debug("Could not read response text status=%s: %s", response.status, err)
+            return None
 
-    async def refresh_access_token(self, refresh_token: str) -> TokenResponse:
-        """Refresh access token and return a typed token response."""
-        response, status = await self._fetch_refresh_token_payload(refresh_token)
-        if response is not None:
-            try:
-                return TokenResponse.from_dict(response)
-            except (KeyError, TypeError, ValueError) as err:
-                raise HomelyResponseError(
-                    "Homely refresh response missing required fields",
-                    status=status,
-                    body=_response_preview(response),
-                ) from err
-        if status in (400, 401, 403):
-            raise HomelyAuthError("Homely rejected the supplied refresh token")
-        if status in (200, 201):
+    def _raise_token_endpoint_failure(
+        self,
+        result: TokenEndpointResult,
+        *,
+        invalid_reason: TokenFailureReason,
+        invalid_message: str,
+        connection_message: str,
+        malformed_message: str,
+        response_message: str,
+    ) -> NoReturn:
+        """Raise a typed SDK exception for a failed token endpoint result."""
+        if result.reason == invalid_reason:
+            raise HomelyAuthError(invalid_message)
+        if result.reason in ("timeout", "network_error"):
+            raise HomelyConnectionError(connection_message)
+        if result.reason in ("invalid_json", "invalid_payload", "empty_response"):
             raise HomelyResponseError(
-                "Homely refresh response could not be parsed",
-                status=status,
+                malformed_message,
+                status=result.status,
+                body=result.body_preview,
+                body_preview=result.body_preview,
             )
-        raise HomelyConnectionError("Could not refresh Homely access token")
+        raise HomelyResponseError(
+            response_message,
+            status=result.status,
+            body=result.body_preview,
+            body_preview=result.body_preview,
+        )
 
     async def _get_locations_payload(
         self,
@@ -246,7 +367,8 @@ class HomelyClient:
                         return None, response.status
                     if not isinstance(parsed, list):
                         _LOGGER.debug(
-                            "Locations fetch returned unexpected payload type status=%s payload_type=%s",
+                            "Locations fetch returned unexpected payload type "
+                            "status=%s payload_type=%s",
                             response.status,
                             type(parsed).__name__,
                         )
@@ -303,7 +425,8 @@ class HomelyClient:
                         parsed = await response.json()
                     except (aiohttp.ContentTypeError, TypeError, ValueError) as err:
                         _LOGGER.debug(
-                            "Location data fetch returned invalid JSON status=%s location_id=%s: %s",
+                            "Location data fetch returned invalid JSON "
+                            "status=%s location_id=%s: %s",
                             response.status,
                             _log_identifier(location_id),
                             err,
@@ -311,7 +434,8 @@ class HomelyClient:
                         return None, response.status
                     if not isinstance(parsed, dict):
                         _LOGGER.debug(
-                            "Location data fetch returned unexpected payload type status=%s location_id=%s payload_type=%s",
+                            "Location data fetch returned unexpected payload "
+                            "type status=%s location_id=%s payload_type=%s",
                             response.status,
                             _log_identifier(location_id),
                             type(parsed).__name__,

{python_homely-0.1.1 → python_homely-0.1.3}/src/homely/exceptions.py

@@ -23,10 +23,14 @@ class HomelyResponseError(HomelyError):
         *,
         status: int | None = None,
         body: str | None = None,
+        body_preview: str | None = None,
     ) -> None:
         """Initialize the exception with optional response details."""
         super().__init__(message)
         self.status = status
+        if body_preview is None:
+            body_preview = body
+        self.body_preview = body_preview
         self.body = body
 
 

{python_homely-0.1.1 → python_homely-0.1.3}/src/homely/models.py

@@ -2,7 +2,18 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Any
+from typing import Any, Literal
+
+TokenFailureReason = Literal[
+    "invalid_auth",
+    "invalid_refresh_token",
+    "http_error",
+    "network_error",
+    "timeout",
+    "invalid_json",
+    "invalid_payload",
+    "empty_response",
+]
 
 
 @dataclass(slots=True)
@@ -29,3 +40,26 @@ class TokenResponse:
             expires_in=parsed_expires_in,
             raw=dict(data),
         )
+
+
+@dataclass(slots=True)
+class TokenEndpointResult:
+    """Detailed result returned by authentication and refresh helpers."""
+
+    token: TokenResponse | None = None
+    reason: TokenFailureReason | None = None
+    status: int | None = None
+    detail: str | None = None
+    body_preview: str | None = None
+
+    @property
+    def ok(self) -> bool:
+        """Return whether the request produced a usable token response."""
+        return self.token is not None
+
+    @property
+    def raw(self) -> dict[str, Any] | None:
+        """Return the raw token payload when available."""
+        if self.token is None:
+            return None
+        return self.token.raw