daikin-onecta 0.1.0__tar.gz

daikin_onecta-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: daikin-onecta
+Version: 0.1.0
+Summary: Async Python client for the Daikin Onecta cloud API
+Author: Johnny Willemsen
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jwillemsen/daikin-onecta
+Project-URL: Repository, https://github.com/jwillemsen/daikin-onecta
+Project-URL: Issues, https://github.com/jwillemsen/daikin-onecta/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.9.0
+Provides-Extra: test
+Requires-Dist: aiohttp<3.14; extra == "test"
+Requires-Dist: aioresponses>=0.7.8; extra == "test"
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: daikin-onecta[test]; extra == "dev"
+Requires-Dist: ruff>=0.13; extra == "dev"
+
+# daikin-onecta
+
+Async Python client for the Daikin Onecta cloud API.
+
+This library contains the Daikin-specific API layer used by the Home Assistant
+Daikin Onecta integration. It deliberately has no dependency on Home Assistant.
+
+## Usage
+
+```python
+import aiohttp
+
+from daikin_onecta import OnectaClient
+
+
+async def token_provider() -> str:
+    return "access-token"
+
+
+async with aiohttp.ClientSession() as session:
+    client = OnectaClient(session, token_provider)
+    devices = await client.get_gateway_devices()
+```
+
+Authentication is supplied by an asynchronous token callback so applications
+remain responsible for their own OAuth flow and token refresh.
+
+## Status
+
+The API is currently alpha. The first release intentionally exposes gateway
+devices as raw dictionaries while the stable typed device model is developed.

daikin_onecta-0.1.0/README.md

@@ -0,0 +1,31 @@
+# daikin-onecta
+
+Async Python client for the Daikin Onecta cloud API.
+
+This library contains the Daikin-specific API layer used by the Home Assistant
+Daikin Onecta integration. It deliberately has no dependency on Home Assistant.
+
+## Usage
+
+```python
+import aiohttp
+
+from daikin_onecta import OnectaClient
+
+
+async def token_provider() -> str:
+    return "access-token"
+
+
+async with aiohttp.ClientSession() as session:
+    client = OnectaClient(session, token_provider)
+    devices = await client.get_gateway_devices()
+```
+
+Authentication is supplied by an asynchronous token callback so applications
+remain responsible for their own OAuth flow and token refresh.
+
+## Status
+
+The API is currently alpha. The first release intentionally exposes gateway
+devices as raw dictionaries while the stable typed device model is developed.

