python-siseli 0.2.5__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.
Files changed (53) hide show
  1. python_siseli-0.3.0/LICENSE +21 -0
  2. python_siseli-0.3.0/PKG-INFO +134 -0
  3. python_siseli-0.3.0/README.md +103 -0
  4. python_siseli-0.3.0/pyproject.toml +70 -0
  5. python_siseli-0.3.0/python_siseli.egg-info/PKG-INFO +134 -0
  6. {python_siseli-0.2.5 → python_siseli-0.3.0}/python_siseli.egg-info/SOURCES.txt +5 -1
  7. {python_siseli-0.2.5 → python_siseli-0.3.0}/python_siseli.egg-info/requires.txt +5 -0
  8. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/__init__.py +4 -0
  9. python_siseli-0.3.0/siseli/_utils.py +60 -0
  10. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/alarms.py +7 -4
  11. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/auth.py +64 -23
  12. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/client.py +166 -31
  13. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/config.py +46 -8
  14. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/config_safety.py +35 -7
  15. python_siseli-0.3.0/siseli/const.py +13 -0
  16. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/dashboard.py +8 -6
  17. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/device.py +8 -12
  18. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/dictionary.py +5 -2
  19. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/exceptions.py +22 -0
  20. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/history.py +29 -36
  21. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/models/auth.py +2 -2
  22. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/models/dashboard.py +1 -2
  23. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/models/state.py +12 -2
  24. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/models/station.py +4 -3
  25. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/open_auth.py +12 -7
  26. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/overview.py +33 -9
  27. python_siseli-0.3.0/siseli/py.typed +0 -0
  28. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/state.py +28 -12
  29. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/station.py +19 -7
  30. {python_siseli-0.2.5 → python_siseli-0.3.0}/tests/test_auth.py +7 -8
  31. python_siseli-0.3.0/tests/test_client.py +354 -0
  32. {python_siseli-0.2.5 → python_siseli-0.3.0}/tests/test_config_safety.py +122 -3
  33. {python_siseli-0.2.5 → python_siseli-0.3.0}/tests/test_phase3.py +40 -1
  34. python_siseli-0.3.0/tests/test_robustness.py +377 -0
  35. python_siseli-0.2.5/PKG-INFO +0 -58
  36. python_siseli-0.2.5/README.md +0 -44
  37. python_siseli-0.2.5/pyproject.toml +0 -26
  38. python_siseli-0.2.5/python_siseli.egg-info/PKG-INFO +0 -58
  39. python_siseli-0.2.5/siseli/_utils.py +0 -34
  40. python_siseli-0.2.5/siseli/const.py +0 -9
  41. {python_siseli-0.2.5 → python_siseli-0.3.0}/python_siseli.egg-info/dependency_links.txt +0 -0
  42. {python_siseli-0.2.5 → python_siseli-0.3.0}/python_siseli.egg-info/top_level.txt +0 -0
  43. {python_siseli-0.2.5 → python_siseli-0.3.0}/setup.cfg +0 -0
  44. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/models/__init__.py +0 -0
  45. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/models/alarm.py +0 -0
  46. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/models/common.py +0 -0
  47. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/models/config.py +0 -0
  48. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/models/device.py +0 -0
  49. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/models/dictionary.py +0 -0
  50. {python_siseli-0.2.5 → python_siseli-0.3.0}/siseli/models/history.py +0 -0
  51. {python_siseli-0.2.5 → python_siseli-0.3.0}/tests/test_normalized_telemetry.py +0 -0
  52. {python_siseli-0.2.5 → python_siseli-0.3.0}/tests/test_open_auth.py +0 -0
  53. {python_siseli-0.2.5 → 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
@@ -1,7 +1,12 @@
1
1
  httpx>=0.27
2
2
  cryptography>=42
3
3
 
4
+ [:platform_system == "Windows"]
5
+ tzdata
6
+
4
7
  [dev]
5
8
  pytest>=8
6
9
  pytest-asyncio>=0.23
7
10
  respx>=0.21
11
+ ruff>=0.5
12
+ mypy>=1.10
@@ -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 typing import Any, Awaitable, Callable
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
- items = [_parse_alarm(item) for item in data.get("list", [])]
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
- items = [_parse_alarm_report(item) for item in data.get("list", [])]
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),