violet-poolController-api 0.0.1__py3-none-any.whl

violet_poolcontroller_api/utils_sanitizer.py

@@ -0,0 +1,488 @@
+
+"""Input Sanitization Utilities für User-Inputs und API-Parameter."""
+from __future__ import annotations
+
+import logging
+import re
+from html import escape
+from typing import Any
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class InputSanitizer:
+    """
+    Input Sanitization für Sicherheit und Datenintegrität.
+
+    Schützt vor:
+    - XSS (Cross-Site Scripting)
+    - SQL Injection (nicht relevant bei HTTP API, aber defensiv)
+    - Command Injection
+    - Path Traversal
+    - Unerwarteten Zeichen
+    """
+
+    # Erlaubte Zeichen-Patterns
+    ALPHANUMERIC = re.compile(r"^[a-zA-Z0-9]+$")
+    ALPHANUMERIC_UNDERSCORE = re.compile(r"^[a-zA-Z0-9_]+$")
+    ALPHANUMERIC_DASH_UNDERSCORE = re.compile(r"^[a-zA-Z0-9_-]+$")
+    NUMERIC = re.compile(r"^-?[0-9]+(\.[0-9]+)?$")
+    INTEGER = re.compile(r"^-?[0-9]+$")
+    FLOAT = re.compile(r"^-?[0-9]+\.[0-9]+$")
+
+    # Gefährliche Patterns
+    DANGEROUS_CHARS = re.compile(r'[<>&"\';\\]')
+    PATH_TRAVERSAL = re.compile(r"\.\.|/|\\")
+    COMMAND_INJECTION = re.compile(r"[;&|`$(){}[\]]")
+
+    @staticmethod
+    def sanitize_string(
+        value: Any,
+        max_length: int = 255,
+        allow_special_chars: bool = False,
+        escape_html: bool = True,
+    ) -> str:
+        """
+        Sanitize einen String-Wert.
+
+        Args:
+            value: Zu sanitisierender Wert
+            max_length: Maximale Länge
+            allow_special_chars: Erlaube Sonderzeichen (sonst nur alphanumerisch)
+            escape_html: HTML-Escape durchführen
+
+        Returns:
+            Sanitisierter String
+
+        Raises:
+            ValueError: Bei ungültigen Eingaben
+        """
+        if value is None:
+            return ""
+
+        # Konvertiere zu String
+        str_value = str(value).strip()
+
+        # Längen-Validierung
+        if len(str_value) > max_length:
+            _LOGGER.warning(
+                "String zu lang (%d > %d), wird gekürzt: %s...",
+                len(str_value),
+                max_length,
+                str_value[:50],
+            )
+            str_value = str_value[:max_length]
+
+        # Wenn keine Sonderzeichen erlaubt sind, entfernen wir sie ZUERST.
+        if not allow_special_chars:
+            # Entferne gefährliche Zeichen
+            original = str_value
+            str_value = re.sub(r"[^a-zA-Z0-9_-]", "", str_value)
+            if str_value != original:
+                _LOGGER.warning(
+                    "Gefährliche Zeichen entfernt: '%s' → '%s'",
+                    original,
+                    str_value,
+                )
+        # HTML-Escape nur wenn Sonderzeichen erlaubt sind
+        # (sonst sind < und > bereits durch Regex entfernt)
+        elif escape_html:
+            str_value = escape(str_value)
+
+        return str_value
+
+    @staticmethod
+    def sanitize_numeric(value: Any) -> float:
+        """
+        Sanitize a numeric value.
+
+        Args:
+            value: Zu sanitisierender numerischer Wert
+
+        Returns:
+            Sanierte Fließkommazahl
+        """
+        try:
+            if isinstance(value, (int, float)):
+                return float(value)
+
+            # Konvertiere String zu Zahl
+            str_value = str(value).strip()
+            # Entferne alle Zeichen außer Zahlen, Minus und Punkt
+            cleaned = re.sub(r"[^0-9.-]", "", str_value)
+
+            if not cleaned:
+                return 0.0
+
+            return float(cleaned)
+        except (ValueError, TypeError):
+            _LOGGER.warning("Ungültiger numerischer Wert: %s", value)
+            return 0.0
+
+    @staticmethod
+    def sanitize_integer(
+        value: Any,
+        min_value: int | None = None,
+        max_value: int | None = None,
+        default: int = 0,
+    ) -> int:
+        """
+        Sanitize einen Integer-Wert.
+
+        Args:
+            value: Zu sanitisierender Wert
+            min_value: Minimaler erlaubter Wert
+            max_value: Maximaler erlaubter Wert
+            default: Default-Wert bei Fehler
+
+        Returns:
+            Sanitisierter Integer
+        """
+        try:
+            int_value = int(float(value))
+
+            # Range-Validierung
+            if min_value is not None and int_value < min_value:
+                _LOGGER.warning(
+                    "Integer-Wert %d < min %d, verwende min",
+                    int_value,
+                    min_value,
+                )
+                return min_value
+
+            if max_value is not None and int_value > max_value:
+                _LOGGER.warning(
+                    "Integer-Wert %d > max %d, verwende max",
+                    int_value,
+                    max_value,
+                )
+                return max_value
+
+            return int_value
+
+        except (ValueError, TypeError) as err:
+            _LOGGER.warning(
+                "Ungültiger Integer-Wert '%s', verwende default %d: %s",
+                value,
+                default,
+                err,
+            )
+            return default
+
+    @staticmethod
+    def sanitize_float(
+        value: Any,
+        min_value: float | None = None,
+        max_value: float | None = None,
+        precision: int = 2,
+        default: float = 0.0,
+    ) -> float:
+        """
+        Sanitize einen Float-Wert.
+
+        Args:
+            value: Zu sanitisierender Wert
+            min_value: Minimaler erlaubter Wert
+            max_value: Maximaler erlaubter Wert
+            precision: Dezimalstellen-Präzision
+            default: Default-Wert bei Fehler
+
+        Returns:
+            Sanitisierter Float
+        """
+        try:
+            float_value = float(value)
+
+            # Range-Validierung
+            if min_value is not None and float_value < min_value:
+                _LOGGER.warning(
+                    "Float-Wert %.2f < min %.2f, verwende min",
+                    float_value,
+                    min_value,
+                )
+                return min_value
+
+            if max_value is not None and float_value > max_value:
+                _LOGGER.warning(
+                    "Float-Wert %.2f > max %.2f, verwende max",
+                    float_value,
+                    max_value,
+                )
+                return max_value
+
+            # Präzision
+            return round(float_value, precision)
+
+        except (ValueError, TypeError) as err:
+            _LOGGER.warning(
+                "Ungültiger Float-Wert '%s', verwende default %.2f: %s",
+                value,
+                default,
+                err,
+            )
+            return default
+
+    @staticmethod
+    def sanitize_boolean(value: Any, default: bool = False) -> bool:
+        """
+        Sanitize einen Boolean-Wert.
+
+        Args:
+            value: Zu sanitisierender Wert
+            default: Default-Wert bei Fehler
+
+        Returns:
+            Sanitisierter Boolean
+        """
+        if isinstance(value, bool):
+            return value
+
+        if isinstance(value, str):
+            lower_value = value.lower().strip()
+            if lower_value in ("true", "1", "yes", "on", "enabled"):
+                return True
+            if lower_value in ("false", "0", "no", "off", "disabled"):
+                return False
+
+        if isinstance(value, (int, float)):
+            return bool(value)
+
+        _LOGGER.warning(
+            "Ungültiger Boolean-Wert '%s', verwende default %s",
+            value,
+            default,
+        )
+        return default
+
+    @staticmethod
+    def validate_device_key(key: str) -> str:
+        """
+        Validiere einen Device-Key (z.B. PUMP, HEATER, etc.).
+
+        Args:
+            key: Device-Key
+
+        Returns:
+            Validierter Key
+
+        Raises:
+            ValueError: Bei ungültigem Key
+        """
+        if not key:
+            raise ValueError("Device-Key darf nicht leer sein")
+
+        # Nur Großbuchstaben, Zahlen und Underscore erlaubt
+        # Wir erlauben auch Bindestriche und konvertieren sie zu Underscores
+        key = key.upper().replace("-", "_")
+        sanitized = re.sub(r"[^A-Z0-9_]", "", key)
+
+        if sanitized != key:
+            _LOGGER.warning(
+                "Device-Key enthielt ungültige Zeichen: '%s' → '%s'",
+                key,
+                sanitized,
+            )
+
+        if len(sanitized) > 50:
+            raise ValueError(f"Device-Key zu lang: {len(sanitized)} > 50")
+
+        return sanitized
+
+    @staticmethod
+    def validate_api_parameter(param: str) -> str:
+        """
+        Validiere einen API-Parameter-Namen.
+
+        Args:
+            param: Parameter-Name
+
+        Returns:
+            Validierter Parameter
+
+        Raises:
+            ValueError: Bei ungültigem Parameter oder Path Traversal
+        """
+        if not param:
+            raise ValueError("API-Parameter darf nicht leer sein")
+
+        # Prüfe auf Path Traversal VOR der Bereinigung
+        if InputSanitizer.PATH_TRAVERSAL.search(param):
+            raise ValueError(f"Path Traversal erkannt in Parameter: {param}")
+
+        # Entferne gefährliche Zeichen
+        sanitized = re.sub(r"[^a-zA-Z0-9_-]", "", param)
+
+        if sanitized != param:
+            _LOGGER.warning(
+                "API-Parameter enthielt ungültige Zeichen: '%s' → '%s'",
+                param,
+                sanitized,
+            )
+
+        if len(sanitized) > 100:
+            raise ValueError(f"API-Parameter zu lang: {len(sanitized)} > 100")
+
+        return sanitized
+
+    @staticmethod
+    def validate_duration(duration: Any, min_sec: int = 0, max_sec: int = 86400) -> int:
+        """
+        Validiere eine Duration in Sekunden.
+
+        Args:
+            duration: Duration-Wert
+            min_sec: Minimale Duration (Standard: 0)
+            max_sec: Maximale Duration (Standard: 24h)
+
+        Returns:
+            Validierte Duration in Sekunden
+        """
+        duration_int = InputSanitizer.sanitize_integer(
+            duration,
+            min_value=min_sec,
+            max_value=max_sec,
+            default=0,
+        )
+
+        if duration_int < 0:
+            _LOGGER.warning("Negative Duration %d, setze auf 0", duration_int)
+            return 0
+
+        return duration_int
+
+    @staticmethod
+    def validate_speed(
+        speed: Any, min_speed: int = 1, max_speed: int = 4, default: int = 2
+    ) -> int:
+        """
+        Validiere einen Speed-Wert (z.B. Pumpengeschwindigkeit).
+
+        Args:
+            speed: Speed-Wert
+            min_speed: Minimale Speed (Standard: 1)
+            max_speed: Maximale Speed (Standard: 4)
+            default: Default Speed (Standard: 2)
+
+        Returns:
+            Validierte Speed
+        """
+        return InputSanitizer.sanitize_integer(
+            speed,
+            min_value=min_speed,
+            max_value=max_speed,
+            default=default,
+        )
+
+    @staticmethod
+    def validate_temperature(
+        temp: Any,
+        min_temp: float = -50.0,
+        max_temp: float = 100.0,
+    ) -> float:
+        """
+        Validiere einen Temperatur-Wert.
+
+        Args:
+            temp: Temperatur-Wert
+            min_temp: Minimale Temperatur
+            max_temp: Maximale Temperatur
+
+        Returns:
+            Validierte Temperatur
+        """
+        return InputSanitizer.sanitize_float(
+            temp,
+            min_value=min_temp,
+            max_value=max_temp,
+            precision=1,
+            default=20.0,
+        )
+
+    @staticmethod
+    def validate_ph_value(ph: Any) -> float:
+        """
+        Validiere einen pH-Wert.
+
+        Args:
+            ph: pH-Wert
+
+        Returns:
+            Validierter pH-Wert (6.0-9.0)
+        """
+        return InputSanitizer.sanitize_float(
+            ph,
+            min_value=6.0,
+            max_value=9.0,
+            precision=1,
+            default=7.2,
+        )
+
+    @staticmethod
+    def validate_orp_value(orp: Any) -> int:
+        """
+        Validiere einen ORP-Wert (Redoxpotential).
+
+        Args:
+            orp: ORP-Wert in mV
+
+        Returns:
+            Validierter ORP-Wert (400-900 mV)
+        """
+        return InputSanitizer.sanitize_integer(
+            orp,
+            min_value=400,
+            max_value=900,
+            default=700,
+        )
+
+    @staticmethod
+    def validate_chlorine_level(chlorine: Any) -> float:
+        """
+        Validiere einen Chlor-Wert.
+
+        Args:
+            chlorine: Chlor-Wert in mg/l
+
+        Returns:
+            Validierter Chlor-Wert (0.0-5.0 mg/l)
+        """
+        return InputSanitizer.sanitize_float(
+            chlorine,
+            min_value=0.0,
+            max_value=5.0,
+            precision=1,
+            default=0.6,
+        )
+
+
+# Singleton-Instanz für einfachen Zugriff
+_sanitizer = InputSanitizer()
+
+
+def sanitize_string(*args, **kwargs) -> str:
+    """Shortcut für InputSanitizer.sanitize_string()."""
+    return _sanitizer.sanitize_string(*args, **kwargs)
+
+
+def sanitize_integer(*args, **kwargs) -> int:
+    """Shortcut für InputSanitizer.sanitize_integer()."""
+    return _sanitizer.sanitize_integer(*args, **kwargs)
+
+
+def sanitize_float(*args, **kwargs) -> float:
+    """Shortcut für InputSanitizer.sanitize_float()."""
+    return _sanitizer.sanitize_float(*args, **kwargs)
+
+
+def sanitize_boolean(*args, **kwargs) -> bool:
+    """Shortcut für InputSanitizer.sanitize_boolean()."""
+    return _sanitizer.sanitize_boolean(*args, **kwargs)
+
+
+__all__ = [
+    "InputSanitizer",
+    "sanitize_string",
+    "sanitize_integer",
+    "sanitize_float",
+    "sanitize_boolean",
+]

