python-siseli 0.2.2__tar.gz → 0.2.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. {python_siseli-0.2.2 → python_siseli-0.2.3}/PKG-INFO +1 -1
  2. {python_siseli-0.2.2 → python_siseli-0.2.3}/pyproject.toml +1 -1
  3. {python_siseli-0.2.2 → python_siseli-0.2.3}/python_siseli.egg-info/PKG-INFO +1 -1
  4. {python_siseli-0.2.2 → python_siseli-0.2.3}/python_siseli.egg-info/SOURCES.txt +2 -0
  5. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/_utils.py +6 -1
  6. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/client.py +58 -0
  7. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/models/state.py +44 -4
  8. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/models/station.py +24 -0
  9. python_siseli-0.2.3/siseli/overview.py +95 -0
  10. python_siseli-0.2.3/tests/test_overview.py +140 -0
  11. {python_siseli-0.2.2 → python_siseli-0.2.3}/README.md +0 -0
  12. {python_siseli-0.2.2 → python_siseli-0.2.3}/python_siseli.egg-info/dependency_links.txt +0 -0
  13. {python_siseli-0.2.2 → python_siseli-0.2.3}/python_siseli.egg-info/requires.txt +0 -0
  14. {python_siseli-0.2.2 → python_siseli-0.2.3}/python_siseli.egg-info/top_level.txt +0 -0
  15. {python_siseli-0.2.2 → python_siseli-0.2.3}/setup.cfg +0 -0
  16. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/__init__.py +0 -0
  17. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/alarms.py +0 -0
  18. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/auth.py +0 -0
  19. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/config.py +0 -0
  20. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/const.py +0 -0
  21. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/dashboard.py +0 -0
  22. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/device.py +0 -0
  23. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/dictionary.py +0 -0
  24. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/exceptions.py +0 -0
  25. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/history.py +0 -0
  26. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/models/__init__.py +0 -0
  27. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/models/alarm.py +0 -0
  28. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/models/auth.py +0 -0
  29. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/models/common.py +0 -0
  30. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/models/config.py +0 -0
  31. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/models/dashboard.py +0 -0
  32. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/models/device.py +0 -0
  33. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/models/dictionary.py +0 -0
  34. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/models/history.py +0 -0
  35. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/open_auth.py +0 -0
  36. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/state.py +0 -0
  37. {python_siseli-0.2.2 → python_siseli-0.2.3}/siseli/station.py +0 -0
  38. {python_siseli-0.2.2 → python_siseli-0.2.3}/tests/test_auth.py +0 -0
  39. {python_siseli-0.2.2 → python_siseli-0.2.3}/tests/test_normalized_telemetry.py +0 -0
  40. {python_siseli-0.2.2 → python_siseli-0.2.3}/tests/test_open_auth.py +0 -0
  41. {python_siseli-0.2.2 → python_siseli-0.2.3}/tests/test_phase3.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: python-siseli
3
- Version: 0.2.2
3
+ Version: 0.2.3
4
4
  Summary: Python SDK for Siseli Cloud
5
5
  License: MIT
6
6
  Requires-Python: >=3.11
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "python-siseli"
7
- version = "0.2.2"
7
+ version = "0.2.3"
8
8
  description = "Python SDK for Siseli Cloud"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: python-siseli
3
- Version: 0.2.2
3
+ Version: 0.2.3
4
4
  Summary: Python SDK for Siseli Cloud
5
5
  License: MIT
6
6
  Requires-Python: >=3.11
@@ -18,6 +18,7 @@ siseli/dictionary.py
18
18
  siseli/exceptions.py
19
19
  siseli/history.py
20
20
  siseli/open_auth.py
21
+ siseli/overview.py
21
22
  siseli/state.py
22
23
  siseli/station.py
23
24
  siseli/models/__init__.py
@@ -34,4 +35,5 @@ siseli/models/station.py
34
35
  tests/test_auth.py
35
36
  tests/test_normalized_telemetry.py
36
37
  tests/test_open_auth.py
38
+ tests/test_overview.py
37
39
  tests/test_phase3.py
@@ -9,7 +9,12 @@ from typing import Any
9
9
  def parse_datetime(value: str | None) -> datetime | None:
10
10
  if not value:
11
11
  return None
12
- return datetime.fromisoformat(value.replace("Z", "+00:00"))
12
+ text = value.replace("Z", "+00:00")
13
+ if len(text) == 4 and text.isdigit():
14
+ text = f"{text}-01-01"
15
+ elif len(text) == 7 and text[4] == "-":
16
+ text = f"{text}-01"
17
+ return datetime.fromisoformat(text)
13
18
 
