python-pooldose 0.5.1__tar.gz → 0.6.5__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 (36) hide show
  1. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/PKG-INFO +197 -38
  2. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/README.md +196 -37
  3. python_pooldose-0.6.5/pyproject.toml +88 -0
  4. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/__init__.py +1 -0
  5. python_pooldose-0.6.5/src/pooldose/__main__.py +297 -0
  6. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/client.py +36 -19
  7. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/constants.py +1 -1
  8. python_pooldose-0.6.5/src/pooldose/device_analyzer.py +411 -0
  9. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/mappings/mapping_info.py +6 -4
  10. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/mock_client.py +4 -4
  11. python_pooldose-0.6.5/src/pooldose/py.typed +0 -0
  12. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/request_handler.py +103 -21
  13. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/request_status.py +1 -0
  14. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/values/instant_values.py +2 -1
  15. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/python_pooldose.egg-info/PKG-INFO +197 -38
  16. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/python_pooldose.egg-info/SOURCES.txt +6 -0
  17. python_pooldose-0.6.5/src/python_pooldose.egg-info/entry_points.txt +2 -0
  18. python_pooldose-0.6.5/tests/test_device_analyzer.py +583 -0
  19. python_pooldose-0.6.5/tests/test_device_analyzer_integration.py +389 -0
  20. python_pooldose-0.5.1/pyproject.toml +0 -38
  21. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/LICENSE +0 -0
  22. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/setup.cfg +0 -0
  23. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/mappings/__init__.py +0 -0
  24. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/mappings/model_PDPR1H1HAR1V0_FW539224.json +0 -0
  25. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/mappings/model_PDPR1H1HAW100_FW539187.json +0 -0
  26. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/values/__init__.py +0 -0
  27. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/values/static_values.py +0 -0
  28. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/python_pooldose.egg-info/dependency_links.txt +0 -0
  29. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/python_pooldose.egg-info/requires.txt +0 -0
  30. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/python_pooldose.egg-info/top_level.txt +0 -0
  31. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/tests/test_client.py +0 -0
  32. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/tests/test_instant_values.py +0 -0
  33. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/tests/test_mapping_info.py +0 -0
  34. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/tests/test_request_handler.py +0 -0
  35. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/tests/test_ssl_support.py +0 -0
  36. {python_pooldose-0.5.1 → python_pooldose-0.6.5}/tests/test_static_values.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: python-pooldose
3
- Version: 0.5.1
3
+ Version: 0.6.5
4
4
  Summary: Unoffical async Python client for SEKO PoolDose devices
5
5
  Author-email: Lukas Maertin <pypi@lukas-maertin.de>
6
6
  License-Expression: MIT
@@ -28,6 +28,9 @@ This client uses an undocumented local HTTP API. It provides live readings for p
28
28
  - **Dynamic sensor discovery** based on device model and firmware
29
29
  - **Dictionary-style access** to instant values
30
30
  - **Structured data API** with type-based organization
31
+ - **Device analyzer** for discovering unsupported device capabilities
32
+ - **PEP-561 compliant** with full type hints for Home Assistant integrations
33
+ - **Command-line interface** for direct device interaction and testing
31
34
  - **Secure by default** - WiFi passwords excluded unless explicitly requested
32
35
  - **Comprehensive error handling** with detailed logging
33
36
  - **SSL/HTTPS support** for secure communication
