python-siseli 0.1.0__py3-none-any.whl

siseli/models/state.py

@@ -0,0 +1,106 @@
+"""State, attribute, and energy-flow models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from .common import LookupValue
+
+
+@dataclass
+class StateAttribute:
+    """A single telemetry attribute."""
+
+    key: str
+    unit: str
+    value: Any
+    value_display: str
+    name_display: str
+    is_hidden: bool | None
+
+
+@dataclass
+class AttributeMetadata:
+    """Metadata describing a state or configuration attribute."""
+
+    key: str
+    name: str
+    name_display: str
+    unit: str
+    value_type: int | None
+    category: int | None
+    operation_mode: int | None
+    is_hidden: bool | None
+    is_config_attribute: bool | None
+    is_writable_config_attribute: bool | None
+    is_readable_config_attribute: bool | None
+    is_state_attribute: bool | None
+    is_event_attribute: bool | None
+    enum_values: list[LookupValue]
+    raw: dict = field(repr=False)
+
+
+@dataclass
+class AttributeGroup:
+    """A group of related device attributes."""
+
+    id: str
+    key: str
+    category: int | None
+    name: str
+    description: str
+    attributes: list[AttributeMetadata]
+    raw: dict = field(repr=False)
+
+
+@dataclass
+class AttributeGroupSet:
+    """Grouped attribute metadata for a device."""
+
+    gather_protocol_version_id: str
+    groups: list[AttributeGroup]
+    raw: dict = field(repr=False)
+
+
+@dataclass
+class DeviceState:
+    """Latest telemetry snapshot for a device."""
+
+    time: datetime | None
+    fields: dict[str, StateAttribute]
+    raw: dict = field(repr=False)
+
+    def get(self, key: str) -> StateAttribute | None:
+        """Return an attribute by its key, or *None* if not present."""
+        return self.fields.get(key)
+
+
+@dataclass
+class FlowNode:
+    """One node of the energy-flow diagram (PV panel, grid, battery, load…)."""
+
+    key: str
+    locale_title: str
+    value: StateAttribute | None
+    flow_direction: int | None
+    is_light: bool | None
+    is_enabled: bool
+    extra_values: list[StateAttribute]
+    raw: dict = field(repr=False)
+
+
+@dataclass
+class EnergyFlow:
+    """Energy-flow snapshot for a device."""
+
+    device_state: DeviceState
+    pv_panel: FlowNode | None
+    grid: FlowNode | None
+    battery: FlowNode | None
+    load: FlowNode | None
+    generator: FlowNode | None
+    ups: FlowNode | None
+    ct: FlowNode | None
+    raw: dict = field(repr=False)

siseli/models/station.py

@@ -0,0 +1,82 @@
+"""Station-related models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from .common import TimePoint
+from .state import FlowNode
+
+
+@dataclass
+class Station:
+    """A Siseli station."""
+
+    id: str
+    name: str
+    timezone: str | None
+    country: str | None
+    province: str | None
+    city: str | None
+    area: str | None
+    address: str | None
+    longitude: float | None
+    latitude: float | None
+    station_type: int | None
+    connected_grid_type: int | None
+    state: int | None
+    is_online: bool | None
+    installed_capacity: float | None
+    total_power: float | None
+    daily_produced_quantity: float | None
+    total_produced_quantity: float | None
+    created_at: datetime | None
+    raw: dict = field(repr=False)
+
+
+@dataclass
+class StationEnergyFlow:
+    """Energy-flow snapshot for a station."""
+
+    is_support_flow: bool
+    time: datetime | None
+    pv_panel: FlowNode | None
+    grid: FlowNode | None
+    battery: FlowNode | None
+    load: FlowNode | None
+    generator: FlowNode | None
+    ups: FlowNode | None
+    ct: FlowNode | None
+    raw: dict = field(repr=False)
+
+
+@dataclass
+class SummaryCategory:
+    """Summary category metadata."""
+
+    id: str
+    key: str
+    name: str
+    raw: dict = field(repr=False)
+
+
+@dataclass
+class SummaryProperty:
+    """One property within an aggregated summary."""
+
+    property: dict[str, Any]
+    time_points: list[TimePoint]
+    has_real_time_points: bool | None
+    raw: dict = field(repr=False)
+
+
+@dataclass
+class StationSummary:
+    """Aggregated station summary series."""
+
+    category: SummaryCategory | None
+    properties: list[SummaryProperty]
+    has_real_time_points: bool
+    raw: dict = field(repr=False)