violet_poolcontroller_api-0.0.1.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: violet-poolController-api
+Version: 0.0.1
+Summary: Asynchronous Python client for the Violet Pool Controller.
+Home-page: https://github.com/Xerolux/violet-poolController-api
+Author: Basti (Xerolux)
+Author-email: "Basti (Xerolux)" <git@xerolux.de>
+Project-URL: Homepage, https://github.com/Xerolux/violet-poolController-api
+Project-URL: Bug Tracker, https://github.com/Xerolux/violet-poolController-api/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9.0
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# Violet Pool Controller API
+
+[![PyPI version](https://img.shields.io/pypi/v/violet-poolController-api.svg?style=for-the-badge)](https://pypi.org/project/violet-poolController-api/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/violet-poolController-api.svg?style=for-the-badge)](https://pypistats.org/packages/violet-poolcontroller-api)
+[![Python versions](https://img.shields.io/pypi/pyversions/violet-poolController-api.svg?style=for-the-badge)](https://pypi.org/project/violet-poolController-api/)
+[![License](https://img.shields.io/github/license/Xerolux/violet-poolController-api.svg?style=for-the-badge)](LICENSE)
+
+[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-xerolux-yellow?logo=buy-me-a-coffee&style=for-the-badge)](https://www.buymeacoffee.com/xerolux)
+[![Tesla](https://img.shields.io/badge/Tesla-Referral-red?style=for-the-badge&logo=tesla)](https://ts.la/sebastian564489)
+
+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.
+
+## Features
+* **Asynchronous:** Fully async operations using `aiohttp`.
+* **Resilient:** Built-in Circuit Breaker and Rate Limiter to protect both the client and the controller from overload.
+* **Sanitization:** Strict payload input sanitization to prevent injection and invalid settings.
+
+## Installation
+
+```bash
+pip install violet-poolController-api
+```
+
+## Basic Usage
+
+```python
+import asyncio
+import aiohttp
+from violet_poolcontroller_api.api import VioletPoolAPI, VioletPoolAPIError
+
+async def main():
+    # Create an aiohttp ClientSession
+    async with aiohttp.ClientSession() as session:
+        # Initialize the API
+        api = VioletPoolAPI(
+            host="192.168.1.100",
+            username="admin",
+            password="your_password",
+            session=session
+        )
+
+        try:
+            # --- 1. Fetch current sensor readings ---
+            readings = await api.get_readings()
+            print("Current Pool Readings:")
+            print(readings)
+
+            # --- 2. Control the Filter Pump ---
+            # Set pump speed to 2 (Normal) permanently (duration=0)
+            await api.set_pump_speed(speed=2, duration=0)
+            print("\nPump speed set to 2.")
+
+            # --- 3. Set Target Temperature ---
+            # Set the target temperature for the heater to 28.5 degrees
+            await api.set_device_temperature("HEATER", 28.5)
+            print("\nHeater target temperature set to 28.5°C.")
+
+            # --- 4. Control Pool Lights ---
+            # Trigger the color pulse animation for the pool light
+            await api.set_light_color_pulse()
+            print("\nLight color pulse triggered.")
+
+        except VioletPoolAPIError as e:
+            print(f"An error occurred while communicating with the Violet controller: {e}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Advanced Operations
+
+The API client includes many more functions tailored to the Violet Controller:
+- `get_config(["PUMP_SPEED_1", "PUMP_SPEED_2"])`: Fetch specific configuration values.
+- `set_ph_target(7.2)`: Change the pH target value.
+- `set_orp_target(750)`: Change the ORP (Redox) target value.
+- `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, please refer to the source code in `api.py`.
+
+## License
+MIT License
+
+---
+
+## About the Violet Pool Controller
+
+Der **VIOLET Pool Controller** von [PoolDigital GmbH & Co. KG](https://www.pooldigital.de/) ist ein Premium Smart Pool Automation System aus deutscher Entwicklung – mit JSON API für nahtlose Home Assistant Integration.
+
+- **Offizieller Shop:** [pooldigital.de](https://www.pooldigital.de/)
+- **Community:** [PoolDigital Forum](http://forum.pooldigital.de/)
+
+**Disclaimer:**
+*This is an unofficial, community-driven project. It is not affiliated with, endorsed by, or associated with PoolDigital GmbH & Co. KG in any way. "VIOLET" and any related trademarks are the property of their respective owners.*
+
+⚠️ **WARNING - USE AT YOUR OWN RISK:**
+*This software interacts with physical hardware and automation systems that control water chemistry (pH, Chlorine/ORP) and electrical equipment (pumps, heaters). A bug, network issue, or incorrect configuration could result in hardware damage, unsafe water conditions, or other hazards. By using this software, you acknowledge and agree that you are solely responsible for any damage, injury, or loss of property that may occur. Please always monitor your pool's chemistry and hardware independently.*

violet_poolcontroller_api-0.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+violet_poolcontroller_api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+violet_poolcontroller_api/api.py,sha256=LwzvBE3nfkJcmJfU3GZO_qJCufy3ReV2R1PKfpCznkA,31423
+violet_poolcontroller_api/circuit_breaker.py,sha256=FZWzDMHJSS_uLibXnPxyLo2bTkGrWezwfJkE1tzzlEc,5994
+violet_poolcontroller_api/const_api.py,sha256=GEVXbxD41-8gHkx1LGzUbnd-huKYJX0m1ZqfH3sfF08,4209
+violet_poolcontroller_api/const_devices.py,sha256=J-a8Y9td9NGKac-xxkzhcQrOoeU7idXjXE60G0W7_tM,10162
+violet_poolcontroller_api/utils_rate_limiter.py,sha256=GcPG1fVXBiU0GUZ3sUjFEzFSwuJEXlH_vAMx65uFJqU,7805
+violet_poolcontroller_api/utils_sanitizer.py,sha256=-_PsBAgeJUgs6NqS9usr2VrePYlDcSz34c2cQqyKtdw,13431
+violet_poolcontroller_api-0.0.1.dist-info/licenses/LICENSE,sha256=4TCuq5DDi4BfoOjXzxmnrAt4udsH5qeX5-jpLcsJ3jw,1072
+violet_poolcontroller_api-0.0.1.dist-info/METADATA,sha256=KT6XzXcLqk6UujW4q5dYqQyP2CxU4W2n4vmKgvLMfa0,5739
+violet_poolcontroller_api-0.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+violet_poolcontroller_api-0.0.1.dist-info/top_level.txt,sha256=CJIVuLVLzANlKYdPaogpTbmEkaJ9IGqgk-WHWEkOlIg,26
+violet_poolcontroller_api-0.0.1.dist-info/RECORD,,

violet_poolcontroller_api-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

violet_poolcontroller_api-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Basti (Xerolux)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

violet_poolcontroller_api-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+violet_poolcontroller_api