python-homely 0.1.0__py3-none-any.whl

homely/__init__.py

@@ -0,0 +1,34 @@
+"""Reusable Homely client package extracted from the integration."""
+
+__version__ = "0.1.0"
+
+from .client import (
+    BASE_URL,
+    REQUEST_TIMEOUT,
+    HomelyClient,
+    auth_header_value,
+)
+from .exceptions import (
+    HomelyAuthError,
+    HomelyConnectionError,
+    HomelyError,
+    HomelyResponseError,
+    HomelyWebSocketError,
+)
+from .models import TokenResponse
+from .websocket import HomelyWebSocket
+
+__all__ = [
+    "__version__",
+    "BASE_URL",
+    "REQUEST_TIMEOUT",
+    "HomelyClient",
+    "HomelyWebSocket",
+    "HomelyError",
+    "HomelyConnectionError",
+    "HomelyAuthError",
+    "HomelyResponseError",
+    "HomelyWebSocketError",
+    "TokenResponse",
+    "auth_header_value",
+]

homely/client.py

@@ -0,0 +1,209 @@
+"""Async Homely API client."""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import aiohttp
+
+from .exceptions import (
+    HomelyAuthError,
+    HomelyConnectionError,
+    HomelyResponseError,
+)
+from .models import TokenResponse
+
+_LOGGER = logging.getLogger(__name__)
+
+BASE_URL = "https://sdk.iotiliti.cloud/homely/"
+REQUEST_TIMEOUT = aiohttp.ClientTimeout(total=20)
+
+
+def auth_header_value(token: str | None) -> str:
+    """Return normalized Authorization header value."""
+    normalized = (token or "").strip()
+    if normalized.lower().startswith("bearer "):
+        return normalized
+    return f"Bearer {normalized}"
+
+
+class HomelyClient:
+    """Small reusable async client for the Homely cloud API."""
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        *,
+        base_url: str = BASE_URL,
+        timeout: aiohttp.ClientTimeout = REQUEST_TIMEOUT,
+    ) -> None:
+        """Initialize the client with a caller-managed aiohttp session."""
+        self._session = session
+        self._base_url = base_url
+        self._timeout = timeout
+
+    @property
+    def base_url(self) -> str:
+        """Return the configured API base URL."""
+        return self._base_url
+
+    @property
+    def timeout(self) -> aiohttp.ClientTimeout:
+        """Return the configured request timeout."""
+        return self._timeout
+
+    async def authenticate(
+        self,
+        username: str,
+        password: str,
+    ) -> TokenResponse:
+        """Authenticate and return a typed token response.
+
+        Raises a typed SDK exception on failure.
+        """
+        response, reason = await self.fetch_token_with_reason(username, password)
+        if response:
+            return TokenResponse.from_dict(response)
+        if reason == "invalid_auth":
+            raise HomelyAuthError("Invalid Homely username or password")
+        raise HomelyConnectionError("Could not connect to Homely")
+
+    async def fetch_token_with_reason(
+        self,
+        username: str,
+        password: str,
+    ) -> tuple[dict[str, Any] | None, str | None]:
+        """Fetch access token and return optional reason key on failure."""
+        url = f"{self._base_url}oauth/token"
+        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):
+                    _LOGGER.debug("Token fetch successful")
+                    return await response.json(), None
+
+                if response.status in (400, 401, 403):
+                    _LOGGER.debug("Token fetch rejected with status=%s", response.status)
+                    return None, "invalid_auth"
+
+                _LOGGER.warning("Token fetch failed with status=%s", response.status)
+                return None, "cannot_connect"
+        except (aiohttp.ClientError, TimeoutError) as err:
+            _LOGGER.warning("Token fetch network error: %s", err)
+            return None, "cannot_connect"
+
+    async def fetch_token(
+        self,
+        username: str,
+        password: str,
+    ) -> dict[str, Any] | None:
+        """Fetch access token from API."""
+        response, _reason = await self.fetch_token_with_reason(username, password)
+        return response
+
+    async def fetch_refresh_token(self, refresh_token: str) -> dict[str, Any] | None:
+        """Refresh access token using refresh token."""
+        url = f"{self._base_url}oauth/refresh-token"
+        payload = {
+            "refresh_token": refresh_token,
+        }
+
+        try:
+            async with self._session.post(url, json=payload, timeout=self._timeout) as response:
+                if response.status in (200, 201):
+                    _LOGGER.debug("Token refresh successful")
+                    return await response.json()
+                _LOGGER.debug("Token refresh failed with status=%s", response.status)
+                return None
+        except (aiohttp.ClientError, TimeoutError) as err:
+            _LOGGER.debug("Token refresh network error: %s", err)
+            return None
+
+    async def refresh_access_token(self, refresh_token: str) -> TokenResponse:
+        """Refresh access token and return a typed token response."""
+        response = await self.fetch_refresh_token(refresh_token)
+        if response:
+            return TokenResponse.from_dict(response)
+        raise HomelyConnectionError("Could not refresh Homely access token")
+
+    async def get_locations(self, token: str) -> list[dict[str, Any]] | None:
+        """Get locations from API."""
+        url = f"{self._base_url}locations"
+        headers = {"Authorization": auth_header_value(token)}
+
+        try:
+            async with self._session.get(url, headers=headers, timeout=self._timeout) as response:
+                if response.status == 200:
+                    _LOGGER.debug("Locations fetch successful")
+                    return await response.json()
+                _LOGGER.debug("Locations fetch failed with status=%s", response.status)
+                return None
+        except (aiohttp.ClientError, TimeoutError) as err:
+            _LOGGER.debug("Locations fetch network error: %s", err)
+            return None
+
+    async def get_locations_or_raise(self, token: str) -> list[dict[str, Any]]:
+        """Get locations from API or raise a typed exception."""
+        locations = await self.get_locations(token)
+        if locations is not None:
+            return locations
+        raise HomelyConnectionError("Could not fetch Homely locations")
+
+    async def get_home_data(
+        self,
+        token: str,
+        location_id: str | int,
+    ) -> dict[str, Any] | None:
+        """Get location data from API."""
+        data, _status = await self.get_home_data_with_status(token, location_id)
+        return data
+
+    async def get_home_data_with_status(
+        self,
+        token: str,
+        location_id: str | int,
+    ) -> tuple[dict[str, Any] | None, int | None]:
+        """Get location data from API and include HTTP status when available."""
+        url = f"{self._base_url}home/{location_id}"
+        headers = {"Authorization": auth_header_value(token)}
+
+        try:
+            async with self._session.get(url, headers=headers, timeout=self._timeout) as response:
+                if response.status == 200:
+                    return await response.json(), response.status
+                body = await response.text()
+                body_preview = body.replace("\n", " ")[:200]
+                _LOGGER.debug(
+                    "Location data fetch failed with status=%s location_id=%s body_preview=%r",
+                    response.status,
+                    location_id,
+                    body_preview,
+                )
+                return None, response.status
+        except (aiohttp.ClientError, TimeoutError) as err:
+            _LOGGER.debug(
+                "Location data fetch network error location_id=%s: %s",
+                location_id,
+                err,
+            )
+            return None, None
+
+    async def get_home_data_or_raise(
+        self,
+        token: str,
+        location_id: str | int,
+    ) -> dict[str, Any]:
+        """Get location data from API or raise a typed exception."""
+        data, status = await self.get_home_data_with_status(token, location_id)
+        if data is not None:
+            return data
+        if status in (401, 403):
+            raise HomelyAuthError("Homely rejected the supplied access token")
+        raise HomelyResponseError(
+            "Could not fetch Homely location data",
+            status=status,
+        )

