python-homely 0.1.0__tar.gz

python_homely-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,99 @@
+# 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/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "python-homely"
+version = "0.1.0"
+description = "Async Python client for the Homely cloud API, built for Home Assistant but usable anywhere."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Ludvik Blichfeldt Rød" }
+]
+keywords = ["homely", "api", "websocket", "asyncio", "home-automation"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Home Automation",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "aiohttp>=3.9.0,<4.0.0",
+  "python-socketio>=5.11.0,<6.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/ludvikroed/python-homely"
+Documentation = "https://github.com/ludvikroed/python-homely#readme"
+Source = "https://github.com/ludvikroed/python-homely"
+Issues = "https://github.com/ludvikroed/python-homely/issues"
+Changelog = "https://github.com/ludvikroed/python-homely/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.2",
+  "pytest>=8.3.0",
+  "pytest-asyncio>=0.24.0",
+  "ruff>=0.8.0",
+  "twine>=6.0.0",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+cache_dir = "/tmp/python-homely-pytest-cache"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]

python_homely-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

python_homely-0.1.0/src/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",
+]

python_homely-0.1.0/src/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,
+        )

python_homely-0.1.0/src/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."""

python_homely-0.1.0/src/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),
+        )