python-siseli 0.1.0__py3-none-any.whl

siseli/device.py

@@ -0,0 +1,89 @@
+"""Device discovery and details."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Awaitable, Callable
+
+from .models.device import Device
+
+RequestFunc = Callable[..., Awaitable[Any]]
+
+
+def _dt(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def _parse_device(raw: dict) -> Device:
+    return Device(
+        id=raw["id"],
+        name=raw.get("name", ""),
+        serial_number=raw.get("serialNumber", ""),
+        state=raw.get("state", 0),
+        is_online=raw.get("isOnline", False),
+        device_sort_key=raw.get("deviceSortKey", ""),
+        station_id=raw.get("stationId"),
+        station_name=raw.get("stationName"),
+        station_timezone=raw.get("stationTimezone"),
+        rated_power=raw.get("ratedPower", 0.0),
+        producing_power=raw.get("producingPower", 0.0),
+        model=raw.get("model"),
+        software_version=raw.get("softwareVersion"),
+        last_data_at=_dt(raw.get("lastDataAt")),
+        last_online_at=_dt(raw.get("lastOnlineAt")),
+        created_at=_dt(raw.get("createdAt")),
+        raw=raw,
+    )
+
+
+async def fetch_device_list(
+    request: RequestFunc,
+    *,
+    page: int = 1,
+    count: int = 20,
+    name: str = "",
+    serial_number: str = "",
+    station_id: str = "",
+    state: str = "",
+) -> tuple[list[Device], int]:
+    """Return a page of devices and the total count.
+
+    :param request: Authenticated request callable from :class:`SiseliClient`.
+    :param page: 1-based page number.
+    :param count: Page size.
+    :param name: Optional name filter (substring match).
+    :param serial_number: Optional serial number filter.
+    :param station_id: Optional station filter.
+    :param state: Optional state filter.
+    :returns: ``(devices, total)`` tuple.
+    """
+    data = await request(
+        "POST",
+        "/apis/device/list",
+        json={
+            "page": page,
+            "count": count,
+            "name": name,
+            "serialNumber": serial_number,
+            "stationId": station_id,
+            "state": state,
+            "fieldNames": [],
+            "exportType": 0,
+            "applyModeCategory": 1,
+        },
+    )
+    devices = [_parse_device(d) for d in data.get("list", [])]
+    total: int = data.get("total", len(devices))
+    return devices, total
+
+
+async def fetch_device_details(request: RequestFunc, device_id: str) -> Device:
+    """Return full details for a single device.
+
+    :param request: Authenticated request callable from :class:`SiseliClient`.
+    :param device_id: The device ID.
+    """
+    data = await request("GET", "/apis/device/details", params={"deviceId": device_id})
+    return _parse_device(data)

siseli/dictionary.py

@@ -0,0 +1,37 @@
+"""Lookup dictionary helpers."""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable
+
+from .models.common import LookupValue
+from .models.dictionary import DictionaryData
+
+RequestFunc = Callable[..., Awaitable[Any]]
+
+
+
+def _parse_lookup_values(values: list[dict] | None) -> list[LookupValue]:
+    if not values:
+        return []
+    return [
+        LookupValue(
+            value=item.get("value"),
+            name=item.get("name", item.get("text", item.get("localeText", ""))),
+            locale_text=item.get("localeText"),
+            raw=item,
+        )
+        for item in values
+    ]
+
+
+async def fetch_dictionary(request: RequestFunc, name: str) -> DictionaryData:
+    """Return one dictionary dataset by name."""
+    data = await request("GET", f"/apis/dictionary/data/{name}")
+    metadata = {key: item for key, item in data.items() if not isinstance(item, list)}
+    values = {
+        key: _parse_lookup_values(item)
+        for key, item in data.items()
+        if isinstance(item, list)
+    }
+    return DictionaryData(name=name, values=values, raw=data, metadata=metadata)

siseli/exceptions.py

@@ -0,0 +1,28 @@
+"""Exception hierarchy for the Siseli SDK."""
+
+from __future__ import annotations
+
+
+class SiseliError(Exception):
+    """Base exception for all Siseli SDK errors."""
+
+
+class AuthenticationError(SiseliError):
+    """Raised when authentication fails."""
+
+
+class TokenExpiredError(AuthenticationError):
+    """Raised when the access token has expired and cannot be refreshed."""
+
+
+class ApiError(SiseliError):
+    """Raised when the API returns a non-zero response code."""
+
+    def __init__(self, code: int, message: str) -> None:
+        self.code = code
+        self.message = message
+        super().__init__(f"API error {code}: {message}")
+
+
+class NetworkError(SiseliError):
+    """Raised on network-level failures (connection errors, timeouts, etc.)."""

siseli/history.py

@@ -0,0 +1,123 @@
+"""Historical telemetry retrieval."""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Iterable
+
+from ._utils import extract_value, parse_datetime, serialize_datetime
+from .const import DEFAULT_PAGE_SIZE
+from .models.history import HistoryRecord, HistorySeries
+
+RequestFunc = Callable[..., Awaitable[Any]]
+
+
+def _build_history_records(
+    time_series: list[str],
+    fields: dict[str, list[Any]],
+) -> list[HistoryRecord]:
+    records: list[HistoryRecord] = []
+    for index, timestamp in enumerate(time_series):
+        values = {
+            key: extract_value(series[index]) if index < len(series) else None
+            for key, series in fields.items()
+        }
+        records.append(
+            HistoryRecord(
+                time=parse_datetime(timestamp),
+                values=values,
+                raw={
+                    "time": timestamp,
+                    "values": {
+                        key: series[index] if index < len(series) else None
+                        for key, series in fields.items()
+                    },
+                },
+            )
+        )
+    return records
+
+
+async def fetch_attribute_history(
+    request: RequestFunc,
+    device_id: str,
+    keys: Iterable[str],
+    *,
+    from_time: Any = None,
+    to_time: Any = None,
+    page: int = 1,
+    count: int = DEFAULT_PAGE_SIZE,
+    order_by_time_asc: bool = True,
+) -> HistorySeries:
+    """Return history for selected attribute keys."""
+    data = await request(
+        "POST",
+        "/apis/deviceState/simple/attribute/keys/history/v1",
+        json={
+            "deviceId": device_id,
+            "keys": list(keys),
+            "fromTime": serialize_datetime(from_time),
+            "toTime": serialize_datetime(to_time),
+            "page": page,
+            "count": count,
+            "orderByTimeAsc": order_by_time_asc,
+        },
+    )
+    payload = data.get("payload", {})
+    raw_fields = payload.get("fields", {})
+    time_series = payload.get("timeSeries", [])
+    normalized_fields = {
+        key: [extract_value(value) for value in values]
+        for key, values in raw_fields.items()
+    }
+    return HistorySeries(
+        page=data.get("page", page),
+        count=data.get("count", count),
+        total=data.get("total", len(time_series)),
+        time_series=[parse_datetime(value) for value in time_series],
+        fields=normalized_fields,
+        formatters=payload.get("formatters", {}),
+        records=_build_history_records(time_series, raw_fields),
+        raw=data,
+    )
+
+
+async def fetch_state_history(
+    request: RequestFunc,
+    device_id: str,
+    *,
+    from_time: Any = None,
+    to_time: Any = None,
+    page: int = 1,
+    count: int = DEFAULT_PAGE_SIZE,
+    order_by_time_asc: bool = False,
+) -> HistorySeries:
+    """Return paginated historical device state records."""
+    data = await request(
+        "POST",
+        "/apis/deviceState/simple/attribute/record/list/v1",
+        json={
+            "deviceId": device_id,
+            "fromTime": serialize_datetime(from_time),
+            "toTime": serialize_datetime(to_time),
+            "page": page,
+            "count": count,
+            "orderByTimeAsc": order_by_time_asc,
+        },
+    )
+    payload = data.get("payload", {})
+    raw_fields = payload.get("fields", {})
+    time_series = payload.get("timeSeries", [])
+    normalized_fields = {
+        key: [extract_value(value) for value in values]
+        for key, values in raw_fields.items()
+    }
+    return HistorySeries(
+        page=data.get("page", page),
+        count=data.get("count", count),
+        total=data.get("total", len(time_series)),
+        time_series=[parse_datetime(value) for value in time_series],
+        fields=normalized_fields,
+        formatters={},
+        records=_build_history_records(time_series, raw_fields),
+        raw=data,
+    )

siseli/models/__init__.py

@@ -0,0 +1,50 @@
+"""Public re-exports from all model modules."""
+
+from .alarm import Alarm, AlarmReport
+from .auth import TokenInfo
+from .common import CountByValue, LookupValue, PagedResult, TimePoint
+from .config import ConfigBatchRead
+from .dashboard import DashboardSummary, LocationDistribution, StationRankEntry
+from .device import Device
+from .dictionary import DictionaryData
+from .history import HistoryRecord, HistorySeries
+from .state import (
+    AttributeGroup,
+    AttributeGroupSet,
+    AttributeMetadata,
+    DeviceState,
+    EnergyFlow,
+    FlowNode,
+    StateAttribute,
+)
+from .station import Station, StationEnergyFlow, StationSummary, SummaryCategory, SummaryProperty
+
+__all__ = [
+    "Alarm",
+    "AlarmReport",
+    "AttributeGroup",
+    "AttributeGroupSet",
+    "AttributeMetadata",
+    "ConfigBatchRead",
+    "CountByValue",
+    "DashboardSummary",
+    "Device",
+    "DeviceState",
+    "DictionaryData",
+    "EnergyFlow",
+    "FlowNode",
+    "HistoryRecord",
+    "HistorySeries",
+    "LocationDistribution",
+    "LookupValue",
+    "PagedResult",
+    "StateAttribute",
+    "Station",
+    "StationEnergyFlow",
+    "StationRankEntry",
+    "StationSummary",
+    "SummaryCategory",
+    "SummaryProperty",
+    "TimePoint",
+    "TokenInfo",
+]

siseli/models/alarm.py

@@ -0,0 +1,41 @@
+"""Alarm-related models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass
+class Alarm:
+    """One alarm entry."""
+
+    id: str
+    device_id: str | None
+    device_serial_number: str | None
+    device_name: str | None
+    station_id: str | None
+    station_name: str | None
+    level: int | None
+    state: int | None
+    category: int | None
+    title: str | None
+    content: str | None
+    created_at: datetime | None
+    processed_at: datetime | None
+    raw: dict = field(repr=False)
+
+
+@dataclass
+class AlarmReport:
+    """Alarm report/export entry."""
+
+    id: str
+    remark: str | None
+    report_from_time: datetime | None
+    report_to_time: datetime | None
+    progress: int | None
+    state: int | None
+    download_resid: str | None
+    created_at: datetime | None
+    raw: dict = field(repr=False)

