python-siseli 0.1.0__tar.gz

python_siseli-0.1.0/PKG-INFO

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

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

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=42"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "python-siseli"
+version = "0.1.0"
+description = "Python SDK for Siseli Cloud"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["siseli*"]

python_siseli-0.1.0/python_siseli.egg-info/PKG-INFO

@@ -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/python_siseli.egg-info/SOURCES.txt

@@ -0,0 +1,33 @@
+README.md
+pyproject.toml
+python_siseli.egg-info/PKG-INFO
+python_siseli.egg-info/SOURCES.txt
+python_siseli.egg-info/dependency_links.txt
+python_siseli.egg-info/requires.txt
+python_siseli.egg-info/top_level.txt
+siseli/__init__.py
+siseli/_utils.py
+siseli/alarms.py
+siseli/auth.py
+siseli/client.py
+siseli/config.py
+siseli/const.py
+siseli/dashboard.py
+siseli/device.py
+siseli/dictionary.py
+siseli/exceptions.py
+siseli/history.py
+siseli/state.py
+siseli/station.py
+siseli/models/__init__.py
+siseli/models/alarm.py
+siseli/models/auth.py
+siseli/models/common.py
+siseli/models/config.py
+siseli/models/dashboard.py
+siseli/models/device.py
+siseli/models/dictionary.py
+siseli/models/history.py
+siseli/models/state.py
+siseli/models/station.py
+tests/test_phase3.py

python_siseli-0.1.0/python_siseli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

python_siseli-0.1.0/python_siseli.egg-info/requires.txt

@@ -0,0 +1,6 @@
+httpx>=0.27
+
+[dev]
+pytest>=8
+pytest-asyncio>=0.23
+respx>=0.21

python_siseli-0.1.0/python_siseli.egg-info/top_level.txt

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

python_siseli-0.1.0/setup.cfg

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

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

python_siseli-0.1.0/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

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

python_siseli-0.1.0/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