python-siseli 0.2.6__tar.gz → 0.3.0__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.
- python_siseli-0.3.0/LICENSE +21 -0
- python_siseli-0.3.0/PKG-INFO +134 -0
- python_siseli-0.3.0/README.md +103 -0
- python_siseli-0.3.0/pyproject.toml +70 -0
- python_siseli-0.3.0/python_siseli.egg-info/PKG-INFO +134 -0
- {python_siseli-0.2.6 → python_siseli-0.3.0}/python_siseli.egg-info/SOURCES.txt +5 -1
- {python_siseli-0.2.6 → python_siseli-0.3.0}/python_siseli.egg-info/requires.txt +5 -0
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/__init__.py +4 -0
- python_siseli-0.3.0/siseli/_utils.py +60 -0
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/alarms.py +7 -4
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/auth.py +64 -23
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/client.py +166 -31
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/config.py +43 -6
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/config_safety.py +35 -7
- python_siseli-0.3.0/siseli/const.py +13 -0
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/dashboard.py +8 -6
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/device.py +8 -12
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/dictionary.py +5 -2
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/exceptions.py +22 -0
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/history.py +29 -36
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/models/auth.py +2 -2
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/models/dashboard.py +1 -2
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/models/state.py +12 -2
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/models/station.py +4 -3
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/open_auth.py +12 -7
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/overview.py +33 -9
- python_siseli-0.3.0/siseli/py.typed +0 -0
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/state.py +28 -12
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/station.py +19 -7
- {python_siseli-0.2.6 → python_siseli-0.3.0}/tests/test_auth.py +7 -8
- python_siseli-0.3.0/tests/test_client.py +354 -0
- {python_siseli-0.2.6 → python_siseli-0.3.0}/tests/test_config_safety.py +122 -3
- {python_siseli-0.2.6 → python_siseli-0.3.0}/tests/test_phase3.py +5 -1
- python_siseli-0.3.0/tests/test_robustness.py +377 -0
- python_siseli-0.2.6/PKG-INFO +0 -58
- python_siseli-0.2.6/README.md +0 -44
- python_siseli-0.2.6/pyproject.toml +0 -26
- python_siseli-0.2.6/python_siseli.egg-info/PKG-INFO +0 -58
- python_siseli-0.2.6/siseli/_utils.py +0 -34
- python_siseli-0.2.6/siseli/const.py +0 -9
- {python_siseli-0.2.6 → python_siseli-0.3.0}/python_siseli.egg-info/dependency_links.txt +0 -0
- {python_siseli-0.2.6 → python_siseli-0.3.0}/python_siseli.egg-info/top_level.txt +0 -0
- {python_siseli-0.2.6 → python_siseli-0.3.0}/setup.cfg +0 -0
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/models/__init__.py +0 -0
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/models/alarm.py +0 -0
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/models/common.py +0 -0
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/models/config.py +0 -0
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/models/device.py +0 -0
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/models/dictionary.py +0 -0
- {python_siseli-0.2.6 → python_siseli-0.3.0}/siseli/models/history.py +0 -0
- {python_siseli-0.2.6 → python_siseli-0.3.0}/tests/test_normalized_telemetry.py +0 -0
- {python_siseli-0.2.6 → python_siseli-0.3.0}/tests/test_open_auth.py +0 -0
- {python_siseli-0.2.6 → python_siseli-0.3.0}/tests/test_overview.py +0 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 vvkor
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: python-siseli
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Python SDK for Siseli Cloud
|
|
5
|
+
Author: vvkor
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/vvkor/python-siseli
|
|
8
|
+
Project-URL: Issues, https://github.com/vvkor/python-siseli/issues
|
|
9
|
+
Keywords: siseli,solar,inverter,home-assistant
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Framework :: AsyncIO
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Typing :: Typed
|
|
18
|
+
Requires-Python: >=3.11
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
License-File: LICENSE
|
|
21
|
+
Requires-Dist: httpx>=0.27
|
|
22
|
+
Requires-Dist: cryptography>=42
|
|
23
|
+
Requires-Dist: tzdata; platform_system == "Windows"
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
26
|
+
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
|
|
27
|
+
Requires-Dist: respx>=0.21; extra == "dev"
|
|
28
|
+
Requires-Dist: ruff>=0.5; extra == "dev"
|
|
29
|
+
Requires-Dist: mypy>=1.10; extra == "dev"
|
|
30
|
+
Dynamic: license-file
|
|
31
|
+
|
|
32
|
+
# python-siseli
|
|
33
|
+
|
|
34
|
+
Python SDK for [Siseli Cloud](https://solar.siseli.com).
|
|
35
|
+
|
|
36
|
+
## Installation
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
pip install python-siseli
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Quick start
|
|
43
|
+
|
|
44
|
+
```python
|
|
45
|
+
import asyncio
|
|
46
|
+
from siseli import SiseliClient
|
|
47
|
+
|
|
48
|
+
async def main():
|
|
49
|
+
async with SiseliClient("user@example.com", "secret", timezone="Europe/Warsaw") as client:
|
|
50
|
+
# Discover devices
|
|
51
|
+
devices = await client.get_devices()
|
|
52
|
+
device = devices[0]
|
|
53
|
+
print(f"Device: {device.name} ({device.id})")
|
|
54
|
+
|
|
55
|
+
# Latest telemetry
|
|
56
|
+
state = await client.get_device_state(device.id)
|
|
57
|
+
grid = state.get("gridVoltage")
|
|
58
|
+
if grid:
|
|
59
|
+
print(f"Grid voltage: {grid.value_display} {grid.unit}")
|
|
60
|
+
|
|
61
|
+
# Energy flow diagram
|
|
62
|
+
flow = await client.get_energy_flow(device.id)
|
|
63
|
+
if flow.battery:
|
|
64
|
+
print(f"Battery: {flow.battery.value.value_display} {flow.battery.value.unit}")
|
|
65
|
+
|
|
66
|
+
asyncio.run(main())
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Client options
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
SiseliClient(
|
|
73
|
+
account, password,
|
|
74
|
+
timezone="Europe/Warsaw", # also used for "today"/"this month" in summaries
|
|
75
|
+
timeout=30.0,
|
|
76
|
+
max_retries=2, # transient failures only, never for config writes
|
|
77
|
+
retry_backoff=0.5, # seconds, doubled on each retry
|
|
78
|
+
http_client=None, # reuse your own httpx.AsyncClient (not closed by the SDK)
|
|
79
|
+
open_auth=False, # sign requests with the Siseli Open API headers
|
|
80
|
+
)
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
* An expired token is refreshed transparently; an HTTP 401/403 triggers one
|
|
84
|
+
re-login and retry.
|
|
85
|
+
* Connection errors, timeouts and HTTP 429/502/503/504 are retried with
|
|
86
|
+
exponential backoff.
|
|
87
|
+
* `open_auth=True` adds the `IOT-Open-*` signature headers. The application
|
|
88
|
+
secret used for this is taken from the official web client; it is only
|
|
89
|
+
obfuscated, not confidential, and may be rotated by the vendor. Pass
|
|
90
|
+
`open_auth=(app_id, encrypted_secret)` to override it.
|
|
91
|
+
|
|
92
|
+
## Errors
|
|
93
|
+
|
|
94
|
+
All errors derive from `SiseliError`:
|
|
95
|
+
|
|
96
|
+
| Exception | Meaning | Typical handling (e.g. Home Assistant) |
|
|
97
|
+
|---|---|---|
|
|
98
|
+
| `AuthenticationError` | Login rejected, or HTTP 401/403 after a re-login | start re-auth flow |
|
|
99
|
+
| `RateLimitError` (a `NetworkError`) | HTTP 429, see `.retry_after` | back off |
|
|
100
|
+
| `NetworkError` | Timeouts, connection errors, other HTTP errors (`.http_status`) | mark unavailable, retry later |
|
|
101
|
+
| `ApiError` | API returned a non-zero `code` | report `.code` / `.message` |
|
|
102
|
+
| `InvalidResponseError` | Body is not JSON or has an unexpected shape | log, retry later |
|
|
103
|
+
|
|
104
|
+
## Writing configuration
|
|
105
|
+
|
|
106
|
+
Use `safe_set_device_config()`; the low-level `set_device_config()` performs no
|
|
107
|
+
validation. Writes are allow-listed, range-checked, serialized per device,
|
|
108
|
+
never retried and verified by reading the value back (the result is
|
|
109
|
+
`UNKNOWN`, not success, when that is inconclusive). Battery-voltage keys need an
|
|
110
|
+
explicit `battery_nominal_voltage`, which is cross-checked against the live
|
|
111
|
+
`batteryVoltage` reading. See [`docs/api.md`](docs/api.md) for details.
|
|
112
|
+
|
|
113
|
+
```python
|
|
114
|
+
from siseli import ConfigAccess
|
|
115
|
+
|
|
116
|
+
result = await client.safe_set_device_config(
|
|
117
|
+
device.id, key="buzzerEnabled", value=False, dry_run=True
|
|
118
|
+
)
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Development
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
pip install -e ".[dev]"
|
|
125
|
+
ruff check siseli tests && mypy siseli && pytest
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## Development plan
|
|
129
|
+
|
|
130
|
+
See [`roadmap.md`](roadmap.md) for the full development plan.
|
|
131
|
+
|
|
132
|
+
## API documentation
|
|
133
|
+
|
|
134
|
+
See [`docs/api.md`](docs/api.md).
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
# python-siseli
|
|
2
|
+
|
|
3
|
+
Python SDK for [Siseli Cloud](https://solar.siseli.com).
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
pip install python-siseli
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Quick start
|
|
12
|
+
|
|
13
|
+
```python
|
|
14
|
+
import asyncio
|
|
15
|
+
from siseli import SiseliClient
|
|
16
|
+
|
|
17
|
+
async def main():
|
|
18
|
+
async with SiseliClient("user@example.com", "secret", timezone="Europe/Warsaw") as client:
|
|
19
|
+
# Discover devices
|
|
20
|
+
devices = await client.get_devices()
|
|
21
|
+
device = devices[0]
|
|
22
|
+
print(f"Device: {device.name} ({device.id})")
|
|
23
|
+
|
|
24
|
+
# Latest telemetry
|
|
25
|
+
state = await client.get_device_state(device.id)
|
|
26
|
+
grid = state.get("gridVoltage")
|
|
27
|
+
if grid:
|
|
28
|
+
print(f"Grid voltage: {grid.value_display} {grid.unit}")
|
|
29
|
+
|
|
30
|
+
# Energy flow diagram
|
|
31
|
+
flow = await client.get_energy_flow(device.id)
|
|
32
|
+
if flow.battery:
|
|
33
|
+
print(f"Battery: {flow.battery.value.value_display} {flow.battery.value.unit}")
|
|
34
|
+
|
|
35
|
+
asyncio.run(main())
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Client options
|
|
39
|
+
|
|
40
|
+
```python
|
|
41
|
+
SiseliClient(
|
|
42
|
+
account, password,
|
|
43
|
+
timezone="Europe/Warsaw", # also used for "today"/"this month" in summaries
|
|
44
|
+
timeout=30.0,
|
|
45
|
+
max_retries=2, # transient failures only, never for config writes
|
|
46
|
+
retry_backoff=0.5, # seconds, doubled on each retry
|
|
47
|
+
http_client=None, # reuse your own httpx.AsyncClient (not closed by the SDK)
|
|
48
|
+
open_auth=False, # sign requests with the Siseli Open API headers
|
|
49
|
+
)
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
* An expired token is refreshed transparently; an HTTP 401/403 triggers one
|
|
53
|
+
re-login and retry.
|
|
54
|
+
* Connection errors, timeouts and HTTP 429/502/503/504 are retried with
|
|
55
|
+
exponential backoff.
|
|
56
|
+
* `open_auth=True` adds the `IOT-Open-*` signature headers. The application
|
|
57
|
+
secret used for this is taken from the official web client; it is only
|
|
58
|
+
obfuscated, not confidential, and may be rotated by the vendor. Pass
|
|
59
|
+
`open_auth=(app_id, encrypted_secret)` to override it.
|
|
60
|
+
|
|
61
|
+
## Errors
|
|
62
|
+
|
|
63
|
+
All errors derive from `SiseliError`:
|
|
64
|
+
|
|
65
|
+
| Exception | Meaning | Typical handling (e.g. Home Assistant) |
|
|
66
|
+
|---|---|---|
|
|
67
|
+
| `AuthenticationError` | Login rejected, or HTTP 401/403 after a re-login | start re-auth flow |
|
|
68
|
+
| `RateLimitError` (a `NetworkError`) | HTTP 429, see `.retry_after` | back off |
|
|
69
|
+
| `NetworkError` | Timeouts, connection errors, other HTTP errors (`.http_status`) | mark unavailable, retry later |
|
|
70
|
+
| `ApiError` | API returned a non-zero `code` | report `.code` / `.message` |
|
|
71
|
+
| `InvalidResponseError` | Body is not JSON or has an unexpected shape | log, retry later |
|
|
72
|
+
|
|
73
|
+
## Writing configuration
|
|
74
|
+
|
|
75
|
+
Use `safe_set_device_config()`; the low-level `set_device_config()` performs no
|
|
76
|
+
validation. Writes are allow-listed, range-checked, serialized per device,
|
|
77
|
+
never retried and verified by reading the value back (the result is
|
|
78
|
+
`UNKNOWN`, not success, when that is inconclusive). Battery-voltage keys need an
|
|
79
|
+
explicit `battery_nominal_voltage`, which is cross-checked against the live
|
|
80
|
+
`batteryVoltage` reading. See [`docs/api.md`](docs/api.md) for details.
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
from siseli import ConfigAccess
|
|
84
|
+
|
|
85
|
+
result = await client.safe_set_device_config(
|
|
86
|
+
device.id, key="buzzerEnabled", value=False, dry_run=True
|
|
87
|
+
)
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## Development
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
pip install -e ".[dev]"
|
|
94
|
+
ruff check siseli tests && mypy siseli && pytest
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## Development plan
|
|
98
|
+
|
|
99
|
+
See [`roadmap.md`](roadmap.md) for the full development plan.
|
|
100
|
+
|
|
101
|
+
## API documentation
|
|
102
|
+
|
|
103
|
+
See [`docs/api.md`](docs/api.md).
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "python-siseli"
|
|
7
|
+
version = "0.3.0"
|
|
8
|
+
description = "Python SDK for Siseli Cloud"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.11"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
authors = [{ name = "vvkor" }]
|
|
14
|
+
keywords = ["siseli", "solar", "inverter", "home-assistant"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 4 - Beta",
|
|
17
|
+
"Framework :: AsyncIO",
|
|
18
|
+
"Intended Audience :: Developers",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3.11",
|
|
21
|
+
"Programming Language :: Python :: 3.12",
|
|
22
|
+
"Programming Language :: Python :: 3.13",
|
|
23
|
+
"Typing :: Typed",
|
|
24
|
+
]
|
|
25
|
+
dependencies = [
|
|
26
|
+
"httpx>=0.27",
|
|
27
|
+
"cryptography>=42",
|
|
28
|
+
"tzdata; platform_system == 'Windows'",
|
|
29
|
+
]
|
|
30
|
+
|
|
31
|
+
[project.urls]
|
|
32
|
+
Homepage = "https://github.com/vvkor/python-siseli"
|
|
33
|
+
Issues = "https://github.com/vvkor/python-siseli/issues"
|
|
34
|
+
|
|
35
|
+
[project.optional-dependencies]
|
|
36
|
+
dev = [
|
|
37
|
+
"pytest>=8",
|
|
38
|
+
"pytest-asyncio>=0.23",
|
|
39
|
+
"respx>=0.21",
|
|
40
|
+
"ruff>=0.5",
|
|
41
|
+
"mypy>=1.10",
|
|
42
|
+
]
|
|
43
|
+
|
|
44
|
+
[tool.setuptools.packages.find]
|
|
45
|
+
where = ["."]
|
|
46
|
+
include = ["siseli*"]
|
|
47
|
+
|
|
48
|
+
[tool.setuptools.package-data]
|
|
49
|
+
siseli = ["py.typed"]
|
|
50
|
+
|
|
51
|
+
[tool.ruff]
|
|
52
|
+
target-version = "py311"
|
|
53
|
+
line-length = 100
|
|
54
|
+
|
|
55
|
+
[tool.ruff.lint]
|
|
56
|
+
select = ["E", "F", "I", "B", "UP", "S"]
|
|
57
|
+
ignore = ["E501", "UP042"]
|
|
58
|
+
|
|
59
|
+
[tool.ruff.lint.per-file-ignores]
|
|
60
|
+
"tests/*" = ["S101", "S105", "S106", "S107", "B011"]
|
|
61
|
+
|
|
62
|
+
[tool.mypy]
|
|
63
|
+
python_version = "3.11"
|
|
64
|
+
ignore_missing_imports = true
|
|
65
|
+
warn_unused_ignores = true
|
|
66
|
+
|
|
67
|
+
[tool.pytest.ini_options]
|
|
68
|
+
asyncio_mode = "auto"
|
|
69
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
70
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: python-siseli
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Python SDK for Siseli Cloud
|
|
5
|
+
Author: vvkor
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/vvkor/python-siseli
|
|
8
|
+
Project-URL: Issues, https://github.com/vvkor/python-siseli/issues
|
|
9
|
+
Keywords: siseli,solar,inverter,home-assistant
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Framework :: AsyncIO
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Typing :: Typed
|
|
18
|
+
Requires-Python: >=3.11
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
License-File: LICENSE
|
|
21
|
+
Requires-Dist: httpx>=0.27
|
|
22
|
+
Requires-Dist: cryptography>=42
|
|
23
|
+
Requires-Dist: tzdata; platform_system == "Windows"
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
26
|
+
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
|
|
27
|
+
Requires-Dist: respx>=0.21; extra == "dev"
|
|
28
|
+
Requires-Dist: ruff>=0.5; extra == "dev"
|
|
29
|
+
Requires-Dist: mypy>=1.10; extra == "dev"
|
|
30
|
+
Dynamic: license-file
|
|
31
|
+
|
|
32
|
+
# python-siseli
|
|
33
|
+
|
|
34
|
+
Python SDK for [Siseli Cloud](https://solar.siseli.com).
|
|
35
|
+
|
|
36
|
+
## Installation
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
pip install python-siseli
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Quick start
|
|
43
|
+
|
|
44
|
+
```python
|
|
45
|
+
import asyncio
|
|
46
|
+
from siseli import SiseliClient
|
|
47
|
+
|
|
48
|
+
async def main():
|
|
49
|
+
async with SiseliClient("user@example.com", "secret", timezone="Europe/Warsaw") as client:
|
|
50
|
+
# Discover devices
|
|
51
|
+
devices = await client.get_devices()
|
|
52
|
+
device = devices[0]
|
|
53
|
+
print(f"Device: {device.name} ({device.id})")
|
|
54
|
+
|
|
55
|
+
# Latest telemetry
|
|
56
|
+
state = await client.get_device_state(device.id)
|
|
57
|
+
grid = state.get("gridVoltage")
|
|
58
|
+
if grid:
|
|
59
|
+
print(f"Grid voltage: {grid.value_display} {grid.unit}")
|
|
60
|
+
|
|
61
|
+
# Energy flow diagram
|
|
62
|
+
flow = await client.get_energy_flow(device.id)
|
|
63
|
+
if flow.battery:
|
|
64
|
+
print(f"Battery: {flow.battery.value.value_display} {flow.battery.value.unit}")
|
|
65
|
+
|
|
66
|
+
asyncio.run(main())
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Client options
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
SiseliClient(
|
|
73
|
+
account, password,
|
|
74
|
+
timezone="Europe/Warsaw", # also used for "today"/"this month" in summaries
|
|
75
|
+
timeout=30.0,
|
|
76
|
+
max_retries=2, # transient failures only, never for config writes
|
|
77
|
+
retry_backoff=0.5, # seconds, doubled on each retry
|
|
78
|
+
http_client=None, # reuse your own httpx.AsyncClient (not closed by the SDK)
|
|
79
|
+
open_auth=False, # sign requests with the Siseli Open API headers
|
|
80
|
+
)
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
* An expired token is refreshed transparently; an HTTP 401/403 triggers one
|
|
84
|
+
re-login and retry.
|
|
85
|
+
* Connection errors, timeouts and HTTP 429/502/503/504 are retried with
|
|
86
|
+
exponential backoff.
|
|
87
|
+
* `open_auth=True` adds the `IOT-Open-*` signature headers. The application
|
|
88
|
+
secret used for this is taken from the official web client; it is only
|
|
89
|
+
obfuscated, not confidential, and may be rotated by the vendor. Pass
|
|
90
|
+
`open_auth=(app_id, encrypted_secret)` to override it.
|
|
91
|
+
|
|
92
|
+
## Errors
|
|
93
|
+
|
|
94
|
+
All errors derive from `SiseliError`:
|
|
95
|
+
|
|
96
|
+
| Exception | Meaning | Typical handling (e.g. Home Assistant) |
|
|
97
|
+
|---|---|---|
|
|
98
|
+
| `AuthenticationError` | Login rejected, or HTTP 401/403 after a re-login | start re-auth flow |
|
|
99
|
+
| `RateLimitError` (a `NetworkError`) | HTTP 429, see `.retry_after` | back off |
|
|
100
|
+
| `NetworkError` | Timeouts, connection errors, other HTTP errors (`.http_status`) | mark unavailable, retry later |
|
|
101
|
+
| `ApiError` | API returned a non-zero `code` | report `.code` / `.message` |
|
|
102
|
+
| `InvalidResponseError` | Body is not JSON or has an unexpected shape | log, retry later |
|
|
103
|
+
|
|
104
|
+
## Writing configuration
|
|
105
|
+
|
|
106
|
+
Use `safe_set_device_config()`; the low-level `set_device_config()` performs no
|
|
107
|
+
validation. Writes are allow-listed, range-checked, serialized per device,
|
|
108
|
+
never retried and verified by reading the value back (the result is
|
|
109
|
+
`UNKNOWN`, not success, when that is inconclusive). Battery-voltage keys need an
|
|
110
|
+
explicit `battery_nominal_voltage`, which is cross-checked against the live
|
|
111
|
+
`batteryVoltage` reading. See [`docs/api.md`](docs/api.md) for details.
|
|
112
|
+
|
|
113
|
+
```python
|
|
114
|
+
from siseli import ConfigAccess
|
|
115
|
+
|
|
116
|
+
result = await client.safe_set_device_config(
|
|
117
|
+
device.id, key="buzzerEnabled", value=False, dry_run=True
|
|
118
|
+
)
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Development
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
pip install -e ".[dev]"
|
|
125
|
+
ruff check siseli tests && mypy siseli && pytest
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## Development plan
|
|
129
|
+
|
|
130
|
+
See [`roadmap.md`](roadmap.md) for the full development plan.
|
|
131
|
+
|
|
132
|
+
## API documentation
|
|
133
|
+
|
|
134
|
+
See [`docs/api.md`](docs/api.md).
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
LICENSE
|
|
1
2
|
README.md
|
|
2
3
|
pyproject.toml
|
|
3
4
|
python_siseli.egg-info/PKG-INFO
|
|
@@ -20,6 +21,7 @@ siseli/exceptions.py
|
|
|
20
21
|
siseli/history.py
|
|
21
22
|
siseli/open_auth.py
|
|
22
23
|
siseli/overview.py
|
|
24
|
+
siseli/py.typed
|
|
23
25
|
siseli/state.py
|
|
24
26
|
siseli/station.py
|
|
25
27
|
siseli/models/__init__.py
|
|
@@ -34,8 +36,10 @@ siseli/models/history.py
|
|
|
34
36
|
siseli/models/state.py
|
|
35
37
|
siseli/models/station.py
|
|
36
38
|
tests/test_auth.py
|
|
39
|
+
tests/test_client.py
|
|
37
40
|
tests/test_config_safety.py
|
|
38
41
|
tests/test_normalized_telemetry.py
|
|
39
42
|
tests/test_open_auth.py
|
|
40
43
|
tests/test_overview.py
|
|
41
|
-
tests/test_phase3.py
|
|
44
|
+
tests/test_phase3.py
|
|
45
|
+
tests/test_robustness.py
|
|
@@ -16,7 +16,9 @@ from .config_safety import (
|
|
|
16
16
|
from .exceptions import (
|
|
17
17
|
ApiError,
|
|
18
18
|
AuthenticationError,
|
|
19
|
+
InvalidResponseError,
|
|
19
20
|
NetworkError,
|
|
21
|
+
RateLimitError,
|
|
20
22
|
SiseliError,
|
|
21
23
|
TokenExpiredError,
|
|
22
24
|
)
|
|
@@ -60,6 +62,8 @@ __all__ = [
|
|
|
60
62
|
"TokenExpiredError",
|
|
61
63
|
"ApiError",
|
|
62
64
|
"NetworkError",
|
|
65
|
+
"RateLimitError",
|
|
66
|
+
"InvalidResponseError",
|
|
63
67
|
"Alarm",
|
|
64
68
|
"AlarmReport",
|
|
65
69
|
"AttributeGroup",
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
"""Shared parsing helpers for Siseli API payloads."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import re
|
|
6
|
+
from datetime import UTC, datetime
|
|
7
|
+
from typing import Any
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def parse_datetime(value: str | None) -> datetime | None:
|
|
11
|
+
if not value:
|
|
12
|
+
return None
|
|
13
|
+
text = value.replace("Z", "+00:00")
|
|
14
|
+
if len(text) == 4 and text.isdigit():
|
|
15
|
+
text = f"{text}-01-01"
|
|
16
|
+
elif len(text) == 7 and text[4] == "-":
|
|
17
|
+
text = f"{text}-01"
|
|
18
|
+
return ensure_aware(datetime.fromisoformat(text))
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def ensure_aware(value: datetime) -> datetime:
|
|
22
|
+
"""Treat naive timestamps from the API as UTC so they compare safely."""
|
|
23
|
+
return value if value.tzinfo is not None else value.replace(tzinfo=UTC)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def serialize_datetime(value: datetime | str | None) -> str | None:
|
|
27
|
+
if value is None:
|
|
28
|
+
return None
|
|
29
|
+
if isinstance(value, str):
|
|
30
|
+
return value
|
|
31
|
+
return value.isoformat().replace("+00:00", "Z")
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def extract_value(raw: Any) -> Any:
|
|
35
|
+
if not isinstance(raw, dict):
|
|
36
|
+
return raw
|
|
37
|
+
for key in ("vd", "valueDisplay", "value"):
|
|
38
|
+
if key in raw:
|
|
39
|
+
return raw[key]
|
|
40
|
+
return raw
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def as_dict(value: Any) -> dict:
|
|
44
|
+
"""Return *value* if it is a dict, else an empty dict (handles JSON null)."""
|
|
45
|
+
return value if isinstance(value, dict) else {}
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def as_list(value: Any) -> list:
|
|
49
|
+
"""Return *value* if it is a list, else an empty list (handles JSON null)."""
|
|
50
|
+
return value if isinstance(value, list) else []
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
_SEGMENT_RE = re.compile(r"^[A-Za-z0-9_-]+$")
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def validate_path_segment(value: str, label: str) -> str:
|
|
57
|
+
"""Reject values that could alter the URL path when interpolated."""
|
|
58
|
+
if not isinstance(value, str) or not _SEGMENT_RE.match(value):
|
|
59
|
+
raise ValueError(f"invalid {label}: {value!r}")
|
|
60
|
+
return value
|
|
@@ -2,9 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
from __future__ import annotations
|
|
4
4
|
|
|
5
|
-
from
|
|
5
|
+
from collections.abc import Awaitable, Callable
|
|
6
|
+
from typing import Any
|
|
6
7
|
|
|
7
|
-
from ._utils import parse_datetime, serialize_datetime
|
|
8
|
+
from ._utils import as_dict, as_list, parse_datetime, serialize_datetime
|
|
8
9
|
from .const import DEFAULT_PAGE_SIZE
|
|
9
10
|
from .models.alarm import Alarm, AlarmReport
|
|
10
11
|
from .models.common import PagedResult
|
|
@@ -100,7 +101,8 @@ async def fetch_alarm_list(
|
|
|
100
101
|
"orderByCreatedTimeDesc": order_by_created_time_desc,
|
|
101
102
|
},
|
|
102
103
|
)
|
|
103
|
-
|
|
104
|
+
data = as_dict(data)
|
|
105
|
+
items = [_parse_alarm(item) for item in as_list(data.get("list"))]
|
|
104
106
|
return PagedResult(
|
|
105
107
|
page=data.get("page", page),
|
|
106
108
|
count=data.get("count", count),
|
|
@@ -149,7 +151,8 @@ async def fetch_alarm_reports(
|
|
|
149
151
|
"orderByCreatedAtAsc": order_by_created_at_asc,
|
|
150
152
|
},
|
|
151
153
|
)
|
|
152
|
-
|
|
154
|
+
data = as_dict(data)
|
|
155
|
+
items = [_parse_alarm_report(item) for item in as_list(data.get("list"))]
|
|
153
156
|
return PagedResult(
|
|
154
157
|
page=data.get("page", page),
|
|
155
158
|
count=data.get("count", count),
|