14
19
 
15
20
  def serialize_datetime(value: datetime | str | None) -> str | None:
@@ -42,6 +42,13 @@ from .models.dictionary import DictionaryData
42
42
  from .models.history import HistorySeries
43
43
  from .models.state import AttributeGroupSet, AttributeMetadata, DeviceState, EnergyFlow
44
44
  from .models.station import Station, StationEnergyFlow, StationSummary
45
+ from .overview import (
46
+ ENERGY_SUMMARY_CATEGORY,
47
+ fetch_device_generated_energy_daily,
48
+ fetch_device_power_class_daily_detail,
49
+ fetch_device_state_summary,
50
+ fetch_owner_state_summary,
51
+ )
45
52
  from .state import (
46
53
  fetch_device_attribute_groups,
47
54
  fetch_device_attributes,
@@ -369,6 +376,57 @@ class SiseliClient:
369
376
  time=time,
370
377
  )
371
378
 
379
+ async def get_device_summary(
380
+ self,
381
+ device_id: str,
382
+ aggregation: str,
383
+ *,
384
+ summary_category_key: str = ENERGY_SUMMARY_CATEGORY,
385
+ time: datetime | str | None = None,
386
+ ) -> StationSummary:
387
+ return await fetch_device_state_summary(
388
+ self._request,
389
+ device_id,
390
+ aggregation,
391
+ summary_category_key=summary_category_key,
392
+ time=time,
393
+ )
394
+
395
+ async def get_device_energy_totals(self, device_id: str) -> dict[str, float | None]:
396
+ """Return lifetime energy counters (kWh) keyed by property key."""
397
+ summary = await self.get_device_summary(device_id, "total")
398
+ return summary.to_totals()
399
+
400
+ async def get_owner_summary(
401
+ self,
402
+ aggregation: str,
403
+ *,
404
+ summary_category_key: str = ENERGY_SUMMARY_CATEGORY,
405
+ time: datetime | str | None = None,
406
+ ) -> StationSummary:
407
+ return await fetch_owner_state_summary(
408
+ self._request,
409
+ aggregation,
410
+ summary_category_key=summary_category_key,
411
+ time=time,
412
+ )
413
+
414
+ async def get_device_generated_energy_daily(
415
+ self,
416
+ device_id: str,
417
+ *,
418
+ time: datetime | str | None = None,
419
+ ) -> list[TimePoint]:
420
+ return await fetch_device_generated_energy_daily(self._request, device_id, time=time)
421
+
422
+ async def get_device_power_daily_detail(
423
+ self,
424
+ device_id: str,
425
+ *,
426
+ time: datetime | str | None = None,
427
+ ) -> dict[str, Any]:
428
+ return await fetch_device_power_class_daily_detail(self._request, device_id, time=time)
429
+
372
430
  async def get_latest_alarm(
373
431
  self,
374
432
  *,
@@ -104,6 +104,19 @@ class DeviceState:
104
104
  def number(api_key: str) -> float | None:
105
105
  return _numeric(value(api_key))
106
106
 
107
+ def display(api_key: str) -> str | None:
108
+ attribute = self.fields.get(api_key)
109
+ text = attribute.value_display if attribute is not None else None
110
+ return text.strip() or None if isinstance(text, str) else None
111
+
112
+ def power_watts(api_key: str) -> float | None:
113
+ # The API reports power as kW unless the unit is explicitly W.
114
+ result = number(api_key)
115
+ attribute = self.fields.get(api_key)
116
+ if result is None or attribute is None:
117
+ return result
118
+ return result if attribute.unit == "W" else result * 1000
119
+
107
120
  voltage = number("batteryVoltage")
108
121
  charging = number("batteryChargingCurrent")
109
122
  discharging = number("batteryDischargeCurrent")
@@ -112,8 +125,8 @@ class DeviceState:
112
125
  if charging is not None and discharging is not None
113
126
  else None
114
127
  )