homely/exceptions.py

@@ -0,0 +1,34 @@
+"""Exceptions exposed by the Homely SDK."""
+from __future__ import annotations
+
+
+class HomelyError(Exception):
+    """Base exception for Homely SDK failures."""
+
+
+class HomelyConnectionError(HomelyError):
+    """Raised when the Homely service cannot be reached."""
+
+
+class HomelyAuthError(HomelyError):
+    """Raised when Homely rejects authentication or authorization."""
+
+
+class HomelyResponseError(HomelyError):
+    """Raised when Homely returns an unexpected response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        body: str | None = None,
+    ) -> None:
+        """Initialize the exception with optional response details."""
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class HomelyWebSocketError(HomelyError):
+    """Raised when the Homely websocket cannot be established."""

homely/models.py

@@ -0,0 +1,31 @@
+"""Public data models for the Homely SDK."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(slots=True)
+class TokenResponse:
+    """Typed token response returned by the Homely authentication endpoints."""
+
+    access_token: str
+    refresh_token: str | None = None
+    expires_in: int | None = None
+    raw: dict[str, Any] | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TokenResponse:
+        """Build a typed token response from a raw API payload."""
+        expires_in = data.get("expires_in")
+        try:
+            parsed_expires_in = int(expires_in) if expires_in is not None else None
+        except (TypeError, ValueError):
+            parsed_expires_in = None
+
+        return cls(
+            access_token=str(data["access_token"]),
+            refresh_token=data.get("refresh_token"),
+            expires_in=parsed_expires_in,
+            raw=dict(data),
+        )