siseli/models/auth.py

@@ -0,0 +1,19 @@
+"""Auth-related models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass
+class TokenInfo:
+    """Tokens returned by a successful login."""
+
+    access_token: str
+    refresh_token: str
+    access_token_expires_at: datetime
+    refresh_token_expires_at: datetime
+    auth_id: str
+    account: str
+    user_id: str

siseli/models/common.py

@@ -0,0 +1,51 @@
+"""Common models shared by multiple Siseli API areas."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass
+class LookupValue:
+    """One value from a lookup table or enum."""
+
+    value: Any
+    name: str
+    locale_text: str | None
+    raw: dict = field(repr=False)
+
+
+@dataclass
+class CountByValue:
+    """Count grouped by a dictionary value."""
+
+    value: Any
+    count: int
+    label: str | None
+    raw: dict = field(repr=False)
+
+
+@dataclass
+class TimePoint:
+    """One aggregated point in a time series."""
+
+    time: datetime | None
+    time_display: str
+    value: Any
+    is_real_value: bool | None
+    raw: dict = field(repr=False)
+
+
+@dataclass
+class PagedResult(Generic[T]):
+    """Generic paginated response wrapper."""
+
+    page: int
+    count: int
+    total: int
+    items: list[T]
+    raw: dict = field(repr=False)

