python-siseli 0.2.2__py3-none-any.whl → 0.2.3__py3-none-any.whl

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.
@@ -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
@@ -1,8 +1,8 @@
1
1
  siseli/__init__.py,sha256=F4eW-gk3BGfcBhVgDCyqotYgCcibac6iSEgyp_px8Ug,1099
2
- siseli/_utils.py,sha256=QT-ooemKKAIEHICNI2QErPvRkFIkUGo6ncUFCJM1kGc,727
2
+ siseli/_utils.py,sha256=p-H5_aoERNHljuik8CQMIP1noUS_ovBqrClApiViuf8,888
3
3
  siseli/alarms.py,sha256=Mc_CV8kUBFTXu8c48NstX8Lc6Q0bPTnhjwehx9sbCkQ,4853
4
4
  siseli/auth.py,sha256=I8WwJgy1go1MGxjowkVx-lvCtneh5rRtbs9DV9yO4T8,6470
5
- siseli/client.py,sha256=Eap7MTrnctdskt6kOzbns7SqUt27ZDjMlIKVshfcfN8,14200
5
+ siseli/client.py,sha256=PJ0N_yOlILkG4u0fK3byWmKGwGxQyMTTtjxDG71v9aM,16048
6
6
  siseli/config.py,sha256=J8raq7Yf4gCyjO9ISNoTrk_EYNEGrESV56O-aHfDvBU,3278
7
7
  siseli/const.py,sha256=9qk2YEaDELKmn7xRsvxlnHh9nUGFymN1DWnulfQG4w4,364
8
8
  siseli/dashboard.py,sha256=JQHfi8orKs5uWsGGfoTvA14A9M_R9yIAYuGCxb4zTsM,3325
@@ -11,6 +11,7 @@ siseli/dictionary.py,sha256=VSO83uXPaGLPzKGRmpROuWQKivXN7DNOmXN8QQJ-Y-w,1120
11
11
  siseli/exceptions.py,sha256=y9ws9c2vr5Q3bZxLwkXybUqQooq57YEEXAN0wO3_fxk,1420
12
12
  siseli/history.py,sha256=CgBvDfZBIrrewu7PeRv08-Zr4boEVOY8Xevruu-ge-I,3869
13
13
  siseli/open_auth.py,sha256=w3Jq7ZA2m3d-A_ZR_O8G1bODHvcUJ4Rc1eOS4uq69l0,5570
14
+ siseli/overview.py,sha256=I9xpky2xQA-JZYp_5gpyi4C7yxylH_ViWbgCW21PNlA,3216
14
15
  siseli/state.py,sha256=d7Exlf7FzF8O_CcF-NbAt6kq8qaR4fFhjGW8028kbrM,5800
15
16
  siseli/station.py,sha256=e1OK4OIry9WUjT8KggQI5b4Acypm9D31mWAMTjDGFew,5531
16
17
  siseli/models/__init__.py,sha256=WSIXRM_JRKNhB_hDwxrpeQgdqKUHdbT3KiFvdrLrrzY,1242
@@ -22,9 +23,9 @@ siseli/models/dashboard.py,sha256=P86feNI8Yn6ADkwDGFQJFUESrKLt6VttGqsEiNzGnZA,11
22
23
  siseli/models/device.py,sha256=u57-csypaF-c5hAimqb8GIMeZqYZMKMhYFBTVuBRSfQ,657
23
24
  siseli/models/dictionary.py,sha256=d6KCu77UMlPcIDON8G3sjuytkSfbI5go1y3I_jAGTX8,422
24
25
  siseli/models/history.py,sha256=dx26VWLJosucMvwL36vojvAguvkMiv5GEKTllUtZV0Y,791
25
- siseli/models/state.py,sha256=WXONHjGx9Ro87mJqn1Y0T-nt3PJKOTbWXAyzqZ2GX48,4749
26
- siseli/models/station.py,sha256=02OLINAVblnKkF73ZwKxYvPtUFROsu4-g544oDg8ApA,1783
27
- python_siseli-0.2.2.dist-info/METADATA,sha256=m7CXqxigJiQL4vA3P9cqZ-RnYJKPwnl9onCyRBbs0Kc,1439
28
- python_siseli-0.2.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
29
- python_siseli-0.2.2.dist-info/top_level.txt,sha256=Dofr9c7hGvRRV6ij6aoPuAZqxEjkgtsBeN4KtFHbGgo,7
30
- python_siseli-0.2.2.dist-info/RECORD,,
26
+ siseli/models/state.py,sha256=kDUYQtegbQhUK_pikEC6-T6MHj5Rrw5g3vDFFB-xR2Y,6744
27
+ siseli/models/station.py,sha256=CxYqic6EHhE54eUvJMIltFvJgw_9gt5QX5rF_CjSL3U,2755
28
+ python_siseli-0.2.3.dist-info/METADATA,sha256=D8Yw1cp_tm_H72zzpvxCe7j2Ufx8nCrg6kSZyBp31hw,1439
29
+ python_siseli-0.2.3.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
30
+ python_siseli-0.2.3.dist-info/top_level.txt,sha256=Dofr9c7hGvRRV6ij6aoPuAZqxEjkgtsBeN4KtFHbGgo,7
31
+ python_siseli-0.2.3.dist-info/RECORD,,
siseli/_utils.py CHANGED
@@ -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:
siseli/client.py CHANGED
@@ -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
  *,
siseli/models/state.py CHANGED
@@ -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
 
siseli/models/station.py CHANGED
@@ -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}
siseli/overview.py ADDED
@@ -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
+ )