siseli/state.py

@@ -0,0 +1,184 @@
+"""Device state, metadata, and energy-flow retrieval."""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable
+
+from ._utils import parse_datetime
+from .const import DEFAULT_DATA_SOURCE
+from .models.common import LookupValue
+from .models.state import (
+    AttributeGroup,
+    AttributeGroupSet,
+    AttributeMetadata,
+    DeviceState,
+    EnergyFlow,
+    FlowNode,
+    StateAttribute,
+)
+
+RequestFunc = Callable[..., Awaitable[Any]]
+
+
+
+def _parse_lookup_value(raw: dict) -> LookupValue:
+    return LookupValue(
+        value=raw.get("value"),
+        name=raw.get("text", raw.get("name", raw.get("localeText", ""))),
+        locale_text=raw.get("localeText"),
+        raw=raw,
+    )
+
+
+
+def _parse_attribute(key: str, raw: dict) -> StateAttribute:
+    return StateAttribute(
+        key=raw.get("key", key),
+        unit=raw.get("unit", ""),
+        value=raw.get("value"),
+        value_display=raw.get("valueDisplay", str(raw.get("value", ""))),
+        name_display=raw.get("nameDisplay", raw.get("name", "")),
+        is_hidden=raw.get("isHidden"),
+    )
+
+
+
+def _parse_attribute_metadata(raw: dict, key: str = "") -> AttributeMetadata:
+    enum_values = [_parse_lookup_value(item) for item in raw.get("enumValues", [])]
+    return AttributeMetadata(
+        key=raw.get("key", key),
+        name=raw.get("name", raw.get("nameDisplay", "")),
+        name_display=raw.get("nameDisplay", raw.get("name", "")),
+        unit=raw.get("unit", ""),
+        value_type=raw.get("valueType"),
+        category=raw.get("category"),
+        operation_mode=raw.get("operationMode"),
+        is_hidden=raw.get("isHidden"),
+        is_config_attribute=raw.get("isConfigAttribute"),
+        is_writable_config_attribute=raw.get("isWritableConfigAttribute"),
+        is_readable_config_attribute=raw.get("isReadableConfigAttribute"),
+        is_state_attribute=raw.get("isStateAttribute"),
+        is_event_attribute=raw.get("isEventAttribute"),
+        enum_values=enum_values,
+        raw=raw,
+    )
+
+
+
+def _parse_attribute_group(raw: dict) -> AttributeGroup:
+    return AttributeGroup(
+        id=raw.get("id", ""),
+        key=raw.get("key", ""),
+        category=raw.get("category"),
+        name=raw.get("name", ""),
+        description=raw.get("description", ""),
+        attributes=[_parse_attribute_metadata(item) for item in raw.get("attributes", [])],
+        raw=raw,
+    )
+
+
+
+def _parse_device_state(raw: dict) -> DeviceState:
+    fields_raw: dict = raw.get("fields", {})
+    fields = {key: _parse_attribute(key, attr) for key, attr in fields_raw.items()}
+    return DeviceState(
+        time=parse_datetime(raw.get("time")),
+        fields=fields,
+        raw=raw,
+    )
+
+
+
+def _parse_flow_node(raw: dict | None) -> FlowNode | None:
+    if raw is None:
+        return None
+    value_raw = raw.get("value")
+    value = _parse_attribute(raw.get("key", ""), value_raw) if value_raw else None
+    extra_values = [_parse_attribute(item.get("key", ""), item) for item in raw.get("extraValues", [])]
+    return FlowNode(
+        key=raw.get("key", ""),
+        locale_title=raw.get("localeTitle", ""),
+        value=value,
+        flow_direction=raw.get("flowDirection"),
+        is_light=raw.get("isLight"),
+        is_enabled=raw.get("isEnabled", raw.get("enabled", True)),
+        extra_values=extra_values,
+        raw=raw,
+    )
+
+
+async def fetch_device_state(
+    request: RequestFunc,
+    device_id: str,
+    *,
+    data_source: int = DEFAULT_DATA_SOURCE,
+) -> DeviceState:
+    """Return the latest telemetry snapshot for *device_id*."""
+    data = await request(
+        "GET",
+        "/apis/deviceState/simple/state/latest/v1",
+        params={"deviceId": device_id, "dataSource": data_source},
+    )
+    return _parse_device_state(data)
+
+
+async def fetch_device_attributes(
+    request: RequestFunc,
+    device_id: str,
+    *,
+    category: str = "",
+    render_in: str = "",
+) -> list[AttributeMetadata]:
+    """Return attribute metadata for the device state screen."""
+    data = await request(
+        "GET",
+        "/apis/deviceState/simple/gatherAttributes/v1",
+        params={"deviceId": device_id, "category": category, "renderIn": render_in},
+    )
+    return [_parse_attribute_metadata(item) for item in data]
+
+
+async def fetch_device_attribute_groups(
+    request: RequestFunc,
+    device_id: str,
+    *,
+    category: str = "",
+    render_in: str = "",
+) -> AttributeGroupSet:
+    """Return grouped device attribute metadata."""
+    data = await request(
+        "GET",
+        "/apis/device/query/attribute/group",
+        params={"deviceId": device_id, "category": category, "renderIn": render_in},
+    )
+    return AttributeGroupSet(
+        gather_protocol_version_id=data.get("gatherProtocolVersionId", ""),
+        groups=[_parse_attribute_group(item) for item in data.get("attributesGroups", [])],
+        raw=data,
+    )
+
+
+async def fetch_energy_flow(
+    request: RequestFunc,
+    device_id: str,
+    *,
+    data_source: int = DEFAULT_DATA_SOURCE,
+) -> EnergyFlow:
+    """Return the current energy-flow diagram data for *device_id*."""
+    data = await request(
+        "GET",
+        "/apis/deviceState/simple/energy/flow/v1",
+        params={"deviceId": device_id, "dataSource": data_source},
+    )
+    device_state = _parse_device_state(data.get("deviceAttributeState", {}))
+    return EnergyFlow(
+        device_state=device_state,
+        pv_panel=_parse_flow_node(data.get("pvPanelFlow")),
+        grid=_parse_flow_node(data.get("gridFlow")),
+        battery=_parse_flow_node(data.get("batteryFlow")),
+        load=_parse_flow_node(data.get("loadFlow")),
+        generator=_parse_flow_node(data.get("generatorFlow")),
+        ups=_parse_flow_node(data.get("upsFlow")),
+        ct=_parse_flow_node(data.get("ctFlow")),
+        raw=data,
+    )