siseli/models/config.py

@@ -0,0 +1,28 @@
+"""Remote configuration models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from .state import AttributeMetadata
+
+
+@dataclass
+class ConfigBatchRead:
+    """Batch configuration read request and its progress."""
+
+    id: str
+    device_id: str
+    scene: int | None
+    request_keys: list[str]
+    target_config: dict[str, AttributeMetadata]
+    gather_protocol_version_id: str | None
+    gather_protocol_version_code: str | None
+    start_at: datetime | None
+    end_at: datetime | None
+    error: Any
+    is_finished: bool
+    created_at: datetime | None
+    raw: dict = field(repr=False)

siseli/models/dashboard.py

@@ -0,0 +1,45 @@
+"""Dashboard models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .common import CountByValue, TimePoint
+
+
+@dataclass
+class StationRankEntry:
+    """Dashboard station ranking entry."""
+
+    name: str
+    full_time: float | int | None
+    raw: dict = field(repr=False)
+
+
+@dataclass
+class DashboardSummary:
+    """Dashboard summary counters."""
+
+    daily_produced_quantity: float | int | None
+    total_produced_quantity: float | int | None
+    total_power: float | int | None
+    saving_standard_carbon: float | int | None
+    co2_emission_reduction: float | int | None
+    so2_emission_reduction: float | int | None
+    nox_emission_reduction: float | int | None
+    devices_number: int | None
+    all_installed_capacity: float | int | None
+    station_total_number: int | None
+    station_state_summary: list[CountByValue]
+    raw: dict = field(repr=False)
+
+
+@dataclass
+class LocationDistribution:
+    """Dashboard location distribution entry."""
+
+    name: str | None
+    longitude: float | None
+    latitude: float | None
+    raw: dict = field(repr=False)