homely/websocket.py

@@ -0,0 +1,407 @@
+"""Reusable WebSocket client for Homely real-time updates."""
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Callable
+from typing import Any
+from urllib.parse import urlencode
+
+import aiohttp
+
+from .exceptions import HomelyWebSocketError
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class HomelyWebSocket:
+    """WebSocket client for Homely using Socket.IO."""
+
+    WEBSOCKET_URL = "https://sdk.iotiliti.cloud"
+
+    def __init__(
+        self,
+        location_id: str | int,
+        token: str,
+        on_data_update: Callable[[dict[str, Any]], None],
+        status_update_callback: Callable[[str, str | None], None] | None = None,
+        context_id: str | None = None,
+        entry_id: str | None = None,
+    ) -> None:
+        """Initialize WebSocket client."""
+        self.context_id = context_id or entry_id
+        self.entry_id = self.context_id
+        self.location_id = location_id
+        self.token = token
+        self.on_data_update = on_data_update
+        self.socket = None
+        self._is_closing = False
+        self._reconnect_task: asyncio.Task | None = None
+        self._reconnect_interval = 300
+        self._reconnect_warn_every = 12
+        self._status_update_callback = status_update_callback
+        self._status = "Not initialized"
+        self._status_reason: str | None = None
+
+    def _ctx(self, device_id: str | None = None) -> str:
+        """Build consistent log context."""
+        base = f"context_id={self.context_id} location_id={self.location_id}"
+        if device_id:
+            return f"{base} device_id={device_id}"
+        return base
+
+    @property
+    def websocket_url(self) -> str:
+        """WebSocket base URL."""
+        return self.WEBSOCKET_URL
+
+    @staticmethod
+    def _bearer_value(token: str | None) -> str:
+        """Return normalized bearer token value."""
+        normalized = (token or "").strip()
+        if normalized.lower().startswith("bearer "):
+            return normalized
+        return f"Bearer {normalized}"
+
+    @property
+    def status(self) -> str:
+        """Return current websocket status string."""
+        return self._status
+
+    @property
+    def status_reason(self) -> str | None:
+        """Return latest status reason if available."""
+        return self._status_reason
+
+    def _set_status(self, status: str, reason: str | None = None) -> None:
+        """Update internal status and notify callback."""
+        status_changed = status != self._status
+        reason_changed = reason != self._status_reason
+        self._status = status
+        self._status_reason = reason
+
+        if status_changed:
+            if status == "Connected":
+                _LOGGER.info("WebSocket connected %s", self._ctx())
+            elif status == "Disconnected":
+                if reason and self._should_warn_disconnect(reason):
+                    _LOGGER.warning("WebSocket disconnected %s (%s)", self._ctx(), reason)
+                elif reason:
+                    _LOGGER.debug("WebSocket disconnected %s (%s)", self._ctx(), reason)
+                else:
+                    _LOGGER.warning("WebSocket disconnected %s", self._ctx())
+            else:
+                if reason:
+                    _LOGGER.debug(
+                        "WebSocket status changed %s: %s (%s)",
+                        self._ctx(),
+                        status,
+                        reason,
+                    )
+                else:
+                    _LOGGER.debug("WebSocket status changed %s: %s", self._ctx(), status)
+        elif reason_changed and reason:
+            _LOGGER.debug("WebSocket status reason updated %s: %s", self._ctx(), reason)
+
+        if self._status_update_callback:
+            try:
+                self._status_update_callback(status, reason)
+            except Exception as err:
+                _LOGGER.debug("Status callback failed %s: %s", self._ctx(), err)
+
+    def _build_reason(self, data: Any) -> str | None:
+        """Build a readable reason string from event payload."""
+        if data is None:
+            return None
+        try:
+            reason = str(data)
+        except Exception:
+            reason = repr(data)
+        return reason or None
+
+    @staticmethod
+    def _should_warn_disconnect(reason: str | None) -> bool:
+        """Return whether a disconnect reason should be warning-level."""
+        if reason is None:
+            return True
+        if reason == "manual disconnect":
+            return False
+        transient_prefixes = (
+            "connect timeout",
+            "network error:",
+            "connect exception:",
+            "connect_error",
+        )
+        return not reason.startswith(transient_prefixes)
+
+    def _on_event(self, data: Any) -> None:
+        """Handle event payload from websocket."""
+        if not self.is_connected():
+            self._set_status("Connected", "event received")
+        elif self._status != "Connected":
+            self._set_status("Connected")
+
+        device_id = data.get("data", {}).get("deviceId") if isinstance(data, dict) else None
+        if isinstance(data, dict):
+            event_type = data.get("type") or data.get("event") or "unknown"
+            _LOGGER.debug(
+                "WebSocket event received %s event_type=%s",
+                self._ctx(device_id=device_id),
+                event_type,
+            )
+        else:
+            _LOGGER.debug(
+                "WebSocket event received %s non-dict payload",
+                self._ctx(device_id=device_id),
+            )
+        if isinstance(data, dict):
+            try:
+                self.on_data_update(data)
+            except Exception as err:
+                _LOGGER.error(
+                    "Error in on_data_update callback %s: %s",
+                    self._ctx(device_id=device_id),
+                    err,
+                    exc_info=True,
+                )
+
+    def _on_connect(self) -> None:
+        """Handle successful connection."""
+        self._stop_reconnect_loop()
+        self._set_status("Connected")
+
+    def _on_disconnect(self, reason: str | None = None) -> None:
+        """Handle disconnected connection."""
+        if self._is_closing:
+            self._set_status("Disconnected", "manual disconnect")
+            return
+        self._set_status("Disconnected", reason)
+        if not self._is_closing:
+            self._start_reconnect_loop("disconnect event")
+            _LOGGER.debug(
+                "Reconnect requested after disconnect %s interval=%ss",
+                self._ctx(),
+                self._reconnect_interval,
+            )
+
+    def _start_reconnect_loop(self, reason: str | None = None) -> None:
+        """Start reconnect loop if not already running."""
+        if self._is_closing:
+            return
+        if self._reconnect_task and not self._reconnect_task.done():
+            return
+
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = asyncio.get_event_loop()
+
+        self._reconnect_task = loop.create_task(self._reconnect_loop())
+        if reason:
+            _LOGGER.info(
+                "Started reconnect loop %s (%s). interval=%ss, retries=infinite",
+                self._ctx(),
+                reason,
+                self._reconnect_interval,
+            )
+        else:
+            _LOGGER.info(
+                "Started reconnect loop %s. interval=%ss, retries=infinite",
+                self._ctx(),
+                self._reconnect_interval,
+            )
+
+    def _stop_reconnect_loop(self) -> None:
+        """Stop reconnect loop."""
+        if self._reconnect_task and not self._reconnect_task.done():
+            self._reconnect_task.cancel()
+        self._reconnect_task = None
+
+    async def _reconnect_loop(self) -> None:
+        """Try reconnect forever at fixed interval."""
+        attempt = 0
+        while not self._is_closing:
+            if self.is_connected():
+                return
+
+            attempt += 1
+            _LOGGER.debug("WebSocket reconnect attempt %s started %s", attempt, self._ctx())
+            success = await self.connect(from_reconnect_loop=True)
+            if success:
+                _LOGGER.info("WebSocket reconnect attempt %s succeeded %s", attempt, self._ctx())
+                return
+
+            if attempt == 1 or attempt % self._reconnect_warn_every == 0:
+                _LOGGER.warning(
+                    "WebSocket reconnect attempt %s failed %s. Retrying in %s seconds",
+                    attempt,
+                    self._ctx(),
+                    self._reconnect_interval,
+                )
+            else:
+                _LOGGER.debug(
+                    "WebSocket reconnect attempt %s failed %s. Retrying in %s seconds",
+                    attempt,
+                    self._ctx(),
+                    self._reconnect_interval,
+                )
+            await asyncio.sleep(self._reconnect_interval)
+
+    async def connect(self, from_reconnect_loop: bool = False) -> bool:
+        """Connect to websocket server."""
+        if self._is_closing:
+            _LOGGER.debug("Skipping websocket connect during shutdown %s", self._ctx())
+            return False
+
+        try:
+            import socketio
+        except ImportError:
+            _LOGGER.error("python-socketio is not installed. WebSocket disabled %s.", self._ctx())
+            self._set_status("Disconnected", "socketio missing")
+            return False
+
+        if self.is_connected():
+            self._set_status("Connected")
+            return True
+
+        if self.socket is not None:
+            try:
+                await asyncio.wait_for(self.socket.disconnect(), timeout=2)
+            except Exception:
+                pass
+            self.socket = None
+
+        self._set_status("Connecting")
+        try:
+            self.socket = socketio.AsyncClient(
+                reconnection=False,
+                logger=False,
+                engineio_logger=False,
+            )
+
+            @self.socket.event
+            async def connect():
+                self._on_connect()
+
+            @self.socket.event
+            async def disconnect(*args):
+                self._on_disconnect(self._build_reason(args[0] if args else None))
+
+            @self.socket.event
+            async def message(data):
+                self._on_event(data)
+
+            @self.socket.event
+            async def event(data):
+                self._on_event(data)
+
+            @self.socket.on("*")
+            async def catch_all(event, data):
+                if event not in ("connect", "disconnect", "message", "event", "connect_error"):
+                    _LOGGER.debug("WebSocket event %s type=%s", self._ctx(), event)
+                    self._on_event({"type": event, "payload": data})
+
+            @self.socket.event
+            async def connect_error(data):
+                raw_reason = self._build_reason(data)
+                reason = f"connect_error: {raw_reason}" if raw_reason else "connect_error"
+                _LOGGER.debug("WebSocket connect_error %s: %s", self._ctx(), reason)
+                self._on_disconnect(reason)
+
+            bearer_token = self._bearer_value(self.token)
+            query = urlencode(
+                {
+                    "locationId": str(self.location_id),
+                    "token": bearer_token,
+                }
+            )
+            url = f"{self.websocket_url}?{query}"
+            _LOGGER.debug("WebSocket connecting %s to %s", self._ctx(), self.websocket_url)
+            await asyncio.wait_for(
+                self.socket.connect(
+                    url,
+                    transports=["websocket", "polling"],
+                    headers={"Authorization": bearer_token},
+                ),
+                timeout=10,
+            )
+            return True
+        except TimeoutError:
+            self.socket = None
+            self._set_status("Disconnected", "connect timeout")
+        except aiohttp.ClientError as err:
+            self.socket = None
+            self._set_status("Disconnected", f"network error: {err}")
+        except Exception as err:
+            self.socket = None
+            self._set_status("Disconnected", f"connect exception: {err}")
+            _LOGGER.error(
+                "WebSocket connect failed %s: %s (%s)",
+                self._ctx(),
+                err,
+                type(err).__name__,
+            )
+
+        if not from_reconnect_loop:
+            self._start_reconnect_loop("connect failed")
+        return False
+
+    async def connect_or_raise(self) -> None:
+        """Connect to the websocket server or raise a typed exception."""
+        if not await self.connect():
+            raise HomelyWebSocketError(
+                f"Could not connect Homely websocket: {self.status_reason or self.status}"
+            )
+
+    async def disconnect(self) -> None:
+        """Disconnect websocket and stop reconnecting."""
+        self._is_closing = True
+        self._stop_reconnect_loop()
+        try:
+            if self.socket is not None:
+                try:
+                    await asyncio.wait_for(self.socket.disconnect(), timeout=5)
+                except Exception:
+                    pass
+                finally:
+                    self.socket = None
+        finally:
+            self._set_status("Disconnected", "manual disconnect")
+            self._is_closing = False
+
+    async def close(self) -> None:
+        """Alias for disconnect, matching common client-library conventions."""
+        await self.disconnect()
+
+    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)
+
+    def is_connected(self) -> bool:
+        """Return True if socket client reports connected."""
+        try:
+            return self.socket is not None and bool(self.socket.connected)
+        except Exception:
+            return False
+
+    def update_token(self, token: str, reconnect_if_disconnected: bool = False) -> None:
+        """Update token used by next connect/reconnect attempt."""
+        if not token:
+            return
+        if token != self.token:
+            self.token = token
+            _LOGGER.debug("WebSocket token updated %s", self._ctx())
+        if reconnect_if_disconnected and not self.is_connected() and not self._is_closing:
+            self._start_reconnect_loop("token changed while disconnected")
+
+    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)
+
+    def request_reconnect(self, reason: str = "manual request") -> None:
+        """Start reconnect loop if disconnected."""
+        if self._is_closing:
+            return
+        if self.is_connected():
+            return
+        self._start_reconnect_loop(reason)