115
- pv_power = number("generationPower")
116
- load_power = number("acOutputActivePower")
128
+ pv_power = power_watts("generationPower")
129
+ load_power = power_watts("acOutputActivePower")
117
130
  battery_power = (
118
131
  voltage * current
119
132
  if voltage is not None and current is not None
@@ -126,13 +139,40 @@ class DeviceState:
126
139
  "battery_power": battery_power,
127
140
  "pv_voltage": number("pvInputVoltage1"),
128
141
  "pv_current": number("pv1InputCurrentForBattery"),
129
- "pv_power": pv_power * 1000 if pv_power is not None else None,
142
+ "pv_power": pv_power,
130
143
  "grid_voltage": number("gridVoltage"),
131
144
  "grid_frequency": number("gridFrequency"),
132
145
  "output_voltage": number("acOutputVoltage"),
133
146
  "output_frequency": number("acOutputFrequency"),
134
- "load_power": load_power * 1000 if load_power is not None else None,
147
+ "load_power": load_power,
135
148
  "inverter_state": value("workingMode"),
149
+ "inverter_mode": display("workingMode"),
150
+ "load_percent": number("outputLoadPercent"),
151
+ "load_apparent_power": number("ratedApparentPower"),
152
+ "heat_sink_temperature": number("inverterHeatSinkTemperature"),
153
+ "bus_voltage": number("busVoltage"),
154
+ "charging_status": display("chargingStatus"),
155
+ "scc_charging_status": display("sccChargingStatus"),
156
+ "ac_charging_status": display("acChargingStatus"),
157
+ "mains_status": display("mainsStatus"),
158
+ "load_status": display("loadStatus"),
159
+ "charger_source_priority": display("chargerSourcePriority"),
160
+ "output_source_priority": display("outputSourcePriority"),
161
+ "battery_type": display("batteryType"),
162
+ }
163
+
164
+ def to_device_info(self) -> dict[str, str | None]:
165
+ """Return identification fields suitable for a device registry entry."""
166
+ def display(api_key: str) -> str | None:
167
+ attribute = self.fields.get(api_key)
168
+ text = attribute.value_display if attribute is not None else None
169
+ return text.strip() or None if isinstance(text, str) else None
170
+
171
+ return {
172
+ "protocol": display("protocolId"),
173
+ "machine_type": display("machineType"),
174
+ "firmware_version": display("mainCpuFirmwareVersion"),
175
+ "secondary_firmware_version": display("secondaryCpuFirmwareVersion"),
136
176
  }
137
177
 
138
178
 
@@ -71,6 +71,22 @@ class SummaryProperty:
71
71
  has_real_time_points: bool | None
72
72
  raw: dict = field(repr=False)
73
73
 
74
+ @property
75
+ def key(self) -> str:
76
+ return self.property.get("key", "")
77
+
78
+ @property
79
+ def unit(self) -> str:
80
+ return self.property.get("unit") or self.property.get("unitI18n", {}).get("en", "")
81
+
82
+ @property
83
+ def latest_value(self) -> float | None:
84
+ """Value of the last time point, or None when the series is empty."""
85
+ for point in reversed(self.time_points):
86
+ if isinstance(point.value, (int, float)) and not isinstance(point.value, bool):
87
+ return float(point.value)
88
+ return None
89
+
74
90
 
75
91
  @dataclass
76
92
  class StationSummary:
@@ -80,3 +96,11 @@ class StationSummary:
80
96
  properties: list[SummaryProperty]
81
97
  has_real_time_points: bool
82
98
  raw: dict = field(repr=False)