siseli/models/device.py

@@ -0,0 +1,29 @@
+"""Device-related models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass
+class Device:
+    """A Siseli device (inverter, battery, etc.)."""
+
+    id: str
+    name: str
+    serial_number: str
+    state: int
+    is_online: bool
+    device_sort_key: str
+    station_id: str | None
+    station_name: str | None
+    station_timezone: str | None
+    rated_power: float
+    producing_power: float
+    model: str | None
+    software_version: str | None
+    last_data_at: datetime | None
+    last_online_at: datetime | None
+    created_at: datetime | None
+    raw: dict = field(repr=False)

siseli/models/dictionary.py

@@ -0,0 +1,18 @@
+"""Dictionary and metadata models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .common import LookupValue
+
+
+@dataclass
+class DictionaryData:
+    """One dictionary dataset returned by the API."""
+
+    name: str
+    values: dict[str, list[LookupValue]]
+    raw: dict = field(repr=False)
+    metadata: dict[str, Any] = field(default_factory=dict, repr=False)

siseli/models/history.py

@@ -0,0 +1,34 @@
+"""Historical telemetry models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+
+@dataclass
+class HistoryRecord:
+    """One timestamped historical record."""
+
+    time: datetime | None
+    values: dict[str, Any]
+    raw: dict = field(repr=False)
+
+
+@dataclass
+class HistorySeries:
+    """Historical attribute values for a device."""
+
+    page: int
+    count: int
+    total: int
+    time_series: list[datetime | None]
+    fields: dict[str, list[Any]]
+    formatters: dict[str, Any]
+    records: list[HistoryRecord]
+    raw: dict = field(repr=False)
+
+    def get_series(self, key: str) -> list[Any]:
+        """Return all values for one key, preserving API order."""
+        return self.fields.get(key, [])