python_homely-0.1.0.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: python-homely
+Version: 0.1.0
+Summary: Async Python client for the Homely cloud API, built for Home Assistant but usable anywhere.
+Author: Ludvik Blichfeldt Rød
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ludvikroed/python-homely
+Project-URL: Documentation, https://github.com/ludvikroed/python-homely#readme
+Project-URL: Source, https://github.com/ludvikroed/python-homely
+Project-URL: Issues, https://github.com/ludvikroed/python-homely/issues
+Project-URL: Changelog, https://github.com/ludvikroed/python-homely/blob/main/CHANGELOG.md
+Keywords: homely,api,websocket,asyncio,home-automation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp<4.0.0,>=3.9.0
+Requires-Dist: python-socketio<6.0.0,>=5.11.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: pytest>=8.3.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+Requires-Dist: ruff>=0.8.0; extra == "dev"
+Requires-Dist: twine>=6.0.0; extra == "dev"
+Dynamic: license-file
+
+# Python-homely
+
+Async Python client for the Homely cloud API and realtime websocket updates.
+
+This package was created for the Homely Home Assistant integration, but it is framework-independent and can be used in any Python project that needs to talk to Homely.
+
+## Features
+
+- Login and token refresh
+- Location and home-data fetches
+- Realtime websocket updates
+- Typed exceptions
+- Async API built on `aiohttp`
+
+## Installation
+
+```bash
+python3 -m pip install python-homely
+```
+
+## Quick Start
+
+```python
+import aiohttp
+from homely import HomelyClient
+
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        client = HomelyClient(session)
+
+        token = await client.authenticate("user@example.com", "password")
+        locations = await client.get_locations_or_raise(token.access_token)
+        location_id = locations[0]["locationId"]
+
+        data = await client.get_home_data_or_raise(token.access_token, location_id)
+        print(data["name"])
+```
+
+## Websocket Example
+
+```python
+import aiohttp
+from homely import HomelyClient, HomelyWebSocket
+
+
+async def on_update(event: dict) -> None:
+    print(event)
+
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        client = HomelyClient(session)
+        token = await client.authenticate("user@example.com", "password")
+        locations = await client.get_locations_or_raise(token.access_token)
+        location_id = locations[0]["locationId"]
+
+        websocket = HomelyWebSocket(
+            location_id=location_id,
+            token=token.access_token,
+            on_data_update=on_update,
+            context_id="example",
+        )
+
+        await websocket.connect_or_raise()
+```
+
+## Main API
+
+- `authenticate(username, password) -> TokenResponse`
+- `refresh_access_token(refresh_token) -> TokenResponse`
+- `get_locations_or_raise(token) -> list[dict]`
+- `get_home_data_or_raise(token, location_id) -> dict`
+- `HomelyWebSocket(...).connect_or_raise()`
+
+Main exports:
+
+- `HomelyClient`
+- `HomelyWebSocket`
+- `TokenResponse`
+- `HomelyConnectionError`
+- `HomelyAuthError`
+- `HomelyResponseError`
+- `HomelyWebSocketError`
+
+## Exceptions
+
+- `HomelyConnectionError`: network or service unavailable
+- `HomelyAuthError`: invalid credentials or rejected token
+- `HomelyResponseError`: unexpected response or HTTP failure
+- `HomelyWebSocketError`: websocket could not be 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)! ⭐
+