99
+
100
+ def get(self, key: str) -> SummaryProperty | None:
101
+ """Return a summary property by its key, or None if absent."""
102
+ return next((item for item in self.properties if item.key == key), None)
103
+
104
+ def to_totals(self) -> dict[str, float | None]:
105
+ """Return the latest value of every property keyed by property key."""
106
+ return {item.key: item.latest_value for item in self.properties}
@@ -0,0 +1,95 @@
1
+ """Device and owner overview (energy statistics) helpers."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from datetime import datetime
6
+ from typing import Any, Awaitable, Callable
7
+
8
+ from .models.common import TimePoint
9
+ from .models.station import StationSummary
10
+ from .station import _parse_station_summary, _parse_time_point
11
+
12
+ RequestFunc = Callable[..., Awaitable[Any]]
13
+
14
+ ENERGY_SUMMARY_CATEGORY = "pvInverterElectricityQuantityClass"
15
+ POWER_SUMMARY_CATEGORY = "pvInverterPowerClass"
16
+ AGGREGATIONS = ("daily", "monthly", "yearly", "total")
17
+
18
+ _TIME_FORMATS = {"daily": "%Y-%m-%d", "monthly": "%Y-%m", "yearly": "%Y"}
19
+
20
+
21
+ def _time_payload(aggregation: str, time: datetime | str | None) -> dict[str, str]:
22
+ """Build the request body using the time format the web UI sends."""
23
+ if aggregation not in AGGREGATIONS:
24
+ raise ValueError(f"aggregation must be one of {AGGREGATIONS}, got {aggregation!r}")
25
+ if isinstance(time, str):
26
+ return {"time": time}
27
+ moment = time or datetime.now().astimezone()
28
+ pattern = _TIME_FORMATS.get(aggregation)
29
+ return {"time": moment.strftime(pattern) if pattern else moment.isoformat()}
30
+
31
+
32
+ async def fetch_device_state_summary(
33
+ request: RequestFunc,
34
+ device_id: str,
35
+ aggregation: str,
36
+ *,
37
+ summary_category_key: str = ENERGY_SUMMARY_CATEGORY,
38
+ time: datetime | str | None = None,
39
+ ) -> StationSummary:
40
+ """Return aggregated device statistics (daily, monthly, yearly or total)."""
41
+ data = await request(
42
+ "POST",
43
+ f"/apis/deviceOverView/stateAttributeSummary/category/{aggregation}",
44
+ params={"deviceId": device_id, "summaryCategoryKey": summary_category_key},
45
+ json=_time_payload(aggregation, time),
46
+ )
47
+ return _parse_station_summary(data)
48
+
49
+
50
+ async def fetch_owner_state_summary(
51
+ request: RequestFunc,
52
+ aggregation: str,
53
+ *,
54
+ summary_category_key: str = ENERGY_SUMMARY_CATEGORY,
55
+ time: datetime | str | None = None,
56
+ ) -> StationSummary:
57
+ """Return aggregated statistics across all stations of the account."""
58
+ data = await request(
59
+ "POST",
60
+ f"/apis/ownerOverView/station/stateAttributeSummary/category/{aggregation}",
61
+ params={"summaryCategoryKey": summary_category_key},
62
+ json=_time_payload(aggregation, time),
63
+ )
64
+ return _parse_station_summary(data)
65
+
66
+
67
+ async def fetch_device_generated_energy_daily(
68
+ request: RequestFunc,
69
+ device_id: str,
70
+ *,
71
+ time: datetime | str | None = None,
72
+ ) -> list[TimePoint]:
73
+ """Return half-hourly generated energy for one day."""
74
+ data = await request(
75
+ "POST",
76
+ "/apis/deviceOverView/generatedEnergy/daily",
77
+ params={"deviceId": device_id},
78
+ json=_time_payload("daily", time),
79
+ )
80
+ return [_parse_time_point(item) for item in data]
81
+
82
+
83
+ async def fetch_device_power_class_daily_detail(
84
+ request: RequestFunc,
85
+ device_id: str,
86
+ *,
87
+ time: datetime | str | None = None,
88
+ ) -> dict[str, Any]:
89
+ """Return the raw per-day PV inverter power series (``timeSeries`` payload)."""
90
+ return await request(
91
+ "POST",
92
+ "/apis/deviceOverView/pvInverterPowerClass/daily/detail",
93
+ params={"deviceId": device_id},
94
+ json=_time_payload("daily", time),
95
+ )
@@ -0,0 +1,140 @@
1
+ """Tests for overview statistics and extended telemetry normalization."""
2
+
3
+ import asyncio
4
+ from datetime import UTC, datetime
5
+
6
+ import pytest
7
+
8
+ from siseli.models.state import DeviceState, StateAttribute
9
+ from siseli.overview import (
10
+ fetch_device_generated_energy_daily,
11
+ fetch_device_state_summary,
12
+ fetch_owner_state_summary,
13
+ )
14
+
15
+
16
+ def make_request(response):
17
+ calls = []
18
+
19
+ async def request(method, path, **kwargs):
20
+ calls.append((method, path, kwargs))
21
+ return response
22
+
23
+ return request, calls
24
+
25
+
26
+ def summary_payload() -> dict:
27
+ def prop(key, points):
28
+ return {
29
+ "property": {"key": key, "unitI18n": {"en": "kWh"}, "unit": "kWh"},
30
+ "timePoints": points,
31
+ "hasRealTimePoints": True,
32
+ }
33
+
34
+ return {
35
+ "category": {"id": "2", "key": "pvInverterElectricityQuantityClass", "name": "Energy"},
36
+ "properties": [
37
+ prop("pvGeneratedEnergy", [{"time": "2026", "timeDisplay": "2026", "value": 12.5, "isRealValue": True}]),
38
+ prop("buyElectricityQuantity", []),
39
+ ],
40
+ }
41
+
42
+
43
+ def test_device_total_summary_request_and_totals() -> None:
44
+ request, calls = make_request(summary_payload())
45
+ summary = asyncio.run(
46
+ fetch_device_state_summary(
47
+ request, "dev1", "total", time=datetime(2026, 10, 12, 12, 0, tzinfo=UTC)
48
+ )
49
+ )
50
+
51
+ method, path, kwargs = calls[0]
52
+ assert method == "POST"
53
+ assert path == "/apis/deviceOverView/stateAttributeSummary/category/total"
54
+ assert kwargs["params"] == {
55
+ "deviceId": "dev1",
56
+ "summaryCategoryKey": "pvInverterElectricityQuantityClass",
57
+ }
58
+ assert kwargs["json"] == {"time": "2026-10-12T12:00:00+00:00"}
59
+ assert summary.get("pvGeneratedEnergy").unit == "kWh"
60
+ assert summary.to_totals() == {"pvGeneratedEnergy": 12.5, "buyElectricityQuantity": None}
61
+
62
+
63
+ @pytest.mark.parametrize(
64
+ ("aggregation", "expected"),
65
+ [("daily", "2026-10-12"), ("monthly", "2026-10"), ("yearly", "2026")],
66
+ )
67
+ def test_summary_time_format_per_aggregation(aggregation: str, expected: str) -> None:
68
+ request, calls = make_request(summary_payload())
69
+ asyncio.run(
70
+ fetch_owner_state_summary(request, aggregation, time=datetime(2026, 10, 12, tzinfo=UTC))
71
+ )
72
+ assert calls[0][1].endswith(f"/ownerOverView/station/stateAttributeSummary/category/{aggregation}")
73
+ assert calls[0][2]["json"] == {"time": expected}
74
+
75
+
76
+ def test_invalid_aggregation_rejected() -> None:
77
+ request, _ = make_request(summary_payload())
78
+ with pytest.raises(ValueError):
79
+ asyncio.run(fetch_device_state_summary(request, "dev1", "weekly"))
80
+
81
+
82
+ def test_generated_energy_daily_points() -> None:
83
+ request, calls = make_request(
84
+ [{"time": "2026-10-12 10:00:00", "timeDisplay": "10:00", "value": 0.5, "isRealValue": True}]
85
+ )
86
+ points = asyncio.run(fetch_device_generated_energy_daily(request, "dev1", time="2026-10-12"))
87
+ assert calls[0][2]["json"] == {"time": "2026-10-12"}
88
+ assert points[0].value == 0.5
89
+ assert points[0].time_display == "10:00"
90
+
91
+
92
+ def make_state(fields: dict) -> DeviceState:
93
+ return DeviceState(
94
+ time=None,
95
+ fields={
96
+ key: StateAttribute(key, unit, value, display, key, False)
97
+ for key, (value, display, unit) in fields.items()
98
+ },
99
+ raw={},
100
+ )
101
+
102
+
103
+ def test_extended_sensor_data_and_unit_aware_power() -> None:
104
+ data = make_state(
105
+ {
106
+ "workingMode": ("L", "Line Mode", ""),
107
+ "outputLoadPercent": (1, "1", "%"),
108
+ "inverterHeatSinkTemperature": (49, "49", "°C"),
109
+ "busVoltage": (419, "419", "V"),
110
+ "ratedApparentPower": (23, "23", "VA"),
111
+ "chargingStatus": ("1", "Charging On", ""),
112
+ "acOutputActivePower": (350, "350", "W"),
113
+ "generationPower": (0.5, "0.5", "kW"),
114
+ }
115
+ ).to_sensor_data()
116
+
117
+ assert data["inverter_state"] == "L"
118
+ assert data["inverter_mode"] == "Line Mode"
119
+ assert data["load_percent"] == 1
120
+ assert data["heat_sink_temperature"] == 49
121
+ assert data["bus_voltage"] == 419
122
+ assert data["load_apparent_power"] == 23
123
+ assert data["charging_status"] == "Charging On"
124
+ assert data["load_power"] == 350
125
+ assert data["pv_power"] == 500
126
+ assert data["mains_status"] is None
127
+
128
+
129
+ def test_device_info() -> None:
130
+ info = make_state(
131
+ {
132
+ "protocolId": ("PI30", "PI30", ""),
133
+ "machineType": ("x", "Off Grid", ""),
134
+ "mainCpuFirmwareVersion": ("v", "00019.06", ""),
135
+ }
136
+ ).to_device_info()
137
+ assert info["protocol"] == "PI30"
138
+ assert info["machine_type"] == "Off Grid"
139
+ assert info["firmware_version"] == "00019.06"
140
+ assert info["secondary_firmware_version"] is None
File without changes
File without changes