siseli/station.py

@@ -0,0 +1,181 @@
+"""Station retrieval and aggregation 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.common import PagedResult, TimePoint
+from .models.station import Station, StationEnergyFlow, StationSummary, SummaryCategory, SummaryProperty
+from .state import _parse_flow_node
+
+RequestFunc = Callable[..., Awaitable[Any]]
+
+
+
+def _parse_station(raw: dict) -> Station:
+    return Station(
+        id=raw.get("id", ""),
+        name=raw.get("name", ""),
+        timezone=raw.get("timezone"),
+        country=raw.get("country"),
+        province=raw.get("province"),
+        city=raw.get("city"),
+        area=raw.get("area"),
+        address=raw.get("address"),
+        longitude=raw.get("longitude"),
+        latitude=raw.get("latitude"),
+        station_type=raw.get("stationType"),
+        connected_grid_type=raw.get("connectedGridType"),
+        state=raw.get("state"),
+        is_online=raw.get("isOnline"),
+        installed_capacity=raw.get("installedCapacity"),
+        total_power=raw.get("totalPower"),
+        daily_produced_quantity=raw.get("dailyProducedQuantity"),
+        total_produced_quantity=raw.get("totalProducedQuantity"),
+        created_at=parse_datetime(raw.get("createdAt")),
+        raw=raw,
+    )
+
+
+
+def _parse_time_point(raw: dict) -> TimePoint:
+    return TimePoint(
+        time=parse_datetime(raw.get("time")),
+        time_display=raw.get("timeDisplay", ""),
+        value=raw.get("value", raw.get("generatedEnergy")),
+        is_real_value=raw.get("isRealValue"),
+        raw=raw,
+    )
+
+
+
+def _parse_summary_category(raw: dict | None) -> SummaryCategory | None:
+    if raw is None:
+        return None
+    return SummaryCategory(
+        id=raw.get("id", ""),
+        key=raw.get("key", ""),
+        name=raw.get("name", ""),
+        raw=raw,
+    )
+
+
+
+def _parse_station_summary(raw: dict) -> StationSummary:
+    properties = [
+        SummaryProperty(
+            property=item.get("property", {}),
+            time_points=[_parse_time_point(point) for point in item.get("timePoints", [])],
+            has_real_time_points=item.get("hasRealTimePoints"),
+            raw=item,
+        )
+        for item in raw.get("properties", [])
+    ]
+    return StationSummary(
+        category=_parse_summary_category(raw.get("category")),
+        properties=properties,
+        has_real_time_points=raw.get("hasRealTimePoints", False),
+        raw=raw,
+    )
+
+
+async def fetch_station_list(
+    request: RequestFunc,
+    *,
+    page: int = 1,
+    count: int = DEFAULT_PAGE_SIZE,
+    name: str = "",
+    connected_grid_type: str = "",
+    state: str = "",
+    station_type: str = "",
+) -> PagedResult[Station]:
+    """Return a page of stations."""
+    data = await request(
+        "POST",
+        "/apis/station/list",
+        json={
+            "page": page,
+            "count": count,
+            "name": name,
+            "connectedGridType": connected_grid_type,
+            "state": state,
+            "stationType": station_type,
+        },
+    )
+    items = [_parse_station(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_station_details(request: RequestFunc, station_id: str) -> Station:
+    """Return station details."""
+    data = await request("GET", "/apis/station/details", params={"stationId": station_id})
+    return _parse_station(data)
+
+
+async def fetch_station_energy_flow(
+    request: RequestFunc,
+    station_id: str,
+    *,
+    is_manual_refresh: bool = False,
+) -> StationEnergyFlow:
+    """Return current station energy-flow data."""
+    data = await request(
+        "GET",
+        "/apis/station/energy/flow",
+        params={"stationId": station_id, "isManualRefresh": is_manual_refresh},
+    )
+    return StationEnergyFlow(
+        is_support_flow=data.get("isSupportFlow", False),
+        time=parse_datetime(data.get("time")),
+        pv_panel=_parse_flow_node(data.get("pvPanelFlow")),
+        grid=_parse_flow_node(data.get("gridFlow")),
+        battery=_parse_flow_node(data.get("batteryFlow")),
+        load=_parse_flow_node(data.get("loadFlow")),
+        generator=_parse_flow_node(data.get("generatorFlow")),
+        ups=_parse_flow_node(data.get("upsFlow")),
+        ct=_parse_flow_node(data.get("ctFlow")),
+        raw=data,
+    )
+
+
+async def fetch_station_income(
+    request: RequestFunc,
+    station_id: str,
+    aggregation: str,
+    *,
+    time: Any = None,
+) -> list[TimePoint]:
+    """Return aggregated station income points."""
+    data = await request(
+        "POST",
+        f"/apis/stationOverView/income/{aggregation}",
+        params={"stationId": station_id},
+        json={"time": serialize_datetime(time)},
+    )
+    return [_parse_time_point(item) for item in data]
+
+
+async def fetch_station_state_summary(
+    request: RequestFunc,
+    station_id: str,
+    summary_category_key: str,
+    aggregation: str,
+    *,
+    time: Any = None,
+) -> StationSummary:
+    """Return aggregated station summary metrics."""
+    data = await request(
+        "POST",
+        f"/apis/stationOverView/stateAttributeSummary/category/{aggregation}",
+        params={"stationId": station_id, "summaryCategoryKey": summary_category_key},
+        json={"time": serialize_datetime(time)},
+    )
+    return _parse_station_summary(data)