violet-poolController-api 0.0.38__tar.gz → 0.0.40__tar.gz

{violet_poolcontroller_api-0.0.38/violet_poolController_api.egg-info → violet_poolcontroller_api-0.0.40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: violet-poolController-api
-Version: 0.0.38
+Version: 0.0.40
 Summary: Asynchronous Python client for the Violet Pool Controller.
 Author-email: "Basti (Xerolux)" <git@xerolux.de>
 License-Expression: AGPL-3.0-or-later
@@ -20,7 +20,7 @@ Classifier: Topic :: Home Automation
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: aiohttp<3.15,>=3.11.0
+Requires-Dist: aiohttp>=3.11.0
 Provides-Extra: test
 Requires-Dist: aioresponses>=0.7.9; extra == "test"
 Requires-Dist: mypy>=1.15; extra == "test"
@@ -40,7 +40,7 @@ Dynamic: license-file
 
 An asynchronous Python client for interacting with the **Violet Pool Controller**.
 
-This library is primarily designed to power the official [Violet Pool Controller Home Assistant Integration](https://github.com/Xerolux/violet-hass), but it can be used independently for any Python project that needs to fetch readings or control a Violet Pool system.
+This library is primarily designed to power the [Violet Pool Controller Home Assistant Integration](https://github.com/Xerolux/violet-hass), but it can be used independently for any Python project that needs to fetch readings or control a Violet Pool system.
 
 > **📖 Documentation:**
 > - GitHub Pages: https://xerolux.github.io/violet-poolController-api/
@@ -117,7 +117,7 @@ The API client includes many more functions tailored to the Violet Controller:
 - `set_pv_surplus(active=True)`: Enable the PV-Surplus mode.
 - `manual_dosing(dosing_type="Chlor", duration=120)`: Trigger manual chemical dosing.
 
-For a full list of available commands and more detailed examples, please refer to the [Wiki](https://github.com/Xerolux/violet-poolController-api/wiki) or the source code in `api.py`.
+For a full list of available commands and more detailed examples, please refer to the [Wiki](https://github.com/Xerolux/violet-poolController-api/wiki) or the `_api_*.py` mixins, which hold the public methods.
 
 ## Violet Dosing Standalone Mode
 
@@ -136,7 +136,7 @@ api = VioletPoolAPI(
 In this mode, dosing functions (for example `manual_dosing` and dosing parameter/target updates) stay available, while base-module-only switch functions (for example pump/light/backwash) are blocked with a clear error message.
 
 **Note on getReadings format:**
-As of version `0.0.7`, the API client automatically detects and normalizes the payload output from the controller. Whether your Violet Controller returns the classic base-module `dict` structure (`{"PUMPSTATE": "2", "PH": 7.2}`) or the new standalone `list` structure, the `get_readings()` and `get_specific_readings()` functions will always return a seamless, flattened key-value dictionary. Your Home Assistant integration or downstream application will work uniformly with both formats without requiring any extra code!
+As of version `0.0.7`, the API client automatically detects and normalizes the payload output from the controller. Whether your Violet Controller returns the classic base-module `dict` structure (`{"PUMPSTATE": "2", "PH": 7.2}`) or the new standalone `list` structure, the `get_readings()` and `get_specific_readings()` functions always return a flattened key-value view. `get_readings()` returns a `VioletReadings`, a read-only `Mapping` with typed accessors on top; use `dict(readings)` where a plain `dict` is required, for example before JSON serialization. Your Home Assistant integration or downstream application will work uniformly with both formats without requiring any extra code!
 
 **Hardware Profile Detection:**
 As of the latest release, the API client provides a method to detect the specific hardware configuration of your Violet Controller.
@@ -152,7 +152,7 @@ print(profile)
 #     "extension_module_2": False,
 # }
 ```
-This detection parses `get_readings()` to check for the presence of certain internal status parameters (`SYSTEM_dosagemodule_cpu_temperature`, `EXT1_1`, `EXT2_1`), allowing your application to dynamically adapt to the connected modules (Base Module, Dosing Module, Relay Extension 1 and 2). By utilizing this detection, developers and integrations can accurately filter out features for missing hardware, ensuring that only supported options are exposed to the user.
+This detection reads the controller's own module counters (`SYSTEM_dosagemodule_alive_count`, `SYSTEM_ext1module_alive_count`, `SYSTEM_ext2module_alive_count`), allowing your application to dynamically adapt to the connected modules (Base Module, Dosing Module, Relay Extension 1 and 2). By utilizing this detection, developers and integrations can accurately filter out features for missing hardware, ensuring that only supported options are exposed to the user.
 
 ## Mock Server (Testing Without Hardware)
 
@@ -229,7 +229,7 @@ GNU Affero General Public License v3.0 or later (AGPLv3+)
 
 The **VIOLET Pool Controller** by [PoolDigital GmbH & Co. KG](https://www.pooldigital.de/) is a premium smart pool automation system developed in Germany, featuring a JSON API for seamless Home Assistant integration.
 
-- **Offizieller Shop:** [pooldigital.de](https://www.pooldigital.de/)
+- **Official shop:** [pooldigital.de](https://www.pooldigital.de/)
 - **Community:** [PoolDigital Forum](http://forum.pooldigital.de/)
 
 **Disclaimer:**

{violet_poolcontroller_api-0.0.38 → violet_poolcontroller_api-0.0.40}/README.md

@@ -10,7 +10,7 @@
 
 An asynchronous Python client for interacting with the **Violet Pool Controller**.
 
-This library is primarily designed to power the official [Violet Pool Controller Home Assistant Integration](https://github.com/Xerolux/violet-hass), but it can be used independently for any Python project that needs to fetch readings or control a Violet Pool system.
+This library is primarily designed to power the [Violet Pool Controller Home Assistant Integration](https://github.com/Xerolux/violet-hass), but it can be used independently for any Python project that needs to fetch readings or control a Violet Pool system.
 
 > **📖 Documentation:**
 > - GitHub Pages: https://xerolux.github.io/violet-poolController-api/
@@ -87,7 +87,7 @@ The API client includes many more functions tailored to the Violet Controller:
 - `set_pv_surplus(active=True)`: Enable the PV-Surplus mode.
 - `manual_dosing(dosing_type="Chlor", duration=120)`: Trigger manual chemical dosing.
 
-For a full list of available commands and more detailed examples, please refer to the [Wiki](https://github.com/Xerolux/violet-poolController-api/wiki) or the source code in `api.py`.
+For a full list of available commands and more detailed examples, please refer to the [Wiki](https://github.com/Xerolux/violet-poolController-api/wiki) or the `_api_*.py` mixins, which hold the public methods.
 
 ## Violet Dosing Standalone Mode
 
@@ -106,7 +106,7 @@ api = VioletPoolAPI(
 In this mode, dosing functions (for example `manual_dosing` and dosing parameter/target updates) stay available, while base-module-only switch functions (for example pump/light/backwash) are blocked with a clear error message.
 
 **Note on getReadings format:**
-As of version `0.0.7`, the API client automatically detects and normalizes the payload output from the controller. Whether your Violet Controller returns the classic base-module `dict` structure (`{"PUMPSTATE": "2", "PH": 7.2}`) or the new standalone `list` structure, the `get_readings()` and `get_specific_readings()` functions will always return a seamless, flattened key-value dictionary. Your Home Assistant integration or downstream application will work uniformly with both formats without requiring any extra code!
+As of version `0.0.7`, the API client automatically detects and normalizes the payload output from the controller. Whether your Violet Controller returns the classic base-module `dict` structure (`{"PUMPSTATE": "2", "PH": 7.2}`) or the new standalone `list` structure, the `get_readings()` and `get_specific_readings()` functions always return a flattened key-value view. `get_readings()` returns a `VioletReadings`, a read-only `Mapping` with typed accessors on top; use `dict(readings)` where a plain `dict` is required, for example before JSON serialization. Your Home Assistant integration or downstream application will work uniformly with both formats without requiring any extra code!
 
 **Hardware Profile Detection:**
 As of the latest release, the API client provides a method to detect the specific hardware configuration of your Violet Controller.
@@ -122,7 +122,7 @@ print(profile)
 #     "extension_module_2": False,
 # }
 ```
-This detection parses `get_readings()` to check for the presence of certain internal status parameters (`SYSTEM_dosagemodule_cpu_temperature`, `EXT1_1`, `EXT2_1`), allowing your application to dynamically adapt to the connected modules (Base Module, Dosing Module, Relay Extension 1 and 2). By utilizing this detection, developers and integrations can accurately filter out features for missing hardware, ensuring that only supported options are exposed to the user.
+This detection reads the controller's own module counters (`SYSTEM_dosagemodule_alive_count`, `SYSTEM_ext1module_alive_count`, `SYSTEM_ext2module_alive_count`), allowing your application to dynamically adapt to the connected modules (Base Module, Dosing Module, Relay Extension 1 and 2). By utilizing this detection, developers and integrations can accurately filter out features for missing hardware, ensuring that only supported options are exposed to the user.
 
 ## Mock Server (Testing Without Hardware)
 
@@ -199,7 +199,7 @@ GNU Affero General Public License v3.0 or later (AGPLv3+)
 
 The **VIOLET Pool Controller** by [PoolDigital GmbH & Co. KG](https://www.pooldigital.de/) is a premium smart pool automation system developed in Germany, featuring a JSON API for seamless Home Assistant integration.
 
-- **Offizieller Shop:** [pooldigital.de](https://www.pooldigital.de/)
+- **Official shop:** [pooldigital.de](https://www.pooldigital.de/)
 - **Community:** [PoolDigital Forum](http://forum.pooldigital.de/)
 
 **Disclaimer:**

{violet_poolcontroller_api-0.0.38 → violet_poolcontroller_api-0.0.40}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "violet-poolController-api"
-version = "0.0.38"
+version = "0.0.40"
 authors = [
   { name="Basti (Xerolux)", email="git@xerolux.de" },
 ]
@@ -25,7 +25,11 @@ classifiers = [
     "Topic :: Home Automation",
 ]
 dependencies = [
-    "aiohttp>=3.11.0,<3.15",
+    # No upper bound on purpose: Home Assistant installs this package into
+    # its own environment and follows aiohttp closely.  A "<3.15" cap made pip
+    # refuse the install the day HA moved past it, taking the integration down
+    # with it.  Compatibility with newer aiohttp is handled in the test shim.
+    "aiohttp>=3.11.0",
 ]
 
 [project.optional-dependencies]

{violet_poolcontroller_api-0.0.38 → violet_poolcontroller_api-0.0.40}/tests/test_api.py

@@ -42,6 +42,7 @@ from violet_poolcontroller_api.const_api import (
     ERROR_SEVERITY_INFO,
     ERROR_SEVERITY_REMINDER,
     ERROR_SEVERITY_WARNING,
+    QUERY_FULL_REFRESH,
     TARGET_PH,
 )
 
@@ -92,7 +93,7 @@ async def test_get_readings_success(
     api_client: VioletPoolAPI,
 ) -> None:
     """Test get_readings returns the correct parsed JSON dictionary."""
-    url = "http://192.168.1.100/getReadings?ALL"
+    url = "http://192.168.1.100/getReadings?ALL,DOSAGE,RUNTIMES,PUMPPRIOSTATE,BACKWASH,SYSTEM"
     mock_data = {"PUMPSTATE": "2", "PH": 7.2}
     mock_aioresponse.get(url, payload=mock_data, status=200)
 
@@ -102,6 +103,25 @@ async def test_get_readings_success(
     assert dict(result) == mock_data
 
 
+@pytest.mark.asyncio
+async def test_get_readings_requests_all_feature_flags(
+    mock_aioresponse: aioresponses,
+    api_client: VioletPoolAPI,
+) -> None:
+    """Plain ``ALL`` omits the computed fields (daily dosing totals, runtime
+    strings, priority-state composites) on some firmware states, leaving the
+    matching sensors at ``unknown``.  get_readings() must therefore always
+    ask for ``ALL`` combined with every feature-flag token."""
+    url = f"http://192.168.1.100/getReadings?{QUERY_FULL_REFRESH}"
+    mock_aioresponse.get(url, payload={"PUMPSTATE": "2"}, status=200)
+
+    await api_client.get_readings()
+
+    # aioresponses matches the URL exactly; reaching this point without an
+    # unsatisfied-mock error proves the full query string was sent.
+    assert mock_aioresponse.requests
+
+
 @pytest.mark.asyncio
 async def test_get_output_runtimes_success(
     mock_aioresponse: aioresponses,
@@ -164,7 +184,7 @@ async def test_request_server_error(
     api_client: VioletPoolAPI,
 ) -> None:
     """Test that a 500 error raises VioletPoolAPIError after retrying."""
-    url = "http://192.168.1.100/getReadings?ALL"
+    url = "http://192.168.1.100/getReadings?ALL,DOSAGE,RUNTIMES,PUMPPRIOSTATE,BACKWASH,SYSTEM"
     mock_aioresponse.get(url, status=500)
     # the second time it retries
     mock_aioresponse.get(url, status=500)
@@ -274,11 +294,56 @@ async def test_set_config_sanitizes_payload_before_request(
 
     monkeypatch.setattr(api_client, "_request", fake_request)
 
-    result = await api_client.set_config({"pool mode": "A<mode>", "speed": 3.7})
+    result = await api_client.set_config({"POOL_MODE": "A<mode>", "speed": 3.7})
 
     assert result["success"] is True
     assert result["response"] == "OK"
-    assert captured["data"] == {"poolmode": "A<mode>", "speed": 3.7}
+    assert captured["data"] == {"POOL_MODE": "A<mode>", "speed": 3.7}
+
+
+@pytest.mark.asyncio
+async def test_set_config_rejects_invalid_key_instead_of_rewriting_it(
+    api_client: VioletPoolAPI,
+    monkeypatch: pytest.Monkeypatch,
+) -> None:
+    """A malformed key is an error, never a silent write to a different key.
+
+    ``"pool mode"`` used to be rewritten to ``"poolmode"`` and sent, so a typo
+    in a configuration key changed a setting the caller never named.
+    """
+    sent = False
+
+    async def fake_request(_endpoint: str, **_kwargs: Any) -> str:  # noqa: ANN401
+        nonlocal sent
+        sent = True
+        return "OK"
+
+    monkeypatch.setattr(api_client, "_request", fake_request)
+
+    with pytest.raises(VioletPoolAPIError, match="Invalid configuration parameter"):
+        await api_client.set_config({"pool mode": "A"})
+
+    assert sent is False
+
+
+@pytest.mark.asyncio
+async def test_set_config_rejects_unsupported_value_types(
+    api_client: VioletPoolAPI,
+    monkeypatch: pytest.Monkeypatch,
+) -> None:
+    """None and containers must not reach the controller as "None" or "1 2"."""
+
+    async def fake_request(_endpoint: str, **_kwargs: Any) -> str:  # noqa: ANN401
+        return "OK"
+
+    monkeypatch.setattr(api_client, "_request", fake_request)
+
+    for bad_value in (None, [1, 2], {"a": 1}):
+        with pytest.raises(VioletPoolAPIError):
+            await api_client.set_config({"SOME_KEY": bad_value})
+
+    with pytest.raises(VioletPoolAPIError, match="Non-finite"):
+        await api_client.set_config({"SOME_KEY": float("nan")})
 
 
 @pytest.mark.asyncio
@@ -313,7 +378,7 @@ async def test_get_readings_standalone_list_format(
     api_client: VioletPoolAPI,
 ) -> None:
     """Test get_readings parses the standalone list format correctly."""
-    url = "http://192.168.1.100/getReadings?ALL"
+    url = "http://192.168.1.100/getReadings?ALL,DOSAGE,RUNTIMES,PUMPPRIOSTATE,BACKWASH,SYSTEM"
     mock_data = {
         "getReadings": [
             {
@@ -349,7 +414,7 @@ async def test_dosing_standalone_detection_dict_format(
     standalone_api_client: VioletPoolAPI,
 ) -> None:
     """Test dosing_standalone is set to False when dict format is received."""
-    url = "http://192.168.1.100/getReadings?ALL"
+    url = "http://192.168.1.100/getReadings?ALL,DOSAGE,RUNTIMES,PUMPPRIOSTATE,BACKWASH,SYSTEM"
     mock_data = {
         "getReadings": {
             "PUMPSTATE": "2",
@@ -369,7 +434,7 @@ async def test_dosing_standalone_detection_dict_format(
 @pytest.mark.asyncio
 async def test_get_hardware_profile(mock_aioresponse, api_client):
     """Test get_hardware_profile correctly detects components via alive counters."""
-    url = "http://192.168.1.100/getReadings?ALL"
+    url = "http://192.168.1.100/getReadings?ALL,DOSAGE,RUNTIMES,PUMPPRIOSTATE,BACKWASH,SYSTEM"
 
     # 1. Base module only (no DOS, EXT)
     mock_aioresponse.get(
@@ -479,7 +544,7 @@ async def test_module_alive_on_zero_count(mock_aioresponse, api_client):
     old code required value > 0, which caused EXT1_* readings to be filtered
     and the relay switch to appear broken right after a restart.
     """
-    url = "http://192.168.1.100/getReadings?ALL"
+    url = "http://192.168.1.100/getReadings?ALL,DOSAGE,RUNTIMES,PUMPPRIOSTATE,BACKWASH,SYSTEM"
     mock_aioresponse.get(
         url,
         payload={
@@ -503,7 +568,7 @@ async def test_module_alive_on_zero_count(mock_aioresponse, api_client):
 @pytest.mark.asyncio
 async def test_ext1_readings_not_filtered_when_detected(mock_aioresponse, api_client):
     """EXT1_* readings are included when extension_module_1 is detected."""
-    url = "http://192.168.1.100/getReadings?ALL"
+    url = "http://192.168.1.100/getReadings?ALL,DOSAGE,RUNTIMES,PUMPPRIOSTATE,BACKWASH,SYSTEM"
     mock_aioresponse.get(
         url,
         payload={
@@ -527,7 +592,7 @@ async def test_ext1_readings_not_filtered_when_detected(mock_aioresponse, api_cl
 @pytest.mark.asyncio
 async def test_ext1_readings_filtered_when_not_detected(mock_aioresponse, api_client):
     """EXT1_* readings are stripped when extension_module_1 key is absent."""
-    url = "http://192.168.1.100/getReadings?ALL"
+    url = "http://192.168.1.100/getReadings?ALL,DOSAGE,RUNTIMES,PUMPPRIOSTATE,BACKWASH,SYSTEM"
     mock_aioresponse.get(
         url,
         payload={
@@ -549,7 +614,7 @@ async def test_ext1_readings_filtered_when_not_detected(mock_aioresponse, api_cl
 @pytest.mark.asyncio
 async def test_get_hardware_profile_standalone_dosing(mock_aioresponse, standalone_api_client):
     """Test get_hardware_profile with a standalone dosing configuration."""
-    url = "http://192.168.1.100/getReadings?ALL"
+    url = "http://192.168.1.100/getReadings?ALL,DOSAGE,RUNTIMES,PUMPPRIOSTATE,BACKWASH,SYSTEM"
     # Using the standalone list format
     mock_data = {
         "getReadings": [
@@ -1383,14 +1448,20 @@ async def test_command_result_dosing_started(
 
 
 @pytest.mark.asyncio
-async def test_command_result_dict_passthrough(
+async def test_command_result_normalizes_dict_input(
     api_client: VioletPoolAPI,
 ) -> None:
-    """Test _command_result passes dict through unchanged."""
+    """A dict body is normalized, so ``success`` is always present.
+
+    The old passthrough returned the dict unchanged, so a caller reading
+    ``result["success"]`` got a KeyError instead of a result.
+    """
     data = {"key": "value", "nested": {"a": 1}}
     result = VioletPoolAPI._command_result(data)
 
-    assert result is data
+    assert result["success"] is True
+    assert result["key"] == "value"
+    assert result["nested"] == {"a": 1}
 
 
 @pytest.mark.asyncio
@@ -1823,7 +1894,7 @@ async def test_client_error_fails_fast_without_retry(
     api_client: VioletPoolAPI,
 ) -> None:
     """A 4xx response raises immediately instead of being retried."""
-    url = "http://192.168.1.100/getReadings?ALL"
+    url = "http://192.168.1.100/getReadings?ALL,DOSAGE,RUNTIMES,PUMPPRIOSTATE,BACKWASH,SYSTEM"
     mock_aioresponse.get(url, status=401, body="Unauthorized")
 
     with pytest.raises(VioletPoolAPIError, match="HTTP 401"):
@@ -1836,7 +1907,7 @@ async def test_client_error_does_not_trip_circuit_breaker(
     api_client: VioletPoolAPI,
 ) -> None:
     """Deterministic 4xx errors must not count as circuit breaker failures."""
-    url = "http://192.168.1.100/getReadings?ALL"
+    url = "http://192.168.1.100/getReadings?ALL,DOSAGE,RUNTIMES,PUMPPRIOSTATE,BACKWASH,SYSTEM"
     threshold = api_client._circuit_breaker.failure_threshold
 
     for _ in range(threshold + 1):
@@ -1856,7 +1927,7 @@ async def test_empty_get_readings_payload_is_flattened(
     mock_aioresponse: aioresponses,
     api_client: VioletPoolAPI,
 ) -> None:
-    url = "http://192.168.1.100/getReadings?ALL"
+    url = "http://192.168.1.100/getReadings?ALL,DOSAGE,RUNTIMES,PUMPPRIOSTATE,BACKWASH,SYSTEM"
     mock_aioresponse.get(url, payload={"getReadings": {}}, status=200)
 
     readings = await api_client.get_readings()
@@ -1886,7 +1957,7 @@ async def test_basic_auth_uses_authorization_header(
     mock_aioresponse: aioresponses,
     api_client: VioletPoolAPI,
 ) -> None:
-    url = "http://192.168.1.100/getReadings?ALL"
+    url = "http://192.168.1.100/getReadings?ALL,DOSAGE,RUNTIMES,PUMPPRIOSTATE,BACKWASH,SYSTEM"
     mock_aioresponse.get(url, payload={}, status=200)
 
     await api_client.get_readings()
@@ -1902,7 +1973,7 @@ async def test_server_error_still_counts_for_circuit_breaker(
     api_client: VioletPoolAPI,
 ) -> None:
     """5xx errors keep counting as circuit breaker failures."""
-    url = "http://192.168.1.100/getReadings?ALL"
+    url = "http://192.168.1.100/getReadings?ALL,DOSAGE,RUNTIMES,PUMPPRIOSTATE,BACKWASH,SYSTEM"
     mock_aioresponse.get(url, status=500, body="boom", repeat=True)
 
     with pytest.raises(VioletPoolAPIError):
@@ -1925,7 +1996,7 @@ async def test_rate_limiter_reacquired_on_every_retry(
     retry loop, so retries fired real HTTP requests without ever going
     through the limiter again.
     """
-    url = "http://192.168.1.100/getReadings?ALL"
+    url = "http://192.168.1.100/getReadings?ALL,DOSAGE,RUNTIMES,PUMPPRIOSTATE,BACKWASH,SYSTEM"
     mock_aioresponse.get(url, status=500, body="boom", repeat=True)
     # Backoff sleeps aren't what this test verifies; skip them for speed.
     monkeypatch.setattr("violet_poolcontroller_api.api.asyncio.sleep", AsyncMock())
@@ -2130,3 +2201,163 @@ def test_input_sanitizer_no_duplicate_validate_duration() -> None:
 
     assert not hasattr(InputSanitizer, "validate_duration")
     assert not hasattr(InputSanitizer, "validate_speed")
+
+
+def _request_count(mocked: aioresponses, method: str, path: str) -> int:
+    """Count recorded requests to *path*, ignoring query-string normalization.
+
+    yarl rewrites a value-less query (``?PUMP,ON,0,0``) by appending ``=``, so
+    the recorded key never equals the URL that was requested.
+    """
+    return sum(
+        len(calls)
+        for (recorded_method, url), calls in mocked.requests.items()
+        if recorded_method == method and url.path == path
+    )
+
+
+# ---------------------------------------------------------------------------
+# Regression: state-changing commands are sent exactly once (0.0.39)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_switch_command_is_not_retried(
+    mock_aioresponse: aioresponses,
+) -> None:
+    """A failed switch command must not be repeated.
+
+    The controller applies state changes through GET, and a request that
+    timed out may well have been applied.  Repeating it can toggle the output
+    back or apply it a second time.
+    """
+    url = "http://192.168.1.100/setFunctionManually?PUMP,ON,0,0"
+    mock_aioresponse.get(url, status=500, body="boom")
+
+    async with aiohttp.ClientSession() as session:
+        api = VioletPoolAPI(host="192.168.1.100", session=session, max_retries=3)
+        with pytest.raises(VioletPoolAPIError):
+            await api.set_switch_state("PUMP", "ON")
+
+    assert _request_count(mock_aioresponse, "GET", "/setFunctionManually") == 1
+
+
+@pytest.mark.asyncio
+async def test_digital_rule_trigger_is_not_retried(
+    mock_aioresponse: aioresponses,
+) -> None:
+    """PUSH is a toggle: a retry would undo the change it just made."""
+    url = "http://192.168.1.100/setFunctionManually?DIRULE_1,PUSH,0,0"
+    mock_aioresponse.get(url, status=500, body="boom")
+
+    async with aiohttp.ClientSession() as session:
+        api = VioletPoolAPI(host="192.168.1.100", session=session, max_retries=3)
+        with pytest.raises(VioletPoolAPIError):
+            await api.trigger_digital_input_rule("DIRULE_1")
+
+    assert _request_count(mock_aioresponse, "GET", "/setFunctionManually") == 1
+
+
+@pytest.mark.asyncio
+async def test_init_update_is_not_retried(
+    mock_aioresponse: aioresponses,
+) -> None:
+    """Starting a firmware update twice is not harmless."""
+    url = "http://192.168.1.100/initUpdate"
+    mock_aioresponse.get(url, status=503, body="busy")
+
+    async with aiohttp.ClientSession() as session:
+        api = VioletPoolAPI(host="192.168.1.100", session=session, max_retries=3)
+        with pytest.raises(VioletPoolAPIError):
+            await api.init_update()
+
+    assert _request_count(mock_aioresponse, "GET", "/initUpdate") == 1
+
+
+@pytest.mark.asyncio
+async def test_reads_are_still_retried(
+    mock_aioresponse: aioresponses,
+) -> None:
+    """The read path keeps its retries; repeating a read costs nothing."""
+    url = "http://192.168.1.100/getReadings?ALL,DOSAGE,RUNTIMES,PUMPPRIOSTATE,BACKWASH,SYSTEM"
+    mock_aioresponse.get(url, status=500, body="boom")
+    mock_aioresponse.get(url, status=500, body="boom")
+    mock_aioresponse.get(url, payload={"getReadings": {"PUMP": "1"}}, status=200)
+
+    async with aiohttp.ClientSession() as session:
+        api = VioletPoolAPI(host="192.168.1.100", session=session, max_retries=3)
+        readings = await api.get_readings()
+
+    assert readings["PUMP"] == "1"
+    assert _request_count(mock_aioresponse, "GET", "/getReadings") == 3
+
+
+@pytest.mark.asyncio
+async def test_rate_limit_wait_timeout_fails_instead_of_bypassing(
+    mock_aioresponse: aioresponses,
+    monkeypatch: pytest.Monkeypatch,
+) -> None:
+    """A limiter timeout must fail the request, not send it without a token.
+
+    Sending anyway let every caller that waited out the timeout hit the
+    controller at once, which is the pile-up the limiter exists to prevent.
+    """
+    url = "http://192.168.1.100/getReadings?ALL,DOSAGE,RUNTIMES,PUMPPRIOSTATE,BACKWASH,SYSTEM"
+    mock_aioresponse.get(url, payload={"getReadings": {}}, status=200)
+
+    async with aiohttp.ClientSession() as session:
+        api = VioletPoolAPI(host="192.168.1.100", session=session, max_retries=1)
+
+        async def always_timeout(**_kwargs: Any) -> None:
+            raise TimeoutError
+
+        monkeypatch.setattr(api._rate_limiter, "wait_if_needed", always_timeout)
+
+        with pytest.raises(VioletPoolAPIError, match="Rate limit wait"):
+            await api.get_readings()
+
+    assert _request_count(mock_aioresponse, "GET", "/getReadings") == 0
+
+
+@pytest.mark.asyncio
+async def test_html_login_page_does_not_open_the_circuit_breaker(
+    mock_aioresponse: aioresponses,
+) -> None:
+    """A captive portal answers 200 with HTML every time, deterministically.
+
+    Counting those as transient failures opened the breaker and replaced the
+    payload error that explains the actual problem.
+    """
+    url = "http://192.168.1.100/getReadings?ALL,DOSAGE,RUNTIMES,PUMPPRIOSTATE,BACKWASH,SYSTEM"
+    for _ in range(8):
+        mock_aioresponse.get(url, body="<html>login</html>", status=200)
+
+    async with aiohttp.ClientSession() as session:
+        api = VioletPoolAPI(host="192.168.1.100", session=session, max_retries=1)
+        for _ in range(8):
+            with pytest.raises(VioletPoolAPIError) as excinfo:
+                await api.get_readings()
+            assert "Invalid JSON payload" in str(excinfo.value)
+
+
+def test_hostname_error_never_echoes_credentials() -> None:
+    """The message reaches config-flow errors and logs; it must stay clean."""
+    with pytest.raises(ValueError, match="must not contain credentials") as excinfo:
+        VioletPoolAPI._build_secure_base_url(
+            VioletPoolAPI,
+            "http://admin:s3cret@192.168.1.5",
+            use_ssl=False,
+        )
+
+    assert "s3cret" not in str(excinfo.value)
+
+
+def test_hostname_accepts_underscores() -> None:
+    """mDNS and router-assigned names use underscores."""
+    url = VioletPoolAPI._build_secure_base_url(
+        VioletPoolAPI,
+        "violet_pool.local",
+        use_ssl=False,
+    )
+
+    assert url == "http://violet_pool.local"

{violet_poolcontroller_api-0.0.38 → violet_poolcontroller_api-0.0.40}/tests/test_language_policy.py

@@ -64,6 +64,24 @@ GERMAN_WORDS = (
     "dieser",
     "keine",
     "sollte",
+    # Added after 0.0.38 shipped with ~20 German docstrings and log lines in
+    # utils_sanitizer.py and utils_rate_limiter.py that this list did not see.
+    "einen",
+    "eine",
+    "verwende",
+    "ungültig",
+    "ungültige",
+    "ungültigen",
+    "ungültiger",
+    "verfügbar",
+    "gefährlich",
+    "gefährliche",
+    "erlaubt",
+    "erlaubter",
+    "zurückgesetzt",
+    "initialisiert",
+    "unbekannter",
+    "warte",
 )
 _GERMAN = re.compile(r"\b(" + "|".join(GERMAN_WORDS) + r")\b", re.IGNORECASE)
 

{violet_poolcontroller_api-0.0.38 → violet_poolcontroller_api-0.0.40}/tests/test_mock_server.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 
 import asyncio
 import base64
+import json
 import socket
 import subprocess
 import sys
@@ -89,6 +90,21 @@ async def test_raw_auth() -> None:
     assert status == 200, f"Expected 200, got {status}"
     print(f"  OK: status={status} body_len={len(body)}")
 
+    print()
+    print("=" * 60)
+    print("TEST 1b: ALL plus feature-flag tokens must not filter the payload")
+    print("=" * 60)
+    status_mixed, body_mixed = await _request(
+        f"http://{HOST}:{PORT}/getReadings?ALL,DOSAGE,RUNTIMES,PUMPPRIOSTATE,BACKWASH,SYSTEM"
+    )
+    assert status_mixed == 200, f"Expected 200, got {status_mixed}"
+    # build_readings() re-randomizes sensor values per call, so compare the
+    # key set: ALL + tokens must return the same unfiltered key set as ALL.
+    keys_all = set(json.loads(body)["getReadings"])
+    keys_mixed = set(json.loads(body_mixed)["getReadings"])
+    assert keys_mixed == keys_all, "ALL + tokens must not filter any keys"
+    print(f"  OK: status={status_mixed} keys={len(keys_mixed)} (same as ALL)")
+
     print()
     print("=" * 60)
     print("TEST 2: Raw HTTP - /getConfig without credentials -> 401")

{violet_poolcontroller_api-0.0.38 → violet_poolcontroller_api-0.0.40/violet_poolController_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: violet-poolController-api
-Version: 0.0.38
+Version: 0.0.40
 Summary: Asynchronous Python client for the Violet Pool Controller.
 Author-email: "Basti (Xerolux)" <git@xerolux.de>
 License-Expression: AGPL-3.0-or-later
@@ -20,7 +20,7 @@ Classifier: Topic :: Home Automation
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: aiohttp<3.15,>=3.11.0
+Requires-Dist: aiohttp>=3.11.0
 Provides-Extra: test
 Requires-Dist: aioresponses>=0.7.9; extra == "test"
 Requires-Dist: mypy>=1.15; extra == "test"
@@ -40,7 +40,7 @@ Dynamic: license-file
 
 An asynchronous Python client for interacting with the **Violet Pool Controller**.
 
-This library is primarily designed to power the official [Violet Pool Controller Home Assistant Integration](https://github.com/Xerolux/violet-hass), but it can be used independently for any Python project that needs to fetch readings or control a Violet Pool system.
+This library is primarily designed to power the [Violet Pool Controller Home Assistant Integration](https://github.com/Xerolux/violet-hass), but it can be used independently for any Python project that needs to fetch readings or control a Violet Pool system.
 
 > **📖 Documentation:**
 > - GitHub Pages: https://xerolux.github.io/violet-poolController-api/
@@ -117,7 +117,7 @@ The API client includes many more functions tailored to the Violet Controller:
 - `set_pv_surplus(active=True)`: Enable the PV-Surplus mode.
 - `manual_dosing(dosing_type="Chlor", duration=120)`: Trigger manual chemical dosing.
 
-For a full list of available commands and more detailed examples, please refer to the [Wiki](https://github.com/Xerolux/violet-poolController-api/wiki) or the source code in `api.py`.
+For a full list of available commands and more detailed examples, please refer to the [Wiki](https://github.com/Xerolux/violet-poolController-api/wiki) or the `_api_*.py` mixins, which hold the public methods.
 
 ## Violet Dosing Standalone Mode
 
@@ -136,7 +136,7 @@ api = VioletPoolAPI(
 In this mode, dosing functions (for example `manual_dosing` and dosing parameter/target updates) stay available, while base-module-only switch functions (for example pump/light/backwash) are blocked with a clear error message.
 
 **Note on getReadings format:**
-As of version `0.0.7`, the API client automatically detects and normalizes the payload output from the controller. Whether your Violet Controller returns the classic base-module `dict` structure (`{"PUMPSTATE": "2", "PH": 7.2}`) or the new standalone `list` structure, the `get_readings()` and `get_specific_readings()` functions will always return a seamless, flattened key-value dictionary. Your Home Assistant integration or downstream application will work uniformly with both formats without requiring any extra code!
+As of version `0.0.7`, the API client automatically detects and normalizes the payload output from the controller. Whether your Violet Controller returns the classic base-module `dict` structure (`{"PUMPSTATE": "2", "PH": 7.2}`) or the new standalone `list` structure, the `get_readings()` and `get_specific_readings()` functions always return a flattened key-value view. `get_readings()` returns a `VioletReadings`, a read-only `Mapping` with typed accessors on top; use `dict(readings)` where a plain `dict` is required, for example before JSON serialization. Your Home Assistant integration or downstream application will work uniformly with both formats without requiring any extra code!
 
 **Hardware Profile Detection:**
 As of the latest release, the API client provides a method to detect the specific hardware configuration of your Violet Controller.
@@ -152,7 +152,7 @@ print(profile)
 #     "extension_module_2": False,
 # }
 ```
-This detection parses `get_readings()` to check for the presence of certain internal status parameters (`SYSTEM_dosagemodule_cpu_temperature`, `EXT1_1`, `EXT2_1`), allowing your application to dynamically adapt to the connected modules (Base Module, Dosing Module, Relay Extension 1 and 2). By utilizing this detection, developers and integrations can accurately filter out features for missing hardware, ensuring that only supported options are exposed to the user.
+This detection reads the controller's own module counters (`SYSTEM_dosagemodule_alive_count`, `SYSTEM_ext1module_alive_count`, `SYSTEM_ext2module_alive_count`), allowing your application to dynamically adapt to the connected modules (Base Module, Dosing Module, Relay Extension 1 and 2). By utilizing this detection, developers and integrations can accurately filter out features for missing hardware, ensuring that only supported options are exposed to the user.
 
 ## Mock Server (Testing Without Hardware)
 
@@ -229,7 +229,7 @@ GNU Affero General Public License v3.0 or later (AGPLv3+)
 
 The **VIOLET Pool Controller** by [PoolDigital GmbH & Co. KG](https://www.pooldigital.de/) is a premium smart pool automation system developed in Germany, featuring a JSON API for seamless Home Assistant integration.
 
-- **Offizieller Shop:** [pooldigital.de](https://www.pooldigital.de/)
+- **Official shop:** [pooldigital.de](https://www.pooldigital.de/)
 - **Community:** [PoolDigital Forum](http://forum.pooldigital.de/)
 
 **Disclaimer:**