daikin_onecta-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "daikin-onecta"
+version = "0.1.0"
+description = "Async Python client for the Daikin Onecta cloud API"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [
+  { name = "Johnny Willemsen" },
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+  "aiohttp>=3.9.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/jwillemsen/daikin-onecta"
+Repository = "https://github.com/jwillemsen/daikin-onecta"
+Issues = "https://github.com/jwillemsen/daikin-onecta/issues"
+
+[project.optional-dependencies]
+test = [
+  "aiohttp<3.14",
+  "aioresponses>=0.7.8",
+  "pytest>=8.0",
+  "pytest-asyncio>=0.24",
+  "pytest-cov>=5.0",
+]
+dev = [
+  "daikin-onecta[test]",
+  "ruff>=0.13",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+addopts = "--cov=daikin_onecta --cov-report=term-missing"
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

daikin_onecta-0.1.0/setup.cfg

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

daikin_onecta-0.1.0/src/daikin_onecta/__init__.py

@@ -0,0 +1,23 @@
+"""Async client for the Daikin Onecta cloud API."""
+
+from .client import OnectaClient
+from .exceptions import (
+    OnectaApiError,
+    OnectaAuthenticationError,
+    OnectaConnectionError,
+    OnectaError,
+    OnectaRateLimitError,
+)
+from .models import GatewayDevice
+from .rate_limit import RateLimit
+
+__all__ = [
+    "GatewayDevice",
+    "OnectaApiError",
+    "OnectaAuthenticationError",
+    "OnectaClient",
+    "OnectaConnectionError",
+    "OnectaError",
+    "OnectaRateLimitError",
+    "RateLimit",
+]

daikin_onecta-0.1.0/src/daikin_onecta/client.py

@@ -0,0 +1,138 @@
+"""Client for the Daikin Onecta cloud API."""
+
+import json
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+import aiohttp
+
+from .exceptions import (
+    OnectaApiError,
+    OnectaAuthenticationError,
+    OnectaConnectionError,
+    OnectaRateLimitError,
+)
+from .models import GatewayDevice
+from .rate_limit import RateLimit
+
+ONECTA_API_URL = "https://api.onecta.daikineurope.com"
+
+
+class OnectaClient:
+    """Async client for the Daikin Onecta cloud API."""
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        token_provider: Callable[[], Awaitable[str]],
+        *,
+        base_url: str = ONECTA_API_URL,
+    ) -> None:
+        """Initialize the client."""
+        self._session = session
+        self._token_provider = token_provider
+        self._base_url = base_url.rstrip("/")
+        self.rate_limit = RateLimit()
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_data: Any = None,
+    ) -> Any:
+        """Perform an authenticated request to the Daikin Onecta API."""
+        token = await self._token_provider()
+        headers = {
+            "Accept-Encoding": "gzip",
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+        }
+
+        try:
+            async with self._session.request(
+                method,
+                f"{self._base_url}{path}",
+                headers=headers,
+                json=json_data,
+            ) as response:
+                self.rate_limit = RateLimit.from_headers(response.headers)
+                response_text = await response.text()
+
+                if response.status in (401, 403):
+                    raise OnectaAuthenticationError(
+                        f"Daikin Onecta API authentication failed with HTTP {response.status}"
+                    )
+
+                if response.status == 429:
+                    raise OnectaRateLimitError(self.rate_limit.retry_after)
+
+                if response.status >= 400:
+                    raise OnectaApiError(response.status, response_text)
+
+                if response.status == 204 or not response_text:
+                    return None
+
+                try:
+                    return json.loads(response_text)
+                except json.JSONDecodeError as err:
+                    raise OnectaApiError(response.status, "Invalid JSON response") from err
+        except (OnectaApiError, OnectaAuthenticationError, OnectaRateLimitError):
+            raise
+        except (TimeoutError, aiohttp.ClientError) as err:
+            raise OnectaConnectionError(str(err)) from err
+
+    async def get_gateway_devices(self) -> list[GatewayDevice]:
+        """Return all gateway devices available to the account."""
+        data = await self._request("GET", "/v1/gateway-devices")
+        if not isinstance(data, list):
+            raise OnectaApiError(200, "Expected a list of gateway devices")
+        return data
+
+    async def patch_characteristic(
+        self,
+        gateway_id: str,
+        management_point_id: str,
+        characteristic: str,
+        value: Any,
+        *,
+        path: str | None = None,
+    ) -> None:
+        """Set a management-point characteristic."""
+        body: dict[str, Any] = {"value": value}
+        if path:
+            body["path"] = path
+        await self._request(
+            "PATCH",
+            f"/v1/gateway-devices/{gateway_id}/management-points/{management_point_id}"
+            f"/characteristics/{characteristic}",
+            json_data=body,
+        )
+
+    async def post_management_point(
+        self,
+        gateway_id: str,
+        management_point_id: str,
+        resource: str,
+        value: Any,
+    ) -> Any:
+        """POST data to a management-point resource."""
+        return await self._request(
+            "POST",
+            f"/v1/gateway-devices/{gateway_id}/management-points/{management_point_id}/{resource}",
+            json_data=value,
+        )
+
+    async def put_management_point(
+        self,
+        gateway_id: str,
+        management_point_id: str,
+        resource: str,
+        value: Any = None,
+    ) -> Any:
+        """PUT data to a management-point resource."""
+        return await self._request(
+            "PUT",
+            f"/v1/gateway-devices/{gateway_id}/management-points/{management_point_id}/{resource}",
+            json_data=value,
+        )

daikin_onecta-0.1.0/src/daikin_onecta/exceptions.py

@@ -0,0 +1,32 @@
+"""Exceptions raised by the Daikin Onecta client."""
+
+
+class OnectaError(Exception):
+    """Base exception for Daikin Onecta errors."""
+
+
+class OnectaConnectionError(OnectaError):
+    """Raised when communication with the Daikin Onecta API fails."""
+
+
+class OnectaAuthenticationError(OnectaError):
+    """Raised when authentication with the Daikin Onecta API fails."""
+
+
+class OnectaRateLimitError(OnectaError):
+    """Raised when the Daikin Onecta API rate limit is exceeded."""
+
+    def __init__(self, retry_after: int | None, message: str = "Daikin Onecta API rate limit exceeded") -> None:
+        """Initialize the rate limit error."""
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class OnectaApiError(OnectaError):
+    """Raised when the Daikin Onecta API returns an unexpected response."""
+
+    def __init__(self, status: int, message: str) -> None:
+        """Initialize the API error."""
+        super().__init__(f"Daikin Onecta API returned HTTP {status}: {message}")
+        self.status = status
+        self.message = message

