violet-poolController-api 0.0.27__tar.gz → 0.0.29__tar.gz

{violet_poolcontroller_api-0.0.27/violet_poolController_api.egg-info → violet_poolcontroller_api-0.0.29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: violet-poolController-api
-Version: 0.0.27
+Version: 0.0.29
 Summary: Asynchronous Python client for the Violet Pool Controller.
 Author-email: "Basti (Xerolux)" <git@xerolux.de>
 License: AGPL-3.0-or-later

{violet_poolcontroller_api-0.0.27 → violet_poolcontroller_api-0.0.29}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "violet-poolController-api"
-version = "0.0.27"
+version = "0.0.29"
 authors = [
   { name="Basti (Xerolux)", email="git@xerolux.de" },
 ]

{violet_poolcontroller_api-0.0.27 → violet_poolcontroller_api-0.0.29/violet_poolController_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: violet-poolController-api
-Version: 0.0.27
+Version: 0.0.29
 Summary: Asynchronous Python client for the Violet Pool Controller.
 Author-email: "Basti (Xerolux)" <git@xerolux.de>
 License: AGPL-3.0-or-later

{violet_poolcontroller_api-0.0.27 → violet_poolcontroller_api-0.0.29}/violet_poolController_api.egg-info/SOURCES.txt

@@ -14,5 +14,7 @@ violet_poolcontroller_api/api.py
 violet_poolcontroller_api/circuit_breaker.py
 violet_poolcontroller_api/const_api.py
 violet_poolcontroller_api/const_devices.py
+violet_poolcontroller_api/parsers.py
+violet_poolcontroller_api/readings.py
 violet_poolcontroller_api/utils_rate_limiter.py
 violet_poolcontroller_api/utils_sanitizer.py

{violet_poolcontroller_api-0.0.27 → violet_poolcontroller_api-0.0.29}/violet_poolcontroller_api/__init__.py

@@ -16,7 +16,17 @@
 
 """Violet Pool Controller API client library."""
 
-from .api import VioletPoolAPI, VioletPoolAPIError
+from .api import (
+    SETPOINT_RANGES,
+    VioletAuthError,
+    VioletPayloadError,
+    VioletPoolAPI,
+    VioletPoolAPIError,
+    VioletSetpointError,
+    VioletTimeoutError,
+    VioletUnsafeOperationError,
+    validate_setpoint,
+)
 from .circuit_breaker import CircuitBreaker, CircuitBreakerOpenError
 from .const_api import (  # noqa: F401
     ACTION_ALLAUTO,
@@ -39,25 +49,70 @@ from .const_devices import (  # noqa: F401
     COVER_STATE_MAP,
     DEVICE_PARAMETERS,
     STATE_TRANSLATIONS,
+    CoverState,
+    DmxSceneState,
+    OnewireState,
+    OutputState,
+    PvSurplusState,
+    RuleState,
     VioletState,
     get_state_translation_language,
     set_state_translation_language,
 )
+from .parsers import (  # noqa: F401
+    parse_epoch_milliseconds,
+    parse_epoch_seconds,
+    parse_hms_string,
+    parse_optional_seconds,
+    parse_runtime_string,
+    parse_uptime_string,
+)
+from .readings import VioletReadings
 from .utils_rate_limiter import RateLimiter, get_global_rate_limiter
 from .utils_sanitizer import InputSanitizer
 
 __all__ = [
+    # Core client
     "VioletPoolAPI",
+    # Exception hierarchy
     "VioletPoolAPIError",
+    "VioletAuthError",
+    "VioletTimeoutError",
+    "VioletPayloadError",
+    "VioletSetpointError",
+    "VioletUnsafeOperationError",
+    # Setpoint validation
+    "SETPOINT_RANGES",
+    "validate_setpoint",
+    # Circuit breaker
     "CircuitBreaker",
     "CircuitBreakerOpenError",
+    # Enums
+    "OutputState",
+    "DmxSceneState",
+    "RuleState",
+    "CoverState",
+    "OnewireState",
+    "PvSurplusState",
+    # State helpers
     "VioletState",
+    "STATE_TRANSLATIONS",
+    "get_state_translation_language",
+    "set_state_translation_language",
+    # Typed readings snapshot
+    "VioletReadings",
+    # Parsers
+    "parse_runtime_string",
+    "parse_hms_string",
+    "parse_uptime_string",
+    "parse_epoch_seconds",
+    "parse_epoch_milliseconds",
+    "parse_optional_seconds",
+    # Utilities
     "InputSanitizer",
     "RateLimiter",
     "get_global_rate_limiter",
-    "get_state_translation_language",
-    "set_state_translation_language",
-    "STATE_TRANSLATIONS",
+    # Action constants
     "ACTION_ALLAUTO",
     "ACTION_ALLOFF",
     "ACTION_ALLON",
@@ -68,9 +123,11 @@ __all__ = [
     "ACTION_ON",
     "ACTION_PUSH",
     "ACTION_UNLOCK",
+    # Device constants
     "COVER_FUNCTIONS",
     "COVER_STATE_MAP",
     "DEVICE_PARAMETERS",
+    # Error codes
     "ERROR_CODES",
     "ERROR_SEVERITY_ALARM",
     "ERROR_SEVERITY_INFO",

{violet_poolcontroller_api-0.0.27 → violet_poolcontroller_api-0.0.29}/violet_poolcontroller_api/api.py

@@ -21,6 +21,7 @@ from __future__ import annotations
 import asyncio
 import json
 import logging
+import math
 import re
 import ssl
 from typing import TYPE_CHECKING, Any, cast
@@ -68,7 +69,8 @@ from .const_api import (
     TARGET_ORP,
     TARGET_PH,
 )
-from .const_devices import DEVICE_PARAMETERS
+from .const_devices import COVER_FUNCTIONS, DEVICE_PARAMETERS
+from .readings import VioletReadings
 from .utils_rate_limiter import get_global_rate_limiter
 from .utils_sanitizer import InputSanitizer
 
@@ -81,11 +83,61 @@ _MAX_HOSTNAME_LENGTH = 253
 _HTTP_SERVER_ERROR = 500
 _HTTP_CLIENT_ERROR = 400
 _HTTP_TOO_MANY_REQUESTS = 429
+_HTTP_UNAUTHORIZED = 401
+_HTTP_FORBIDDEN = 403
 _MIN_CALIB_HISTORY_PARTS = 3
 
+# Valid setpoint ranges for each configurable target key (inclusive bounds).
+# Values outside these ranges or non-finite values are rejected before the
+# HTTP call to avoid surprising controller behaviour.
+SETPOINT_RANGES: dict[str, tuple[float, float]] = {
+    TARGET_PH: (6.0, 8.0),
+    TARGET_ORP: (500.0, 900.0),
+    TARGET_MIN_CHLORINE: (0.0, 5.0),
+    "HEATER_set_temp": (5.0, 45.0),
+    "SOLAR_maxtemp": (5.0, 55.0),
+}
+
+
+# =============================================================================
+# Exception hierarchy
+# =============================================================================
+
 
 class VioletPoolAPIError(Exception):
-    """Raised when the Violet Pool Controller API returns an error."""
+    """Base exception for all Violet Pool Controller API errors.
+
+    Callers can catch this base class to handle any API failure, or use
+    the specific subclasses for more targeted error handling.
+    """
+
+
+class VioletAuthError(VioletPoolAPIError):
+    """Raised when the controller rejects credentials (HTTP 401 or 403)."""
+
+
+class VioletTimeoutError(VioletPoolAPIError):
+    """Raised when an HTTP request to the controller exceeds the timeout."""
+
+
+class VioletPayloadError(VioletPoolAPIError):
+    """Raised when the controller returns a malformed or unparseable response."""
+
+
+class VioletSetpointError(VioletPoolAPIError, ValueError):
+    """Raised when a setpoint value is outside its documented valid range.
+
+    Inherits from both ``VioletPoolAPIError`` and ``ValueError`` so callers
+    can catch it as either.
+    """
+
+
+class VioletUnsafeOperationError(VioletPoolAPIError):
+    """Raised for potentially dangerous operations without explicit acknowledgment.
+
+    Pass ``acknowledge_unsafe=True`` to the relevant method to confirm that
+    the caller is aware of the risk (e.g. motorised cover movement).
+    """
 
 
 class _DeterministicClientError(Exception):
@@ -96,9 +148,43 @@ class _DeterministicClientError(Exception):
     circuit breaker failure count: 4xx responses are deterministic
     (bad credentials, unknown endpoint) and must not open the breaker
     that protects against a down controller or network.  It is
-    translated to VioletPoolAPIError before reaching the caller.
+    translated to the appropriate VioletPoolAPIError subclass before
+    reaching the caller.
     """
 
+    def __init__(self, msg: str, *, is_auth: bool = False) -> None:
+        super().__init__(msg)
+        self.is_auth = is_auth
+
+
+def validate_setpoint(field: str, value: float) -> None:
+    """Validate a setpoint value against documented controller ranges.
+
+    Args:
+        field: The configuration key (e.g. ``"DOSAGE_phminus_setpoint"``).
+        value: The numeric value to validate.
+
+    Raises:
+        VioletSetpointError: If ``value`` is non-finite or outside the
+            documented valid range for ``field``.  Fields with no registered
+            range are accepted without range checking.
+    """
+    if not math.isfinite(value):
+        msg = f"Invalid setpoint for '{field}': {value!r} is not a finite number"
+        raise VioletSetpointError(msg)
+
+    bounds = SETPOINT_RANGES.get(field)
+    if bounds is None:
+        return  # No documented range — accept any finite value
+
+    lo, hi = bounds
+    if not lo <= value <= hi:
+        msg = (
+            f"Setpoint '{field}' value {value} is outside the valid range "
+            f"[{lo}, {hi}]"
+        )
+        raise VioletSetpointError(msg)
+
 
 class VioletPoolAPI:
     """A small HTTP client for interacting with the Violet Pool Controller.
@@ -339,7 +425,11 @@ class VioletPoolAPI:
                             # deterministic - fail fast instead of retrying.
                             body = await response.text()
                             msg = f"HTTP {response.status} for {endpoint}: {body.strip()}"
-                            raise _DeterministicClientError(msg)
+                            is_auth = response.status in (
+                                _HTTP_UNAUTHORIZED,
+                                _HTTP_FORBIDDEN,
+                            )
+                            raise _DeterministicClientError(msg, is_auth=is_auth)
 
                         if expect_json:
                             try:
@@ -350,13 +440,25 @@ class VioletPoolAPI:
                             ) as err:
                                 body = await response.text()
                                 msg = f"Invalid JSON payload for {endpoint}: {body.strip()}"
-                                raise VioletPoolAPIError(
-                                    msg,
-                                ) from err
+                                raise VioletPayloadError(msg) from err
 
                         return await response.text()
 
-                except (TimeoutError, aiohttp.ClientError) as err:
+                except (TimeoutError, aiohttp.ServerTimeoutError) as err:
+                    last_error = VioletTimeoutError(
+                        f"Request to {endpoint} timed out: {err}",
+                    )
+                    _LOGGER.debug(
+                        "Attempt %d for %s timed out: %s",
+                        attempt,
+                        endpoint,
+                        err,
+                    )
+                    if attempt == self._max_retries:
+                        raise last_error from None
+                    delay = min(2.0, 0.2 * (2 ** (attempt - 1)))
+                    await asyncio.sleep(delay)
+                except aiohttp.ClientError as err:
                     last_error = VioletPoolAPIError(
                         f"Error communicating with Violet controller: {err}",
                     )
@@ -378,6 +480,8 @@ class VioletPoolAPI:
         try:
             return await self._circuit_breaker.call(_execute_request)
         except _DeterministicClientError as err:
+            if err.is_auth:
+                raise VioletAuthError(str(err)) from err
             raise VioletPoolAPIError(str(err)) from err
         except CircuitBreakerOpenError as err:
             msg = "Circuit breaker is open due to repeated communication failures"
@@ -614,11 +718,17 @@ class VioletPoolAPI:
             readings = {k: v for k, v in readings.items() if not k.startswith("EXT2")}
         return readings
 
-    async def get_readings(self) -> dict[str, Any]:
-        """Return the complete dataset from the controller.
+    async def get_readings(self) -> VioletReadings:
+        """Return the complete dataset from the controller as a typed snapshot.
+
+        The returned :class:`~violet_poolcontroller_api.readings.VioletReadings`
+        object implements :class:`~collections.abc.Mapping`, so all existing
+        code that accesses ``data.get("KEY")`` or ``"KEY" in data`` continues
+        to work unchanged.  Typed properties (``readings.pump``,
+        ``readings.ph``, etc.) are available as an additive convenience.
 
         Returns:
-            A dictionary containing all readings.
+            A :class:`VioletReadings` instance wrapping all readings.
 
         Raises:
             VioletPoolAPIError: If the payload is unexpected.
@@ -629,7 +739,8 @@ class VioletPoolAPI:
             query="ALL",
             payload_name="getReadings",
         )
-        return self._flatten_getreadings_response(response)
+        flat = self._flatten_getreadings_response(response)
+        return VioletReadings(flat)
 
     async def get_hardware_profile(self) -> dict[str, bool]:
         """Detect connected hardware modules from the controller readings.
@@ -647,28 +758,29 @@ class VioletPoolAPI:
             query="ALL",
             payload_name="getReadings",
         )
-        readings = self._flatten_getreadings_response(response)
+        # Use flat dict directly (VioletReadings wrapping not needed here)
+        flat = self._flatten_getreadings_response(response)
 
-        has_base = not self._dosing_standalone and bool(readings)
+        has_base = not self._dosing_standalone and bool(flat)
         return {
             "base_module": has_base,
             "dosing_module": self._dosing_standalone
-            or "SYSTEM_dosagemodule_alive_count" in readings,
-            "extension_module_1": "SYSTEM_ext1module_alive_count" in readings,
-            "extension_module_2": "SYSTEM_ext2module_alive_count" in readings,
+            or "SYSTEM_dosagemodule_alive_count" in flat,
+            "extension_module_1": "SYSTEM_ext1module_alive_count" in flat,
+            "extension_module_2": "SYSTEM_ext2module_alive_count" in flat,
         }
 
     async def get_specific_readings(
         self,
         categories: list[str] | tuple[str, ...],
-    ) -> dict[str, Any]:
-        """Return a reduced dataset for the provided categories.
+    ) -> VioletReadings:
+        """Return a reduced typed snapshot for the provided categories.
 
         Args:
             categories: A list or tuple of category strings to fetch.
 
         Returns:
-            A dictionary containing the requested readings.
+            A :class:`VioletReadings` instance for the requested categories.
 
         Raises:
             VioletPoolAPIError: If no categories are provided
@@ -685,7 +797,7 @@ class VioletPoolAPI:
             query=query,
             payload_name="getReadings",
         )
-        return self._flatten_getreadings_response(response)
+        return VioletReadings(self._flatten_getreadings_response(response))
 
     async def get_history(
         self,
@@ -1164,6 +1276,45 @@ class VioletPoolAPI:
 
         return await self.set_switch_state("DMX_SCENE1", action)
 
+    async def set_cover_command(
+        self,
+        action: str,
+        *,
+        acknowledge_unsafe: bool = False,
+    ) -> dict[str, Any]:
+        """Send an open, close, or stop command to the pool cover.
+
+        Cover movement is a potentially hazardous operation (motorised cover,
+        risk of entrapment).  Callers must explicitly pass
+        ``acknowledge_unsafe=True`` to confirm they are aware of the risk and
+        have taken appropriate safety precautions.
+
+        Args:
+            action: ``"OPEN"``, ``"CLOSE"``, or ``"STOP"`` (case-insensitive).
+            acknowledge_unsafe: Must be ``True`` to allow the command.
+
+        Returns:
+            A dictionary with the command result.
+
+        Raises:
+            VioletUnsafeOperationError: If ``acknowledge_unsafe`` is ``False``.
+            VioletPoolAPIError: If ``action`` is not a known cover action.
+
+        """
+        if not acknowledge_unsafe:
+            msg = (
+                "Cover movement is a potentially unsafe operation. "
+                "Pass acknowledge_unsafe=True to confirm you are aware of the risk."
+            )
+            raise VioletUnsafeOperationError(msg)
+
+        cover_key = COVER_FUNCTIONS.get(action.strip().upper())
+        if not cover_key:
+            msg = f"Unknown cover action '{action}'. Valid: {list(COVER_FUNCTIONS)}"
+            raise VioletPoolAPIError(msg)
+
+        return await self.set_switch_state(cover_key, ACTION_PUSH)
+
     async def set_light_color_pulse(self) -> dict[str, Any]:
         """Trigger the color pulse animation for the pool light.
 
@@ -1215,11 +1366,15 @@ class VioletPoolAPI:
 
         Args:
             climate_key: The climate key (HEATER or SOLAR).
-            temperature: The target temperature.
+            temperature: The target temperature in °C.
 
         Returns:
             A dictionary with the command result.
 
+        Raises:
+            VioletSetpointError: If ``temperature`` is outside the valid range
+                (5–45 °C for heater, 5–55 °C for solar).
+
         """
         config_key = (
             "SOLAR_maxtemp" if climate_key.upper() == "SOLAR" else f"{climate_key}_set_temp"
@@ -1230,41 +1385,60 @@ class VioletPoolAPI:
         """Update the pH setpoint.
 
         Args:
-            value: The new pH target value.
+            value: The new pH target value (valid range: 6.0–8.0).
 
         Returns:
             A dictionary with the command result.
 
+        Raises:
+            VioletSetpointError: If ``value`` is outside the valid range or
+                is not a finite number.
+
         """
+        validate_setpoint(TARGET_PH, float(value))
         return await self.set_target_value(TARGET_PH, float(value))
 
     async def set_orp_target(self, value: int) -> dict[str, Any]:
         """Update the ORP setpoint.
 
         Args:
-            value: The new ORP target value.
+            value: The new ORP target value in mV (valid range: 500–900).
 
         Returns:
             A dictionary with the command result.
 
+        Raises:
+            VioletSetpointError: If ``value`` is outside the valid range or
+                is not a finite number.
+
         """
+        validate_setpoint(TARGET_ORP, float(value))
         return await self.set_target_value(TARGET_ORP, int(value))
 
     async def set_min_chlorine_level(self, value: float) -> dict[str, Any]:
         """Update the minimum chlorine level.
 
         Args:
-            value: The new minimum chlorine level.
+            value: The new minimum chlorine level in mg/L (valid range: 0.0–5.0).
 
         Returns:
             A dictionary with the command result.
 
+        Raises:
+            VioletSetpointError: If ``value`` is outside the valid range or
+                is not a finite number.
+
         """
+        validate_setpoint(TARGET_MIN_CHLORINE, float(value))
         return await self.set_target_value(TARGET_MIN_CHLORINE, float(value))
 
     async def set_target_value(self, key: str, value: float) -> dict[str, Any]:
         """Send a generic target value update to the controller.
 
+        For known setpoint keys (see ``SETPOINT_RANGES``), validation is
+        performed automatically.  Call ``validate_setpoint()`` directly for
+        keys not covered by the convenience methods.
+
         Args:
             key: The target key.
             value: The new value.
@@ -1272,7 +1446,12 @@ class VioletPoolAPI:
         Returns:
             A dictionary with the command result.
 
+        Raises:
+            VioletSetpointError: If ``value`` is non-finite or outside a
+                known valid range for ``key``.
+
         """
+        validate_setpoint(key, float(value))
         return await self.set_config({key: value})
 
     async def set_dosing_parameters(

{violet_poolcontroller_api-0.0.27 → violet_poolcontroller_api-0.0.29}/violet_poolcontroller_api/const_devices.py

@@ -26,8 +26,109 @@ throughout the integration.
 
 from __future__ import annotations
 
+from enum import IntEnum, StrEnum
 from typing import Any, cast
 
+# =============================================================================
+# TYPED ENUMERATIONS
+# =============================================================================
+
+
+class OutputState(IntEnum):
+    """Output state codes returned by getReadings (manual section 26.1).
+
+    These codes apply to ~30 outputs: pump, heater, solar, light, dosing
+    channels, extension relays, etc.  Use the ``is_on``, ``is_manual``, and
+    ``is_emergency`` properties instead of comparing raw integers.
+    """
+
+    AUTO_OFF = 0
+    AUTO_ON = 1
+    AUTO_PRIO_OFF = 2
+    AUTO_PRIO_ON = 3
+    MANUAL_ON = 4
+    EMERGENCY_OFF = 5
+    MANUAL_OFF = 6
+
+    @property
+    def is_on(self) -> bool:
+        """Return True when the output is currently active."""
+        return self in (OutputState.AUTO_ON, OutputState.AUTO_PRIO_ON, OutputState.MANUAL_ON)
+
+    @property
+    def is_manual(self) -> bool:
+        """Return True when the output is in manual (non-auto) mode."""
+        return self in (OutputState.MANUAL_ON, OutputState.MANUAL_OFF)
+
+    @property
+    def is_emergency(self) -> bool:
+        """Return True when an emergency rule is responsible for the state."""
+        return self in (OutputState.AUTO_PRIO_ON, OutputState.EMERGENCY_OFF)
+
+
+class DmxSceneState(IntEnum):
+    """Output state codes for DMX scenes (subset of OutputState values)."""
+
+    AUTO_OFF = 0
+    AUTO_ON = 1
+    MANUAL_ON = 4
+    MANUAL_OFF = 6
+
+    @property
+    def is_on(self) -> bool:
+        """Return True when the DMX scene is active."""
+        return self in (DmxSceneState.AUTO_ON, DmxSceneState.MANUAL_ON)
+
+
+class RuleState(IntEnum):
+    """State codes for digital-input switching rules (DIRULE_*)."""
+
+    INACTIVE = 0
+    ACTIVE = 1
+    BLOCKED_BY_RULE = 5
+    BLOCKED_MANUALLY = 6
+
+
+class CoverState(StrEnum):
+    """Pool cover motion states returned by the COVER_STATE reading."""
+
+    OPEN = "OPEN"
+    CLOSED = "CLOSED"
+    OPENING = "OPENING"
+    CLOSING = "CLOSING"
+    STOPPED = "STOPPED"
+
+
+class OnewireState(StrEnum):
+    """1-wire temperature sensor status values (OW*_state readings).
+
+    Note: The controller uses ``DATA_MISSMATCH`` (double-s) — preserved here
+    for exact string matching against the API response.
+    """
+
+    OK = "OK"
+    CRC_FAULT = "CRC_FAULT"
+    DATA_MISMATCH = "DATA_MISSMATCH"
+    NOT_CONNECTED = "NOT_CONNECTED"
+    NO_SENSOR_CONFIGURED = "NO_SENSOR_CONFIGURED"
+
+
+class PvSurplusState(IntEnum):
+    """PV surplus trigger source states returned by the PVSURPLUS reading.
+
+    Unlike other outputs, PVSURPLUS uses values 0/1/2 instead of the
+    standard 0-6 scheme (manual section 26.3).
+    """
+
+    OFF = 0
+    ON_BY_INPUT = 1
+    ON_BY_HTTP = 2
+
+    @property
+    def is_on(self) -> bool:
+        """Return True when PV surplus mode is active (regardless of source)."""
+        return self in (PvSurplusState.ON_BY_INPUT, PvSurplusState.ON_BY_HTTP)
+
 # =============================================================================
 # COVER CONTROL FUNCTIONS
 # =============================================================================