python-siseli 0.2.1__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.1
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=VK5CNqMLRkY1w9HrcUhvaO_6J-rjqP7VwvbppCFpucI,2393
26
- siseli/models/station.py,sha256=02OLINAVblnKkF73ZwKxYvPtUFROsu4-g544oDg8ApA,1783
27
- python_siseli-0.2.1.dist-info/METADATA,sha256=wzl4nryFI-fsKCerJ7V60RUJggiQTAqX1DAwAnAfba8,1439
28
- python_siseli-0.2.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
29
- python_siseli-0.2.1.dist-info/top_level.txt,sha256=Dofr9c7hGvRRV6ij6aoPuAZqxEjkgtsBeN4KtFHbGgo,7
30
- python_siseli-0.2.1.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
@@ -9,6 +9,19 @@ from typing import Any
9
9
  from .common import LookupValue
10
10
 
11
11
 
12
+ def _numeric(value: Any) -> float | None:
13
+ """Return finite numeric telemetry as a float, otherwise None."""
14
+ if value is None or isinstance(value, bool):
15
+ return None
16
+ try:
17
+ number = float(value)
18
+ except (TypeError, ValueError, OverflowError):
19
+ return None
20
+ if number != number or number in (float("inf"), float("-inf")):
21
+ return None
22
+ return number
23
+
24
+
12
25
  @dataclass
13
26
  class StateAttribute:
14
27
  """A single telemetry attribute."""
@@ -76,6 +89,92 @@ class DeviceState:
76
89
  """Return an attribute by its key, or *None* if not present."""
77
90
  return self.fields.get(key)
78
91
 
92
+ def to_sensor_data(self) -> dict[str, Any]:
93
+ """Return stable, typed semantic telemetry fields for integrations.
94
+
95
+ API-specific field names, unit conversions, and derived battery values
96
+ belong here rather than in consumer integrations. Invalid numeric
97
+ telemetry is represented as None. Power values reported in kW by this
98
+ device are converted to W.
99
+ """
100
+ def value(api_key: str) -> Any:
101
+ attribute = self.fields.get(api_key)
102
+ return attribute.value if attribute is not None else None
103
+
104
+ def number(api_key: str) -> float | None:
105
+ return _numeric(value(api_key))
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
+
120
+ voltage = number("batteryVoltage")
121
+ charging = number("batteryChargingCurrent")
122
+ discharging = number("batteryDischargeCurrent")
123
+ current = (
124
+ charging - discharging
125
+ if charging is not None and discharging is not None
126
+ else None
127
+ )
128
+ pv_power = power_watts("generationPower")
129
+ load_power = power_watts("acOutputActivePower")
130
+ battery_power = (
131
+ voltage * current
132
+ if voltage is not None and current is not None
133
+ else None
134
+ )
135
+ return {
136
+ "battery_soc": number("batteryCapacity"),
137
+ "battery_voltage": voltage,
138
+ "battery_current": current,
139
+ "battery_power": battery_power,
140
+ "pv_voltage": number("pvInputVoltage1"),
141
+ "pv_current": number("pv1InputCurrentForBattery"),
142
+ "pv_power": pv_power,
143
+ "grid_voltage": number("gridVoltage"),
144
+ "grid_frequency": number("gridFrequency"),
145
+ "output_voltage": number("acOutputVoltage"),
146
+ "output_frequency": number("acOutputFrequency"),
147
+ "load_power": load_power,
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"),
176
+ }
177
+
79
178
 
80
179
  @dataclass
81
180
  class FlowNode:
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
+ )