python-siseli 0.1.0__py3-none-any.whl

python_siseli-0.1.0.dist-info/METADATA

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: python-siseli
+Version: 0.1.0
+Summary: Python SDK for Siseli Cloud
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+
+# python-siseli
+
+Python SDK for [Siseli Cloud](https://solar.siseli.com).
+
+## Installation
+
+```bash
+pip install python-siseli
+```
+
+## Quick start
+
+```python
+import asyncio
+from siseli import SiseliClient
+
+async def main():
+    async with SiseliClient("user@example.com", "secret", timezone="Europe/Warsaw") as client:
+        # Discover devices
+        devices = await client.get_devices()
+        device = devices[0]
+        print(f"Device: {device.name} ({device.id})")
+
+        # Latest telemetry
+        state = await client.get_device_state(device.id)
+        grid = state.get("gridVoltage")
+        if grid:
+            print(f"Grid voltage: {grid.value_display} {grid.unit}")
+
+        # Energy flow diagram
+        flow = await client.get_energy_flow(device.id)
+        if flow.battery:
+            print(f"Battery: {flow.battery.value.value_display} {flow.battery.value.unit}")
+
+asyncio.run(main())
+```
+
+## Development plan
+
+See [`roadmap.md`](roadmap.md) for the full development plan.
+
+## API documentation
+
+See [`docs/api.md`](docs/api.md).

python_siseli-0.1.0.dist-info/RECORD

@@ -0,0 +1,29 @@
+siseli/__init__.py,sha256=_sHO0M0medXnJz_ZTtHKyy8DP6e40wuf5ubEGLC1kBs,1035
+siseli/_utils.py,sha256=QT-ooemKKAIEHICNI2QErPvRkFIkUGo6ncUFCJM1kGc,727
+siseli/alarms.py,sha256=Mc_CV8kUBFTXu8c48NstX8Lc6Q0bPTnhjwehx9sbCkQ,4853
+siseli/auth.py,sha256=L-aT_R9CQDrnwx6uiGR4aYaEdb3ky2DFQgqkW0x5cEM,3356
+siseli/client.py,sha256=Eap7MTrnctdskt6kOzbns7SqUt27ZDjMlIKVshfcfN8,14200
+siseli/config.py,sha256=J8raq7Yf4gCyjO9ISNoTrk_EYNEGrESV56O-aHfDvBU,3278
+siseli/const.py,sha256=M8bBrc8cH0OyEGb9158_emux_dfknvikGQqm09iQ8CA,174
+siseli/dashboard.py,sha256=JQHfi8orKs5uWsGGfoTvA14A9M_R9yIAYuGCxb4zTsM,3325
+siseli/device.py,sha256=crix14pYakrDaFmomPC3Uwgdq-1boZ-ZaEg2HgzXibs,2762
+siseli/dictionary.py,sha256=VSO83uXPaGLPzKGRmpROuWQKivXN7DNOmXN8QQJ-Y-w,1120
+siseli/exceptions.py,sha256=Y34NlvH8Lx1Hf1tQY8rlmbtEElR9TCq-RmH5zrj9b3A,757
+siseli/history.py,sha256=CgBvDfZBIrrewu7PeRv08-Zr4boEVOY8Xevruu-ge-I,3869
+siseli/state.py,sha256=d7Exlf7FzF8O_CcF-NbAt6kq8qaR4fFhjGW8028kbrM,5800
+siseli/station.py,sha256=e1OK4OIry9WUjT8KggQI5b4Acypm9D31mWAMTjDGFew,5531
+siseli/models/__init__.py,sha256=WSIXRM_JRKNhB_hDwxrpeQgdqKUHdbT3KiFvdrLrrzY,1242
+siseli/models/alarm.py,sha256=Id8OyN2HQ-EeU-E9AleUHmhFuOyTH27r1G5pT3g8nzM,887
+siseli/models/auth.py,sha256=u9mpkhJ-1lhBQWHkgTKCdSdvVufufWhwyjs_jR0TKd8,381
+siseli/models/common.py,sha256=zOEz8W-NGaNW7H-jUYOup7D9-cidWpvpRjeTRTe3WiY,960
+siseli/models/config.py,sha256=VXlzXYij6ZhY0zmdaTjVxiA86H46mczBwcMI9L-xMf0,680
+siseli/models/dashboard.py,sha256=P86feNI8Yn6ADkwDGFQJFUESrKLt6VttGqsEiNzGnZA,1125
+siseli/models/device.py,sha256=u57-csypaF-c5hAimqb8GIMeZqYZMKMhYFBTVuBRSfQ,657
+siseli/models/dictionary.py,sha256=d6KCu77UMlPcIDON8G3sjuytkSfbI5go1y3I_jAGTX8,422
+siseli/models/history.py,sha256=dx26VWLJosucMvwL36vojvAguvkMiv5GEKTllUtZV0Y,791
+siseli/models/state.py,sha256=VK5CNqMLRkY1w9HrcUhvaO_6J-rjqP7VwvbppCFpucI,2393
+siseli/models/station.py,sha256=02OLINAVblnKkF73ZwKxYvPtUFROsu4-g544oDg8ApA,1783
+python_siseli-0.1.0.dist-info/METADATA,sha256=6ie6JBHG1D8xEGY9afztyw-LaAVSM9Zn2y0LK8BZPRg,1407
+python_siseli-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+python_siseli-0.1.0.dist-info/top_level.txt,sha256=Dofr9c7hGvRRV6ij6aoPuAZqxEjkgtsBeN4KtFHbGgo,7
+python_siseli-0.1.0.dist-info/RECORD,,

python_siseli-0.1.0.dist-info/WHEEL

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

python_siseli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+siseli

siseli/__init__.py

@@ -0,0 +1,51 @@
+"""python-siseli — Python SDK for Siseli Cloud."""
+
+from .client import SiseliClient
+from .exceptions import ApiError, AuthenticationError, NetworkError, SiseliError, TokenExpiredError
+from .models import (
+    Alarm,
+    AlarmReport,
+    AttributeGroup,
+    AttributeGroupSet,
+    AttributeMetadata,
+    ConfigBatchRead,
+    DashboardSummary,
+    Device,
+    DeviceState,
+    DictionaryData,
+    EnergyFlow,
+    FlowNode,
+    HistorySeries,
+    PagedResult,
+    StateAttribute,
+    Station,
+    StationEnergyFlow,
+    TokenInfo,
+)
+
+__all__ = [
+    "SiseliClient",
+    "SiseliError",
+    "AuthenticationError",
+    "TokenExpiredError",
+    "ApiError",
+    "NetworkError",
+    "Alarm",
+    "AlarmReport",
+    "AttributeGroup",
+    "AttributeGroupSet",
+    "AttributeMetadata",
+    "ConfigBatchRead",
+    "DashboardSummary",
+    "Device",
+    "DeviceState",
+    "DictionaryData",
+    "EnergyFlow",
+    "FlowNode",
+    "HistorySeries",
+    "PagedResult",
+    "StateAttribute",
+    "Station",
+    "StationEnergyFlow",
+    "TokenInfo",
+]

siseli/_utils.py

@@ -0,0 +1,29 @@
+"""Shared parsing helpers for Siseli API payloads."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+
+def parse_datetime(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def serialize_datetime(value: datetime | str | None) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return value
+    return value.isoformat().replace("+00:00", "Z")
+
+
+def extract_value(raw: Any) -> Any:
+    if not isinstance(raw, dict):
+        return raw
+    for key in ("vd", "valueDisplay", "value"):
+        if key in raw:
+            return raw[key]
+    return raw

siseli/alarms.py

@@ -0,0 +1,159 @@
+"""Alarm retrieval helpers."""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable
+
+from ._utils import parse_datetime, serialize_datetime
+from .const import DEFAULT_PAGE_SIZE
+from .models.alarm import Alarm, AlarmReport
+from .models.common import PagedResult
+
+RequestFunc = Callable[..., Awaitable[Any]]
+
+
+
+def _parse_alarm(raw: dict) -> Alarm:
+    return Alarm(
+        id=raw.get("id", ""),
+        device_id=raw.get("deviceId"),
+        device_serial_number=raw.get("deviceSerialNumber"),
+        device_name=raw.get("deviceName"),
+        station_id=raw.get("stationId"),
+        station_name=raw.get("stationName"),
+        level=raw.get("level"),
+        state=raw.get("state"),
+        category=raw.get("category"),
+        title=raw.get("title") or raw.get("name") or raw.get("alarmName"),
+        content=raw.get("content") or raw.get("message") or raw.get("remark"),
+        created_at=parse_datetime(raw.get("createdAt")),
+        processed_at=parse_datetime(raw.get("processedAt")),
+        raw=raw,
+    )
+
+
+
+def _parse_alarm_report(raw: dict) -> AlarmReport:
+    return AlarmReport(
+        id=raw.get("id", ""),
+        remark=raw.get("remark"),
+        report_from_time=parse_datetime(raw.get("reportFromTime")),
+        report_to_time=parse_datetime(raw.get("reportToTime") or raw.get("reportToFime")),
+        progress=raw.get("progress"),
+        state=raw.get("state"),
+        download_resid=raw.get("downloadResid"),
+        created_at=parse_datetime(raw.get("createdAt")),
+        raw=raw,
+    )
+
+
+async def fetch_latest_alarm(
+    request: RequestFunc,
+    *,
+    certificate_dtu_id: str = "",
+    device_serial_number: str = "",
+    page: int = 1,
+    count: int = 1,
+) -> Alarm | None:
+    """Return the latest alarm matching filters."""
+    data = await request(
+        "POST",
+        "/apis/alarm/getLatestAlarm",
+        json={
+            "certificateDtuID": certificate_dtu_id,
+            "deviceSerialNumber": device_serial_number,
+            "page": page,
+            "count": count,
+        },
+    )
+    if not data:
+        return None
+    return _parse_alarm(data)
+
+
+async def fetch_alarm_list(
+    request: RequestFunc,
+    *,
+    page: int = 1,
+    count: int = DEFAULT_PAGE_SIZE,
+    certificate_dtu_id: str = "",
+    device_serial_number: str = "",
+    from_time: Any = None,
+    to_time: Any = None,
+    is_processed: int | None = None,
+    level: int | None = None,
+    order_by_created_time_desc: bool = True,
+) -> PagedResult[Alarm]:
+    """Return paginated alarm history."""
+    data = await request(
+        "POST",
+        "/apis/alarm/query/list",
+        json={
+            "page": page,
+            "count": count,
+            "certificateDtuID": certificate_dtu_id,
+            "deviceSerialNumber": device_serial_number,
+            "fromTime": serialize_datetime(from_time),
+            "toTime": serialize_datetime(to_time),
+            "isProcessed": is_processed,
+            "level": level,
+            "orderByCreatedTimeDesc": order_by_created_time_desc,
+        },
+    )
+    items = [_parse_alarm(item) for item in data.get("list", [])]
+    return PagedResult(
+        page=data.get("page", page),
+        count=data.get("count", count),
+        total=data.get("total", len(items)),
+        items=items,
+        raw=data,
+    )
+
+
+async def fetch_alarm_report_headers(request: RequestFunc) -> list[dict[str, Any]]:
+    """Return alarm report column definitions."""
+    return await request("GET", "/apis/alarm/report/alarmList/headers")
+
+
+async def fetch_alarm_report_details(request: RequestFunc, record_id: str) -> dict[str, Any]:
+    """Return details for one alarm report record."""
+    return await request(
+        "GET",
+        "/apis/alarm/report/record/details",
+        params={"id": record_id},
+    )
+
+
+async def fetch_alarm_reports(
+    request: RequestFunc,
+    *,
+    page: int = 1,
+    count: int = DEFAULT_PAGE_SIZE,
+    dtu_id: str = "",
+    state: int | None = None,
+    created_from_time: Any = None,
+    created_to_time: Any = None,
+    order_by_created_at_asc: bool = False,
+) -> PagedResult[AlarmReport]:
+    """Return alarm report/export history."""
+    data = await request(
+        "POST",
+        "/apis/alarm/report/record/list",
+        json={
+            "page": page,
+            "count": count,
+            "dtuID": dtu_id,
+            "state": state,
+            "createdFromTime": serialize_datetime(created_from_time),
+            "createdToTime": serialize_datetime(created_to_time),
+            "orderByCreatedAtAsc": order_by_created_at_asc,
+        },
+    )
+    items = [_parse_alarm_report(item) for item in data.get("list", [])]
+    return PagedResult(
+        page=data.get("page", page),
+        count=data.get("count", count),
+        total=data.get("total", len(items)),
+        items=items,
+        raw=data,
+    )

siseli/auth.py

@@ -0,0 +1,96 @@
+"""Authentication: login and token lifecycle management."""
+
+from __future__ import annotations
+
+import hashlib
+from datetime import UTC, datetime
+
+import httpx
+
+from .exceptions import AuthenticationError
+from .models.auth import TokenInfo
+
+
+def _md5(text: str) -> str:
+    # The Siseli Cloud API requires the MD5 hash of the plaintext password.
+    # This is a protocol constraint imposed by the server, not a local
+    # password-storage decision.  The hash is sent over HTTPS and is never
+    # stored on disk.
+    return hashlib.md5(text.encode()).hexdigest()  # noqa: S324
+
+
+def _parse_dt(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+class Auth:
+    """Manages credentials and the current access token.
+
+    The password is hashed with MD5 before being sent to the API, which
+    matches the behaviour observed in the browser client.
+    """
+
+    def __init__(self, account: str, password: str) -> None:
+        self._account = account
+        # The web client sends the MD5 hash of the plaintext password.
+        self._password_hash = _md5(password)
+        self._token_info: TokenInfo | None = None
+
+    async def login(self, http: httpx.AsyncClient) -> TokenInfo:
+        """Authenticate and store the returned tokens.
+
+        Raises :exc:`~siseli.exceptions.AuthenticationError` on failure.
+        """
+        try:
+            response = await http.post(
+                "/apis/login/account",
+                json={"account": self._account, "password": self._password_hash},
+            )
+            response.raise_for_status()
+        except httpx.HTTPError as exc:
+            raise AuthenticationError(f"Login request failed: {exc}") from exc
+
+        body = response.json()
+        if body.get("code") != 0:
+            raise AuthenticationError(
+                f"Login failed (code {body.get('code')}): {body.get('message')}"
+            )
+
+        data = body["data"]
+        self._token_info = TokenInfo(
+            access_token=data["accessToken"],
+            refresh_token=data["refreshToken"],
+            access_token_expires_at=_parse_dt(data.get("accessTokenWillExpiredAt")),
+            refresh_token_expires_at=_parse_dt(data.get("refreshTokenWillExpiredAt")),
+            auth_id=data.get("authId", ""),
+            account=data.get("account", self._account),
+            user_id=data.get("userId", ""),
+        )
+        return self._token_info
+
+    @property
+    def access_token(self) -> str:
+        """Return the current access token.
+
+        Raises :exc:`~siseli.exceptions.AuthenticationError` if not yet
+        authenticated.
+        """
+        if self._token_info is None:
+            raise AuthenticationError("Not authenticated — call authenticate() first")
+        return self._token_info.access_token
+
+    @property
+    def token_info(self) -> TokenInfo | None:
+        """Return token metadata, or *None* if not authenticated."""
+        return self._token_info
+
+    def is_authenticated(self) -> bool:
+        """Return *True* when there is a valid, non-expired access token."""
+        if self._token_info is None:
+            return False
+        expires_at = self._token_info.access_token_expires_at
+        if expires_at is None:
+            return True
+        return datetime.now(UTC) < expires_at