daikin_onecta-0.1.0/src/daikin_onecta/models.py

@@ -0,0 +1,5 @@
+"""Models returned by the Daikin Onecta API."""
+
+from typing import Any
+
+type GatewayDevice = dict[str, Any]

daikin_onecta-0.1.0/src/daikin_onecta/rate_limit.py

@@ -0,0 +1,39 @@
+"""Daikin Onecta API rate-limit information."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+
+def _header_int(headers: Mapping[str, str], name: str) -> int | None:
+    """Return an integer response header when it contains a valid value."""
+    value = headers.get(name)
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+@dataclass(frozen=True, slots=True)
+class RateLimit:
+    """Rate-limit state returned by the Daikin Onecta API."""
+
+    minute_limit: int | None = None
+    day_limit: int | None = None
+    minute_remaining: int | None = None
+    day_remaining: int | None = None
+    retry_after: int | None = None
+    reset: int | None = None
+
+    @classmethod
+    def from_headers(cls, headers: Mapping[str, str]) -> "RateLimit":
+        """Create rate-limit state from Daikin response headers."""
+        return cls(
+            minute_limit=_header_int(headers, "X-RateLimit-Limit-minute"),
+            day_limit=_header_int(headers, "X-RateLimit-Limit-day"),
+            minute_remaining=_header_int(headers, "X-RateLimit-Remaining-minute"),
+            day_remaining=_header_int(headers, "X-RateLimit-Remaining-day"),
+            retry_after=_header_int(headers, "Retry-After"),
+            reset=_header_int(headers, "RateLimit-Reset"),
+        )

daikin_onecta-0.1.0/src/daikin_onecta.egg-info/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: daikin-onecta
+Version: 0.1.0
+Summary: Async Python client for the Daikin Onecta cloud API
+Author: Johnny Willemsen
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jwillemsen/daikin-onecta
+Project-URL: Repository, https://github.com/jwillemsen/daikin-onecta
+Project-URL: Issues, https://github.com/jwillemsen/daikin-onecta/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.9.0
+Provides-Extra: test
+Requires-Dist: aiohttp<3.14; extra == "test"
+Requires-Dist: aioresponses>=0.7.8; extra == "test"
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: daikin-onecta[test]; extra == "dev"
+Requires-Dist: ruff>=0.13; extra == "dev"
+
+# daikin-onecta
+
+Async Python client for the Daikin Onecta cloud API.
+
+This library contains the Daikin-specific API layer used by the Home Assistant
+Daikin Onecta integration. It deliberately has no dependency on Home Assistant.
+
+## Usage
+
+```python
+import aiohttp
+
+from daikin_onecta import OnectaClient
+
+
+async def token_provider() -> str:
+    return "access-token"
+
+
+async with aiohttp.ClientSession() as session:
+    client = OnectaClient(session, token_provider)
+    devices = await client.get_gateway_devices()
+```
+
+Authentication is supplied by an asynchronous token callback so applications
+remain responsible for their own OAuth flow and token refresh.
+
+## Status
+
+The API is currently alpha. The first release intentionally exposes gateway
+devices as raw dictionaries while the stable typed device model is developed.

daikin_onecta-0.1.0/src/daikin_onecta.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+src/daikin_onecta/__init__.py
+src/daikin_onecta/client.py
+src/daikin_onecta/exceptions.py
+src/daikin_onecta/models.py
+src/daikin_onecta/rate_limit.py
+src/daikin_onecta.egg-info/PKG-INFO
+src/daikin_onecta.egg-info/SOURCES.txt
+src/daikin_onecta.egg-info/dependency_links.txt
+src/daikin_onecta.egg-info/requires.txt
+src/daikin_onecta.egg-info/top_level.txt
+tests/test_client.py
+tests/test_rate_limit.py

daikin_onecta-0.1.0/src/daikin_onecta.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

daikin_onecta-0.1.0/src/daikin_onecta.egg-info/requires.txt

@@ -0,0 +1,12 @@
+aiohttp>=3.9.0
+
+[dev]
+daikin-onecta[test]
+ruff>=0.13
+
+[test]
+aiohttp<3.14
+aioresponses>=0.7.8
+pytest>=8.0
+pytest-asyncio>=0.24
+pytest-cov>=5.0

daikin_onecta-0.1.0/src/daikin_onecta.egg-info/top_level.txt

@@ -0,0 +1 @@
+daikin_onecta

daikin_onecta-0.1.0/tests/test_client.py

@@ -0,0 +1,82 @@
+"""Tests for the Daikin Onecta client."""
+
+import aiohttp
+import pytest
+from aioresponses import aioresponses
+
+from daikin_onecta import (
+    OnectaApiError,
+    OnectaAuthenticationError,
+    OnectaClient,
+    OnectaRateLimitError,
+)
+
+BASE_URL = "https://api.onecta.daikineurope.com"
+
+
+async def token_provider() -> str:
+    """Return a test access token."""
+    return "token"
+
+
+@pytest.mark.asyncio
+async def test_get_gateway_devices() -> None:
+    """Return gateway devices from the API."""
+    payload = [{"id": "gateway-1", "deviceModel": "test"}]
+
+    async with aiohttp.ClientSession() as session:
+        with aioresponses() as mocked:
+            mocked.get(
+                f"{BASE_URL}/v1/gateway-devices",
+                payload=payload,
+                headers={"X-RateLimit-Remaining-day": "123"},
+            )
+            client = OnectaClient(session, token_provider)
+
+            assert await client.get_gateway_devices() == payload
+            assert client.rate_limit.day_remaining == 123
+
+
+@pytest.mark.asyncio
+async def test_rate_limit_error() -> None:
+    """Expose Daikin retry-after information on HTTP 429."""
+    async with aiohttp.ClientSession() as session:
+        with aioresponses() as mocked:
+            mocked.get(
+                f"{BASE_URL}/v1/gateway-devices",
+                status=429,
+                headers={"Retry-After": "60"},
+            )
+            client = OnectaClient(session, token_provider)
+
+            with pytest.raises(OnectaRateLimitError) as exc_info:
+                await client.get_gateway_devices()
+
+            assert exc_info.value.retry_after == 60
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("status", [401, 403])
+async def test_authentication_error(status: int) -> None:
+    """Translate authentication failures to a dedicated exception."""
+    async with aiohttp.ClientSession() as session:
+        with aioresponses() as mocked:
+            mocked.get(f"{BASE_URL}/v1/gateway-devices", status=status)
+            client = OnectaClient(session, token_provider)
+
+            with pytest.raises(OnectaAuthenticationError):
+                await client.get_gateway_devices()
+
+
+@pytest.mark.asyncio
+async def test_unexpected_api_error() -> None:
+    """Raise an API error instead of returning an empty device list."""
+    async with aiohttp.ClientSession() as session:
+        with aioresponses() as mocked:
+            mocked.get(f"{BASE_URL}/v1/gateway-devices", status=500, body="server error")
+            client = OnectaClient(session, token_provider)
+
+            with pytest.raises(OnectaApiError) as exc_info:
+                await client.get_gateway_devices()
+
+            assert exc_info.value.status == 500

daikin_onecta-0.1.0/tests/test_rate_limit.py

@@ -0,0 +1,32 @@
+"""Tests for Daikin Onecta rate-limit parsing."""
+
+from daikin_onecta import RateLimit
+
+
+def test_rate_limit_from_headers() -> None:
+    """Parse all supported Daikin rate-limit headers."""
+    rate_limit = RateLimit.from_headers(
+        {
+            "X-RateLimit-Limit-minute": "20",
+            "X-RateLimit-Limit-day": "200",
+            "X-RateLimit-Remaining-minute": "7",
+            "X-RateLimit-Remaining-day": "123",
+            "Retry-After": "42",
+            "RateLimit-Reset": "99",
+        }
+    )
+
+    assert rate_limit.minute_limit == 20
+    assert rate_limit.day_limit == 200
+    assert rate_limit.minute_remaining == 7
+    assert rate_limit.day_remaining == 123
+    assert rate_limit.retry_after == 42
+    assert rate_limit.reset == 99
+
+
+def test_rate_limit_ignores_invalid_headers() -> None:
+    """Invalid or absent headers should not break a request."""
+    rate_limit = RateLimit.from_headers({"Retry-After": "invalid"})
+
+    assert rate_limit.retry_after is None
+    assert rate_limit.minute_limit is None