@@ -169,6 +172,141 @@ client = PooldoseClient("192.168.1.100", use_ssl=True, port=8443, ssl_verify=Fal
169
172
  pip install python-pooldose
170
173
  ```
171
174
 
175
+ ## Command Line Usage
176
+
177
+ After installation, you can use python-pooldose directly from the command line:
178
+
179
+ ### Connect to Real Device
180
+
181
+ ```bash
182
+ # Basic connection
183
+ pooldose --host 192.168.1.100
184
+
185
+ # With HTTPS
186
+ pooldose --host 192.168.1.100 --ssl
187
+
188
+ # Custom port
189
+ pooldose --host 192.168.1.100 --ssl --port 8443
190
+
191
+ # Analyze device capabilities (discover unsupported devices)
192
+ pooldose --host 192.168.1.100 --analyze
193
+
194
+ # Show all widgets including hidden ones
195
+ pooldose --host 192.168.1.100 --analyze-all
196
+ ```
197
+
198
+ ### Mock Mode with JSON Files
199
+
200
+ ```bash
201
+ # Use JSON file for testing
202
+ pooldose --mock path/to/your/data.json
203
+ ```
204
+
205
+ ### Alternative Module Execution
206
+
207
+ You can also run it as a Python module:
208
+
209
+ ```bash
210
+ # Real device
211
+ python -m pooldose --host 192.168.1.100
212
+
213
+ # Device analysis
214
+ python -m pooldose --host 192.168.1.100 --analyze
215
+
216
+ # Mock mode
217
+ python -m pooldose --mock data.json
218
+
219
+ # Show help
220
+ python -m pooldose --help
221
+ ```
222
+
223
+ ## Device Analysis for Unsupported Devices
224
+
225
+ The device analyzer is a powerful feature that helps discover and analyze PoolDose devices that are not yet officially supported. This is particularly useful for:
226
+
227
+ - **New Device Discovery**: Identifying capabilities of unknown device models
228
+ - **Device Support Development**: Gathering data needed to add support for new devices
229
+ - **Troubleshooting**: Understanding how your device exposes data and controls
230
+ - **Widget Exploration**: Discovering all available sensors, controls, and settings
231
+
232
+ ### Basic Device Analysis
233
+
234
+ ```bash
235
+ # Analyze a device to discover its capabilities
236
+ pooldose --host 192.168.1.100 --analyze
237
+
238
+ # Show all widgets including hidden ones
239
+ pooldose --host 192.168.1.100 --analyze-all
240
+
241
+ # Analyze with HTTPS
242
+ pooldose --host 192.168.1.100 --ssl --analyze
243
+ ```
244
+
245
+ ### Analysis Output
246
+
247
+ The analyzer provides comprehensive information about your device:
248
+
249
+ ```
250
+ === DEVICE ANALYSIS ===
251
+ Device: 01234567890A_DEVICE
252
+ Model: PDPR1H1HAW***
253
+ Firmware: FW53****
254
+
255
+ === WIDGETS (Visible UI Elements) ===
256
+
257
+ SENSORS (Read-only values)
258
+ temperature: 24.5°C
259
+ ph: 7.2
260
+ orp: 720 mV
261
+
262
+ SETPOINTS (Configurable values)
263
+ target_ph: 7.0 (Range: 6.0-8.0, Step: 0.1)
264
+ target_orp: 700 mV (Range: 400-900, Step: 10)
265
+
266
+ SWITCHES (On/Off controls)
267
+ stop_dosing: OFF
268
+ pump_detection: ON
269
+
270
+ SELECTS (Configuration options)
271
+ water_meter_unit: L/h
272
+ Options: [L/h, m³/h, gal/h]
273
+
274
+ ALARMS (Status indicators)
275
+ alarm_ph: OK
276
+ alarm_orp: OK
277
+ ```
278
+
279
+ ### Using Analysis for Device Support
280
+
281
+ When you encounter an unsupported device, the analyzer helps gather the necessary information:
282
+
283
+ 1. **Run Analysis**: Use `--analyze` to discover all device capabilities
284
+ 2. **Document Output**: Save the analysis output to understand device structure
285
+ 3. **Check Widget Types**: Note which sensors, controls, and settings are available
286
+ 4. **Identify Patterns**: Look for device model and firmware information
287
+ 5. **Report Findings**: Use the analysis data to request support for your device model
288
+
289
+ ### Example: Discovering New Device
290
+
291
+ ```bash
292
+ # Unknown device analysis
293
+ pooldose --host 192.168.1.100 --analyze
294
+
295
+ # Output shows:
296
+ # Device: 01987654321B_DEVICE
297
+ # Model: PDPR2H2XYZ*** ← New model not yet supported
298
+ # Firmware: FW54**** ← New firmware version
299
+ #
300
+ # Widgets discovered: 15 sensors, 8 controls, 12 settings
301
+ ```
302
+
303
+ With this information, you can:
304
+ - Report the new model/firmware combination
305
+ - Share the widget structure for mapping development
306
+ - Help expand device support for the community
307
+
308
+ The device analyzer makes python-pooldose extensible and helps build support for the growing ecosystem of SEKO PoolDose devices.
309
+
172
310
  ## Examples
173
311
 
174
312
  The `examples/` directory contains demonstration scripts that show how to use the python-pooldose library:
@@ -189,25 +327,6 @@ python examples/demo.py
189
327
  - Displays all sensor readings, alarms, setpoints, and settings
190
328
  - Demonstrates error handling
191
329
 
192
- ### 2. Mock Client Demo (`examples/demo_mock.py`)
193
-
194
- Shows how to use the mock client with JSON files for development and testing:
195
-
196
- ```bash
197
- # Run with sample data
198
- python examples/demo_mock.py references/testdaten/suplere/instantvalues.json
199
-
200
- # Use custom JSON file
201
- python examples/demo_mock.py path/to/your/data.json
202
- ```
203
-
204
- **Features:**
205
-
206
- - No hardware required
207
- - Uses real device data from JSON files
208
- - Same API as real client
209
- - Perfect for development and CI/CD
210
-
211
330
  ### Benefits of the Examples
212
331
 
213
332
  - **Learning**: Step-by-step progression from simple to advanced usage
@@ -266,14 +385,14 @@ asyncio.run(simple_test())
266
385
 
267
386
  ### Mock Client Command Line Usage
268
387
 
269
- You can run the demo script with custom JSON files:
388
+ You can use the mock client with custom JSON files via the command line:
270
389
 
271
390
  ```bash
272
- # Run with sample data
273
- python examples/demo_mock.py references/testdaten/suplere/instantvalues.json
391
+ # Use mock client with JSON file
392
+ pooldose --mock path/to/your/data.json
274
393
 
275
- # Use custom JSON file
276
- python examples/demo_mock.py path/to/your/data.json
394
+ # Or as Python module
395
+ python -m pooldose --mock path/to/your/data.json
277
396
  ```
278
397
 
279
398
  ### JSON Data Format
@@ -344,8 +463,7 @@ success = client.reload_data()
344
463
 
345
464
  The following sample JSON files are available in the repository:
346
465
 
347
- - `references/testdaten/suplere/instantvalues.json` - PDPR1H1HAR1V0_FW539224 device
348
- - `references/testdaten/instantvalues_poolforum_1.json` - Additional sample data
466
+ - `references/testdaten/tscherno/instantvalues.json` - Sample device data for testing
349
467
 
350
468
  ### Mock Client Use Cases
351
469
 
@@ -617,13 +735,13 @@ Mapping Discovery Process:
617
735
 
618
736
 
619
737
  ┌─────────────────┐
620
- │ Get MODEL_ID │ ──────► PDPR1H1HAW100
621
- │ Get FW_CODE │ ──────► 539187
738
+ │ Get MODEL_ID │ ──────► PDPR1H1HAW***
739
+ │ Get FW_CODE │ ──────► 53****
622
740
  └─────────────────┘
623
741
 
624
742
 
625
743
  ┌─────────────────┐
626
- │ Load JSON File │ ──────► model_PDPR1H1HAW100_FW539187.json
744
+ │ Load JSON File │ ──────► model_PDPR1H1HAW***_FW53****.json
627
745
  └─────────────────┘
628
746
 
629
747
 
@@ -741,12 +859,54 @@ The `instant_values_structured()` method returns data organized by type:
741
859
 
742
860
  This client has been tested with:
743
861
 
744
- - **PoolDose Double/Dual WiFi** (Model: PDPR1H1HAW100, FW: 539187)
862
+ - **SEKO PoolDose Double/Dual WiFi** (Model: PDPR1H1HAW***, FW: 53****)
863
+ - **VA dos BASIC Chlor - pH/ORP Wi-Fi** (Model: PDPR1H1HAR***, FW: 53****)
745
864
 
746
- Other SEKO PoolDose models may work but are untested. The client uses JSON mapping files to adapt to different device models and firmware versions (see e.g. `src/pooldose/mappings/model_PDPR1H1HAW100_FW539187.json`).
865
+ Other SEKO PoolDose models may work but are untested. The client uses JSON mapping files to adapt to different device models and firmware versions (see e.g. `src/pooldose/mappings/model_PDPR1H1HAW***_FW53****.json`).
747
866
 
748
867
  > **Note:** The JSON files in the mappings directory define the device-specific data keys and their human-readable names for different PoolDose models and firmware versions.
749
868
 
869
+ ## Type Hints & Home Assistant Integration
870
+
871
+ This package is **PEP-561 compliant** and fully typed for use in Home Assistant integrations:
872
+
873
+ ### Type Safety Features
874
+
875
+ **PEP-561 Compliance**: Package includes `py.typed` file marking it as fully typed
876
+ **Comprehensive Type Annotations**: All public API methods have complete type hints
877
+ **mypy Support**: Built-in mypy configuration for static type checking
878
+ **Home Assistant Ready**: Compatible with Home Assistant's strict typing requirements
879
+
880
+ ### Type-Safe Usage
881
+
882
+ ```python
883
+ from pooldose import PooldoseClient
884
+ from pooldose.request_status import RequestStatus
885
+
886
+ # Type checkers will infer all types automatically
887
+ client: PooldoseClient = PooldoseClient("192.168.1.100")
888
+ status: RequestStatus = await client.connect()
889
+
890
+ # Dictionary-style access with proper typing
891
+ status, instant_values = await client.instant_values()
892
+ if status == RequestStatus.SUCCESS and instant_values:
893
+ temperature = instant_values["temperature"] # Typed as tuple[float, str]
894
+ ph_value = instant_values.get("ph", "N/A") # Safe access with default
895
+
896
+ # Structured data with full type safety
897
+ status, structured_data = await client.instant_values_structured()
898
+ sensors = structured_data.get("sensor", {}) # Type: dict[str, dict[str, Any]]
899
+ ```
900
+
901
+ ### Integration Benefits
902
+
903
+ - **IDE Support**: Full autocomplete and type checking in VS Code, PyCharm, etc.
904
+ - **Runtime Safety**: Catch type errors before deployment
905
+ - **Documentation**: Self-documenting code through type annotations
906
+ - **Maintenance**: Easier refactoring with type-guided development
907
+
908
+ For Home Assistant integrations, add this package to your integration's dependencies and enjoy full type safety throughout your integration code.
909
+
750
910
  ## Security
751
911
 
752
912
  By default, the client excludes sensitive information like WiFi passwords from device info. To include sensitive data:
@@ -761,7 +921,7 @@ status = await client.connect()
761
921
 
762
922
  ### Security Model
763
923
 
764
- ```
924
+ ```text
765
925
  Data Classification:
766
926
  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
767
927
  │ Public Data │ │ Sensitive Data │ │ Never Exposed │
@@ -782,9 +942,8 @@ Data Classification:
782
942
 
783
943
  For detailed release notes and version history, please see [CHANGELOG.md](CHANGELOG.md).
784
944
 
785
- ### Latest Release (0.5.1)
945
+ ### Latest Release (0.6.5)
786
946
 
787
- - **Examples**: Demo scripts for real and mock clients (`examples/` directory)
788
- - **Device Support**: Added mapping for model `PDPR1H1HAR1V0_FW539224`
789
- - **Mock Client**: JSON-based testing framework for development without hardware
790
- - **Fixed**: Removed deprecated references and improved consistency
947
+ - **Device Analyzer**: New CLI command `--analyze` for comprehensive device analysis and support discovery
948
+ - **Code Quality**: Perfect Pylint 10.00/10 score with complete PEP-561 compliance
949
+ - **Enhanced Documentation**: Added device analysis guide for unsupported device discovery
@@ -10,6 +10,9 @@ This client uses an undocumented local HTTP API. It provides live readings for p
10
10
  - **Dynamic sensor discovery** based on device model and firmware
11
11
  - **Dictionary-style access** to instant values
12
12
  - **Structured data API** with type-based organization
13
+ - **Device analyzer** for discovering unsupported device capabilities
14
+ - **PEP-561 compliant** with full type hints for Home Assistant integrations
15
+ - **Command-line interface** for direct device interaction and testing
13
16
  - **Secure by default** - WiFi passwords excluded unless explicitly requested
14
17
  - **Comprehensive error handling** with detailed logging
15
18
  - **SSL/HTTPS support** for secure communication
@@ -151,6 +154,141 @@ client = PooldoseClient("192.168.1.100", use_ssl=True, port=8443, ssl_verify=Fal
151
154
  pip install python-pooldose
152
155
  ```
153
156
 
157
+ ## Command Line Usage
158
+
159
+ After installation, you can use python-pooldose directly from the command line:
160
+
161
+ ### Connect to Real Device
162
+
163
+ ```bash
164
+ # Basic connection
165
+ pooldose --host 192.168.1.100
166
+
167
+ # With HTTPS
168
+ pooldose --host 192.168.1.100 --ssl
169
+
170
+ # Custom port
171
+ pooldose --host 192.168.1.100 --ssl --port 8443
172
+
173
+ # Analyze device capabilities (discover unsupported devices)
174
+ pooldose --host 192.168.1.100 --analyze
175
+
176
+ # Show all widgets including hidden ones
177
+ pooldose --host 192.168.1.100 --analyze-all
178
+ ```
179
+
180
+ ### Mock Mode with JSON Files
181
+
182
+ ```bash
183
+ # Use JSON file for testing
184
+ pooldose --mock path/to/your/data.json
185
+ ```
186
+
187
+ ### Alternative Module Execution
188
+
189
+ You can also run it as a Python module:
190
+
191
+ ```bash
192
+ # Real device
193
+ python -m pooldose --host 192.168.1.100
194
+
195
+ # Device analysis
196
+ python -m pooldose --host 192.168.1.100 --analyze
197
+
198
+ # Mock mode
199
+ python -m pooldose --mock data.json
200
+
201
+ # Show help
202
+ python -m pooldose --help
203
+ ```
204
+
205
+ ## Device Analysis for Unsupported Devices
206
+
207
+ The device analyzer is a powerful feature that helps discover and analyze PoolDose devices that are not yet officially supported. This is particularly useful for:
208
+
209
+ - **New Device Discovery**: Identifying capabilities of unknown device models
210
+ - **Device Support Development**: Gathering data needed to add support for new devices
211
+ - **Troubleshooting**: Understanding how your device exposes data and controls
212
+ - **Widget Exploration**: Discovering all available sensors, controls, and settings
213
+
214
+ ### Basic Device Analysis
215
+
216
+ ```bash
217
+ # Analyze a device to discover its capabilities
218
+ pooldose --host 192.168.1.100 --analyze
219
+
220
+ # Show all widgets including hidden ones
221
+ pooldose --host 192.168.1.100 --analyze-all
222
+
223
+ # Analyze with HTTPS
224
+ pooldose --host 192.168.1.100 --ssl --analyze
225
+ ```
226
+
227
+ ### Analysis Output
228
+
229
+ The analyzer provides comprehensive information about your device:
230
+
231
+ ```
232
+ === DEVICE ANALYSIS ===
233
+ Device: 01234567890A_DEVICE
234
+ Model: PDPR1H1HAW***
235
+ Firmware: FW53****
236
+
237
+ === WIDGETS (Visible UI Elements) ===
238
+
239
+ SENSORS (Read-only values)
240
+ temperature: 24.5°C
241
+ ph: 7.2
242
+ orp: 720 mV
243
+
244
+ SETPOINTS (Configurable values)
245
+ target_ph: 7.0 (Range: 6.0-8.0, Step: 0.1)
246
+ target_orp: 700 mV (Range: 400-900, Step: 10)
247
+
248
+ SWITCHES (On/Off controls)
249
+ stop_dosing: OFF
250
+ pump_detection: ON
251
+
252
+ SELECTS (Configuration options)
253
+ water_meter_unit: L/h
254
+ Options: [L/h, m³/h, gal/h]
255
+
256
+ ALARMS (Status indicators)
257
+ alarm_ph: OK
258
+ alarm_orp: OK
259
+ ```
260
+
261
+ ### Using Analysis for Device Support
262
+
263
+ When you encounter an unsupported device, the analyzer helps gather the necessary information:
264
+
265
+ 1. **Run Analysis**: Use `--analyze` to discover all device capabilities
266
+ 2. **Document Output**: Save the analysis output to understand device structure
267
+ 3. **Check Widget Types**: Note which sensors, controls, and settings are available
268
+ 4. **Identify Patterns**: Look for device model and firmware information
269
+ 5. **Report Findings**: Use the analysis data to request support for your device model
270
+
271
+ ### Example: Discovering New Device
272
+
273
+ ```bash
274
+ # Unknown device analysis
275
+ pooldose --host 192.168.1.100 --analyze
276
+
277
+ # Output shows:
278
+ # Device: 01987654321B_DEVICE
279
+ # Model: PDPR2H2XYZ*** ← New model not yet supported
280
+ # Firmware: FW54**** ← New firmware version
281
+ #
282
+ # Widgets discovered: 15 sensors, 8 controls, 12 settings
283
+ ```
284
+
285
+ With this information, you can:
286
+ - Report the new model/firmware combination
287
+ - Share the widget structure for mapping development
288
+ - Help expand device support for the community
289
+
290
+ The device analyzer makes python-pooldose extensible and helps build support for the growing ecosystem of SEKO PoolDose devices.
291
+
154
292
  ## Examples
155
293
 
156
294
  The `examples/` directory contains demonstration scripts that show how to use the python-pooldose library:
@@ -171,25 +309,6 @@ python examples/demo.py
171
309
  - Displays all sensor readings, alarms, setpoints, and settings
172
310
  - Demonstrates error handling
173
311
 
174
- ### 2. Mock Client Demo (`examples/demo_mock.py`)
175
-
176
- Shows how to use the mock client with JSON files for development and testing:
177
-
178
- ```bash
179
- # Run with sample data
180
- python examples/demo_mock.py references/testdaten/suplere/instantvalues.json
181
-
182
- # Use custom JSON file
183
- python examples/demo_mock.py path/to/your/data.json
184
- ```
185
-
186
- **Features:**
187
-
188
- - No hardware required
189
- - Uses real device data from JSON files
190
- - Same API as real client
191
- - Perfect for development and CI/CD
192
-
193
312
  ### Benefits of the Examples
194
313
 
195
314
  - **Learning**: Step-by-step progression from simple to advanced usage
@@ -248,14 +367,14 @@ asyncio.run(simple_test())
248
367
 
249
368
  ### Mock Client Command Line Usage
250
369
 
251
- You can run the demo script with custom JSON files:
370
+ You can use the mock client with custom JSON files via the command line:
252
371
 
253
372
  ```bash
254
- # Run with sample data
255
- python examples/demo_mock.py references/testdaten/suplere/instantvalues.json
373
+ # Use mock client with JSON file
374
+ pooldose --mock path/to/your/data.json
256
375
 
257
- # Use custom JSON file
258
- python examples/demo_mock.py path/to/your/data.json
376
+ # Or as Python module
377
+ python -m pooldose --mock path/to/your/data.json
259
378
  ```
260
379
 
261
380
  ### JSON Data Format
@@ -326,8 +445,7 @@ success = client.reload_data()
326
445
 
327
446
  The following sample JSON files are available in the repository:
328
447
 
329
- - `references/testdaten/suplere/instantvalues.json` - PDPR1H1HAR1V0_FW539224 device
330
- - `references/testdaten/instantvalues_poolforum_1.json` - Additional sample data
448
+ - `references/testdaten/tscherno/instantvalues.json` - Sample device data for testing
331
449
 
332
450
  ### Mock Client Use Cases
333
451
 
@@ -599,13 +717,13 @@ Mapping Discovery Process:
599
717
 
600
718
 
601
719
  ┌─────────────────┐
602
- │ Get MODEL_ID │ ──────► PDPR1H1HAW100
603
- │ Get FW_CODE │ ──────► 539187
720
+ │ Get MODEL_ID │ ──────► PDPR1H1HAW***
721
+ │ Get FW_CODE │ ──────► 53****
604
722
  └─────────────────┘
605
723
 
606
724
 
607
725
  ┌─────────────────┐
608
- │ Load JSON File │ ──────► model_PDPR1H1HAW100_FW539187.json
726
+ │ Load JSON File │ ──────► model_PDPR1H1HAW***_FW53****.json
609
727
  └─────────────────┘
610
728
 
611
729
 
@@ -723,12 +841,54 @@ The `instant_values_structured()` method returns data organized by type:
723
841
 
724
842
  This client has been tested with:
725
843
 
726
- - **PoolDose Double/Dual WiFi** (Model: PDPR1H1HAW100, FW: 539187)
844
+ - **SEKO PoolDose Double/Dual WiFi** (Model: PDPR1H1HAW***, FW: 53****)
845
+ - **VA dos BASIC Chlor - pH/ORP Wi-Fi** (Model: PDPR1H1HAR***, FW: 53****)
727
846
 
728
- Other SEKO PoolDose models may work but are untested. The client uses JSON mapping files to adapt to different device models and firmware versions (see e.g. `src/pooldose/mappings/model_PDPR1H1HAW100_FW539187.json`).
847
+ Other SEKO PoolDose models may work but are untested. The client uses JSON mapping files to adapt to different device models and firmware versions (see e.g. `src/pooldose/mappings/model_PDPR1H1HAW***_FW53****.json`).
729
848
 
730
849
  > **Note:** The JSON files in the mappings directory define the device-specific data keys and their human-readable names for different PoolDose models and firmware versions.
731
850
 
851
+ ## Type Hints & Home Assistant Integration
852
+
853
+ This package is **PEP-561 compliant** and fully typed for use in Home Assistant integrations:
854
+
855
+ ### Type Safety Features
856
+
857
+ **PEP-561 Compliance**: Package includes `py.typed` file marking it as fully typed
858
+ **Comprehensive Type Annotations**: All public API methods have complete type hints
859
+ **mypy Support**: Built-in mypy configuration for static type checking
860
+ **Home Assistant Ready**: Compatible with Home Assistant's strict typing requirements
861
+
862
+ ### Type-Safe Usage
863
+
864
+ ```python
865
+ from pooldose import PooldoseClient
866
+ from pooldose.request_status import RequestStatus
867
+
868
+ # Type checkers will infer all types automatically
869
+ client: PooldoseClient = PooldoseClient("192.168.1.100")
870
+ status: RequestStatus = await client.connect()
871
+
872
+ # Dictionary-style access with proper typing
873
+ status, instant_values = await client.instant_values()
874
+ if status == RequestStatus.SUCCESS and instant_values:
875
+ temperature = instant_values["temperature"] # Typed as tuple[float, str]
876
+ ph_value = instant_values.get("ph", "N/A") # Safe access with default
877
+
878
+ # Structured data with full type safety
879
+ status, structured_data = await client.instant_values_structured()
880
+ sensors = structured_data.get("sensor", {}) # Type: dict[str, dict[str, Any]]
881
+ ```
882
+
883
+ ### Integration Benefits
884
+
885
+ - **IDE Support**: Full autocomplete and type checking in VS Code, PyCharm, etc.
886
+ - **Runtime Safety**: Catch type errors before deployment
887
+ - **Documentation**: Self-documenting code through type annotations
888
+ - **Maintenance**: Easier refactoring with type-guided development
889
+
890
+ For Home Assistant integrations, add this package to your integration's dependencies and enjoy full type safety throughout your integration code.
891
+
732
892
  ## Security
733
893
 
734
894
  By default, the client excludes sensitive information like WiFi passwords from device info. To include sensitive data:
@@ -743,7 +903,7 @@ status = await client.connect()
743
903
 
744
904
  ### Security Model
745
905
 
746
- ```
906
+ ```text
747
907
  Data Classification:
748
908
  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
749
909
  │ Public Data │ │ Sensitive Data │ │ Never Exposed │
@@ -764,9 +924,8 @@ Data Classification:
764
924
 
765
925
  For detailed release notes and version history, please see [CHANGELOG.md](CHANGELOG.md).
766
926
 
767
- ### Latest Release (0.5.1)
927
+ ### Latest Release (0.6.5)
768
928
 
769
- - **Examples**: Demo scripts for real and mock clients (`examples/` directory)
770
- - **Device Support**: Added mapping for model `PDPR1H1HAR1V0_FW539224`
771
- - **Mock Client**: JSON-based testing framework for development without hardware
772
- - **Fixed**: Removed deprecated references and improved consistency
929
+ - **Device Analyzer**: New CLI command `--analyze` for comprehensive device analysis and support discovery
930
+ - **Code Quality**: Perfect Pylint 10.00/10 score with complete PEP-561 compliance
931
+ - **Enhanced Documentation**: Added device analysis guide for unsupported device discovery
@@ -0,0 +1,88 @@
1
+ [project]
2
+ name = "python-pooldose"
3
+ dynamic = ["version"]
4
+ description = "Unoffical async Python client for SEKO PoolDose devices"
5
+ authors = [
6
+ { name = "Lukas Maertin", email = "pypi@lukas-maertin.de" }
7
+ ]
8
+ license = "MIT"
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ dependencies = [
12
+ "aiohttp",
13
+ "aiofiles"
14
+ ]
15
+
16
+ [project.urls]
17
+ Homepage = "https://github.com/lmaertin/python-pooldose"
18
+ Repository = "https://github.com/lmaertin/python-pooldose"
19
+
20
+ [project.scripts]
21
+ pooldose = "pooldose.__main__:main"
22
+
23
+ [build-system]
24
+ requires = ["setuptools>=61.0", "wheel"]
25
+ build-backend = "setuptools.build_meta"
26
+
27
+ [project.optional-dependencies]
28
+ dev = ["pytest", "pytest-asyncio"]
29
+
30
+ [tool.setuptools]
31
+ package-dir = {"" = "src"}
32
+
33
+ [tool.setuptools.dynamic]
34
+ version = {attr = "pooldose.__version__"}
35
+
36
+ [tool.setuptools.packages.find]
37
+ where = ["src"]
38
+
39
+ [tool.setuptools.package-data]
40
+ "pooldose.mappings" = ["*.json"]
41
+ "pooldose" = ["py.typed"]
42
+
43
+ [tool.pytest.ini_options]
44
+ testpaths = ["tests"]
45
+ asyncio_mode = "auto"
46
+
47
+ [tool.mypy]
48
+ python_version = "3.11"
49
+ # Home Assistant strict typing compliance
50
+ strict = false
51
+ warn_return_any = false
52
+ warn_unused_configs = true
53
+ disallow_untyped_defs = false
54
+ disallow_incomplete_defs = false
55
+ check_untyped_defs = true
56
+ no_implicit_optional = true
57
+ warn_redundant_casts = true
58
+ warn_unused_ignores = false
59
+ warn_no_return = true
60
+ strict_equality = true
61
+ ignore_missing_imports = true
62
+ # Focus on public API typing
63
+ show_error_codes = true
64
+
65
+ [[tool.mypy.overrides]]
66
+ module = "examples.*"
67
+ ignore_errors = true
68
+
69
+ [[tool.mypy.overrides]]
70
+ module = "tests.*"
71
+ ignore_errors = true
72
+
73
+ # Strict typing for core public API modules
74
+ [[tool.mypy.overrides]]
75
+ module = "pooldose.__init__"
76
+ disallow_untyped_defs = true
77
+ disallow_incomplete_defs = true
78
+
79
+ [[tool.mypy.overrides]]
80
+ module = "pooldose.client"
81
+ disallow_untyped_defs = true
82
+ disallow_incomplete_defs = true
83
+ warn_return_any = false
84
+
85
+ [[tool.mypy.overrides]]
86
+ module = "pooldose.request_status"
87
+ disallow_untyped_defs = true
88
+ disallow_incomplete_defs = true