python_homely-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+homely/__init__.py,sha256=9vuclgRmKvpI76PVl1CnTxnezHmSUlPRNuIUjbYY35Y,698
+homely/client.py,sha256=0UQVZFjPMPGMad4kSsDuiiXV_LR4EkZ0J_9TfMEKoj4,7677
+homely/exceptions.py,sha256=g1v7QR9uDydzDCH12FD-3pZN2MGPJu1lDgAnNdT0lCA,893
+homely/models.py,sha256=NgNwYeOo4UiiyP29iFM0rN7k2HIkxZg4s5DivgfdYKM,968
+homely/websocket.py,sha256=DQruxEKuY0K2pEPcz8ltdOZ3NTLZwKKP4eHvDYy73uQ,14978
+python_homely-0.1.0.dist-info/licenses/LICENSE,sha256=nNVHKvQjryAonWsz5TbhzLd6M2kZaoNUvhxz92MgeAA,1079
+python_homely-0.1.0.dist-info/METADATA,sha256=8LKHkP-iwB32Afhpc4uLU9nrSkmJwM78jThVW6E-ZYw,4062
+python_homely-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_homely-0.1.0.dist-info/top_level.txt,sha256=auE-j6ghVMdT_jAw04jiXthgbuLpi-jYBU0fCkKvREQ,7
+python_homely-0.1.0.dist-info/RECORD,,

python_homely-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

python_homely-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ludvik Blichfeldt Rød
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_homely-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+homely