pyvesync 3.0.0b0__py3-none-any.whl

pyvesync/utils/colors.py

@@ -0,0 +1,248 @@
+"""Data structures for handling colors."""
+
+from __future__ import annotations
+import logging
+from dataclasses import InitVar, dataclass
+
+import colorsys
+from pyvesync.utils.helpers import Validators, NUMERIC_STRICT
+
+_LOGGER = logging.getLogger(__name__)
+
+
+@dataclass
+class RGB:
+    """RGB color space dataclass, for internal use in `utils.colors.Color` dataclass.
+
+    Does not perform any validation, it should not be used directly. Used as an
+    attribute in the :obj:`pyvesync.helpers.Color` dataclass. This should only be
+    used through the :obj:`Color` dataclass with the Color.from_rgb(red, green, blue)
+    classmethod.
+
+    Attributes:
+        red (float): The red component of the RGB color.
+        green (float): The green component of the RGB color.
+        blue (float): The blue component of the RGB color.
+    """
+
+    red: float
+    green: float
+    blue: float
+
+    def __post_init__(self) -> None:
+        """Convert to int."""
+        self.red = int(self.red)
+        self.green = int(self.green)
+        self.blue = int(self.blue)
+
+    def __str__(self) -> str:
+        """Return string representation."""
+        return f"RGB({self.red}, {self.green}, {self.blue})"
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return f"RGB(red={self.red}, green={self.green}, blue={self.blue})"
+
+    def to_tuple(self) -> tuple[float, float, float]:
+        """Return RGB values as tuple."""
+        return self.red, self.green, self.blue
+
+    def to_dict(self) -> dict[str, float]:
+        """Return RGB values as dict."""
+        return {
+            "red": self.red,
+            "green": self.green,
+            "blue": self.blue,
+        }
+
+
+@dataclass
+class HSV:
+    """HSV color space dataclass, for internal use in `utils.colors.Color` dataclass.
+
+    Does not perform any validation and should not be used directly, only
+    by the `Color` dataclass through the Color.from_hsv(hue, saturation, value)
+    classmethod or Color.rgb_to_hsv(red, green, blue) method.
+
+    Attributes:
+        hue (float): The hue component of the color, typically in the range [0, 360).
+        saturation (float): The saturation component of the color,
+            typically in the range [0, 1].
+        value (float): The value (brightness) component of the color,
+            typically in the range [0, 1].
+    """
+    hue: float
+    saturation: float
+    value: float
+
+    def __post_init__(self) -> None:
+        """Convert to int."""
+        self.hue = int(self.hue)
+        self.saturation = int(self.saturation)
+        self.value = int(self.value)
+
+    def __str__(self) -> str:
+        """Return string representation."""
+        return f"HSV({self.hue}, {self.saturation}, {self.value})"
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return f"HSV(hue={self.hue}, saturation={self.saturation}, value={self.value})"
+
+    def to_tuple(self) -> tuple[float, float, float]:
+        """Return HSV values as tuple."""
+        return self.hue, self.saturation, self.value
+
+    def to_dict(self) -> dict[str, float]:
+        """Return HSV values as dict."""
+        return {
+            "hue": self.hue,
+            "saturation": self.saturation,
+            "value": self.value,
+        }
+
+
+@dataclass
+class Color:
+    """Dataclass for color values.
+
+    This class should be instantiated through the `from_rgb` or `from_hsv`
+    classmethods. It will return a `Color` object with the appropriate color
+    values in RGB and HSV.
+
+    Args:
+        color_object (HSV | RGB): Named tuple with color values.
+
+    Attributes:
+        hsv (namedtuple): hue (0-360), saturation (0-100), value (0-100)
+            see [`HSV dataclass`][pyvesync.utils.colors.HSV]
+        rgb (namedtuple): red (0-255), green (0-255), blue (0-255)
+            see [`RGB dataclass`][pyvesync.utils.colors.RGB]
+    """
+    color_object: InitVar[HSV | RGB]
+
+    def __post_init__(
+        self,
+        color_object: HSV | RGB,
+    ) -> None:
+        """Check HSV or RGB Values and create named tuples."""
+        if isinstance(color_object, HSV):
+            self.hsv = color_object
+            self.rgb = self.hsv_to_rgb(*self.hsv.to_tuple())
+        elif isinstance(color_object, RGB):
+            self.rgb = color_object
+            self.hsv = self.rgb_to_hsv(*self.rgb.to_tuple())
+
+    def __str__(self) -> str:
+        """Return string representation."""
+        return f"Color(hsv={self.hsv}, rgb={self.rgb})"
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return f"Color(hsv={self.hsv}, rgb={self.rgb})"
+
+    def as_dict(self) -> dict[str, dict]:
+        """Return color values as dict."""
+        return {
+            "hsv": {
+                "hue": self.hsv.hue,
+                "saturation": self.hsv.saturation,
+                "value": self.hsv.value,
+            },
+            "rgb": {
+                "red": self.rgb.red,
+                "green": self.rgb.green,
+                "blue": self.rgb.blue,
+            },
+        }
+
+    @classmethod
+    def from_rgb(cls, red: NUMERIC_STRICT, green: NUMERIC_STRICT,
+                 blue: NUMERIC_STRICT) -> Color | None:
+        """Create Color instance from RGB values.
+
+        Args:
+            red (NUMERIC_STRICT): The red component of the color,
+                typically in the range [0, 255].
+            green (NUMERIC_STRICT): The green component of the color,
+                typically in the range [0, 255].
+            blue (NUMERIC_STRICT): The blue component of the color,
+                typically in the range [0, 255].
+
+        Returns:
+            Color | None: A Color object with the appropriate color values in RGB and HSV,
+                or None if the input values are invalid.
+        """
+        if not Validators.validate_rgb(red, green, blue):
+            _LOGGER.debug("Invalid RGB values")
+            return None
+        return cls(RGB(float(red), float(green), float(blue)))
+
+    @classmethod
+    def from_hsv(cls, hue: NUMERIC_STRICT, saturation: NUMERIC_STRICT,
+                 value: NUMERIC_STRICT) -> Color | None:
+        """Create Color instance from HSV values.
+
+        Args:
+            hue (NUMERIC_STRICT): The hue component of the color,
+                in the range [0, 360).
+            saturation (NUMERIC_STRICT): The saturation component of the color,
+                typically in the range [0, 1].
+            value (NUMERIC_STRICT): The value (brightness) component of the color,
+                typically in the range [0, 1].
+
+        Returns:
+            Color | None: A Color object with the appropriate color values in RGB and HSV,
+                or None if the input values are invalid.
+        """
+        if not Validators.validate_hsv(hue, saturation, value):
+            _LOGGER.debug("Invalid HSV values")
+            return None
+        return cls(HSV(float(hue), float(saturation), float(value)))
+
+    @staticmethod
+    def hsv_to_rgb(hue: float, saturation: float, value: float) -> RGB:
+        """Convert HSV to RGB.
+
+        Args:
+            hue (float): The hue component of the color, in the range [0, 360).
+            saturation (float): The saturation component of the color,
+                in the range [0, 1].
+            value (float): The value (brightness) component of the color,
+                in the range [0, 1].
+
+        Returns:
+            RGB: An RGB dataclass with red, green, and blue components.
+        """
+        return RGB(
+            *tuple(round(i * 255, 0) for i in colorsys.hsv_to_rgb(
+                hue / 360,
+                saturation / 100,
+                value / 100
+            ))
+        )
+
+    @staticmethod
+    def rgb_to_hsv(red: float, green: float, blue: float) -> HSV:
+        """Convert RGB to HSV.
+
+        Args:
+            red (float): The red component of the color, in the range [0, 255].
+            green (float): The green component of the color, in the range [0, 255].
+            blue (float): The blue component of the color, in the range [0, 255].
+
+        Returns:
+            HSV: An HSV dataclass with hue, saturation, and value components.
+        """
+        hsv_tuple = colorsys.rgb_to_hsv(
+                red / 255,
+                green / 255,
+                blue / 255
+            )
+        hsv_factors = [360, 100, 100]
+
+        return HSV(
+            float(round(hsv_tuple[0] * hsv_factors[0], 2)),
+            float(round(hsv_tuple[1] * hsv_factors[1], 2)),
+            float(round(hsv_tuple[2] * hsv_factors[2], 0)),
+        )

pyvesync/utils/device_mixins.py

@@ -0,0 +1,366 @@
+"""Mixins for Devices that have similar API requests.
+
+The `BypassV2Mixin` and `BypassV1Mixin` classes are used to send API requests to the
+Bypass V2 and Bypass V1 endpoints, respectively. The `BypassV2Mixin` class is used for
+devices that use the `/cloud/v2/deviceManaged/bypassV2` endpoint, while the
+`BypassV1Mixin` class is used for devices that use the
+`/cloud/v1/deviceManaged/{endpoint}` path.
+"""
+
+from __future__ import annotations
+from logging import Logger
+from typing import TYPE_CHECKING, ClassVar, TypeVar
+
+from mashumaro.mixins.orjson import DataClassORJSONMixin
+
+from pyvesync.models.base_models import DefaultValues
+from pyvesync.models.bypass_models import (
+    RequestBypassV2,
+    RequestBypassV1,
+)
+from pyvesync.utils.helpers import Helpers
+from pyvesync.utils.errors import ErrorCodes, ErrorTypes, raise_api_errors
+from pyvesync.utils.logs import LibraryLogger
+from pyvesync.const import ConnectionStatus
+
+if TYPE_CHECKING:
+    from pyvesync import VeSync
+    from pyvesync.utils.errors import ResponseInfo
+    from pyvesync.base_devices import VeSyncBaseDevice
+
+T_MODEL = TypeVar("T_MODEL", bound=DataClassORJSONMixin)
+
+BYPASS_V1_PATH = "/cloud/v1/deviceManaged/"
+BYPASS_V2_BASE = "/cloud/v2/deviceManaged/"
+
+
+def process_bypassv1_result(
+    device: VeSyncBaseDevice,
+    logger: Logger,
+    method: str,
+    resp_dict: dict | None,
+    model: type[T_MODEL]
+) -> T_MODEL | None:
+    """Process the Bypass V1 API response.
+
+    This will gracefully handle errors in the response and error codes,
+    logging them as needed. The return value is the built model.
+
+    Args:
+        device (VeSyncBaseDevice): The device object.
+        logger (Logger): The logger to use for logging.
+        method (str): The method used in the payload.
+        resp_dict (dict | str): The api response.
+        model (type[T_MODEL]): The model to use for the response.
+
+    Returns:
+        dict: The response data
+    """
+    if not isinstance(resp_dict, dict) or 'code' not in resp_dict:
+        LibraryLogger.log_device_api_response_error(
+            logger,
+            device.device_name,
+            device.device_type,
+            method,
+            "Error decoding JSON response",
+        )
+        return None
+
+    error_info = ErrorCodes.get_error_info(resp_dict['code'])
+    device.last_response = error_info
+    device.last_response.response_data = resp_dict
+    if error_info.error_type != ErrorTypes.SUCCESS:
+        _handle_bypass_error(
+            logger, device, method, error_info, resp_dict['code']
+        )
+        return None
+    result = resp_dict.get("result")
+    if not isinstance(result, dict):
+        return None
+    return Helpers.model_maker(logger, model, method, result, device)
+
+
+def _handle_bypass_error(
+    logger: Logger,
+    device: VeSyncBaseDevice,
+    method: str,
+    error_info: ResponseInfo,
+    code: int,
+) -> None:
+    """Process the outer result error code.
+
+    Internal method for handling the error code in the response field
+    used by the `process_bypassv1_result` and `process_bypassv2_result` method.
+
+    Args:
+        logger (Logger): The logger to use for logging.
+        device (VeSyncBaseDevice): The device object.
+        method (str): The method used in the payload.
+        error_info (ResponseInfo): The error info object.
+        code (int): The error code.
+
+    Note:
+        This will raise the appropriate exception based on the error code. See
+        `pyvesync.utils.errors.ErrorCodes` for more information
+        about the error codes and their meanings.
+    """
+    raise_api_errors(error_info)
+    LibraryLogger.log_device_return_code(
+        logger,
+        method,
+        device.device_name,
+        device.product_type,
+        code,
+        error_info.message,
+    )
+    device.state.connection_status = ConnectionStatus.from_bool(
+        error_info.device_online
+        )
+
+
+def _get_inner_result(
+    device: VeSyncBaseDevice,
+    logger: Logger,
+    method: str,
+    resp_dict: dict,
+) -> dict | None:
+    """Process the code in the result field of Bypass V2."""
+    try:
+        outer_result = resp_dict["result"]
+        inner_result = outer_result["result"]
+        code = int(outer_result['code'])
+    except (ValueError, TypeError, KeyError):
+        LibraryLogger.log_device_api_response_error(
+            logger,
+            device.device_name,
+            device.device_type,
+            method,
+            "Error processing bypass V2 API response result.",
+        )
+        return None
+
+    if code != 0:
+        error_info = ErrorCodes.get_error_info(code)
+        error_msg = f"{error_info.message}"
+        if inner_result.get("msg") is not None:
+            error_info.message = f"{error_info.message} - {inner_result['msg']}"
+        LibraryLogger.log_device_return_code(
+            logger,
+            method,
+            device.device_name,
+            device.product_type,
+            code,
+            error_msg,
+        )
+        device.last_response = error_info
+        return None
+    return inner_result
+
+
+def process_bypassv2_result(
+    device: VeSyncBaseDevice,
+    logger: Logger,
+    method: str,
+    resp_dict: dict | None,
+    model: type[T_MODEL]
+) -> T_MODEL | None:
+    """Process the Bypass V1 API response.
+
+    This will gracefully handle errors in the response and error codes,
+    logging them as needed. The return dictionary is the **inner** result value of
+    the API response.
+
+    Args:
+        device (VeSyncBaseDevice): The device object.
+        logger (Logger): The logger to use for logging.
+        method (str): The method used in the payload.
+        resp_dict (dict | str): The api response.
+        model (type[T_MODEL]): The model to use for the response.
+
+    Returns:
+        T_MODEL: An instance of the inner result model.
+    """
+    if not isinstance(resp_dict, dict) or 'code' not in resp_dict:
+        LibraryLogger.log_device_api_response_error(
+            logger,
+            device.device_name,
+            device.device_type,
+            method,
+            "Error decoding JSON response",
+        )
+        return None
+
+    error_info = ErrorCodes.get_error_info(resp_dict['code'])
+    device.last_response = error_info
+    device.last_response.response_data = resp_dict
+    if error_info.error_type != ErrorTypes.SUCCESS:
+        _handle_bypass_error(
+            logger, device, method, error_info, resp_dict['code']
+        )
+        return None
+    result = _get_inner_result(device, logger, method, resp_dict)
+    if not isinstance(result, dict):
+        return None
+    return Helpers.model_maker(logger, model, method, result, device)
+
+
+class BypassV2Mixin:
+    """Mixin for bypass V2 API.
+
+    Overrides the `_build_request` method and `request_keys` attribute for devices
+    that use the Bypass V2 API- /cloud/v2/deviceManaged/bypassV2.
+    """
+    if TYPE_CHECKING:
+        manager: VeSync
+
+    __slots__ = ()
+    request_keys: ClassVar[list[str]] = [
+        "acceptLanguage",
+        "appVersion",
+        "phoneBrand",
+        "phoneOS",
+        "accountID",
+        "cid",
+        "configModule",
+        "debugMode",
+        "traceId",
+        "timeZone",
+        "token",
+        "userCountryCode",
+        "configModel",
+        "deviceId",
+    ]
+
+    def _build_request(
+        self,
+        payload_method: str,
+        data: dict | None = None,
+        method: str = "bypassV2",
+    ) -> RequestBypassV2:
+        """Build API request body Bypass V2 endpoint.
+
+        Args:
+            payload_method (str): The method to use in the payload dict.
+            data (dict | None): The data dict inside the payload value.
+            method (str): The method to use in the outer body, defaults to bypassV2.
+        """
+        body = Helpers.get_class_attributes(DefaultValues, self.request_keys)
+        body.update(Helpers.get_class_attributes(self.manager, self.request_keys))
+        body.update(Helpers.get_class_attributes(self, self.request_keys))
+        body["method"] = method
+        body["payload"] = {"method": payload_method, "source": "APP", "data": data or {}}
+        return RequestBypassV2.from_dict(body)
+
+    async def call_bypassv2_api(
+        self,
+        payload_method: str,
+        data: dict | None = None,
+        method: str = "bypassV2",
+        endpoint: str = "bypassV2",
+    ) -> dict | None:
+        """Send Bypass V2 API request.
+
+        This uses the `_build_request` method to send API requests to the Bypass V2 API.
+
+        Args:
+            payload_method (str): The method to use in the payload dict.
+            data (dict | None): The data to send in the request.
+            method (str): The method to use in the outer body.
+            endpoint (str | None): The last part of the API url, defaults to
+                `bypassV2`, e.g. `/cloud/v2/deviceManaged/bypassV2`.
+
+        Returns:
+            bytes: The response from the API request.
+        """
+        request = self._build_request(payload_method, data, method)
+        endpoint = BYPASS_V2_BASE + endpoint
+        resp_dict, _ = await self.manager.async_call_api(
+            endpoint, "post", request, Helpers.req_header_bypass()
+        )
+        return resp_dict
+
+
+class BypassV1Mixin:
+    """Mixin for bypass V1 API.
+
+    Overrides the `_build_request` method and `request_keys` attribute for devices
+    that use the Bypass V1 API- /cloud/v1/deviceManaged/bypass. The primary method to
+    call is `call_bypassv1_api`, which is a wrapper for setting up the request body and
+    calling the API. The `bypass` endpoint can also be overridden for specific API calls.
+    """
+
+    if TYPE_CHECKING:
+        manager: VeSync
+
+    __slots__ = ()
+    request_keys: ClassVar[list[str]] = [
+        "acceptLanguage",
+        "appVersion",
+        "phoneBrand",
+        "phoneOS",
+        "accountID",
+        "cid",
+        "configModule",
+        "debugMode",
+        "traceId",
+        "timeZone",
+        "token",
+        "userCountryCode",
+        "uuid",
+        "configModel",
+        "deviceId",
+    ]
+
+    def _build_request(
+        self,
+        request_model: type[RequestBypassV1],
+        update_dict: dict | None = None,
+        method: str = "bypass"
+    ) -> RequestBypassV1:
+        """Build API request body for the Bypass V1 endpoint.
+
+        Args:
+            request_model (type[RequestBypassV1]): The request model to use.
+            update_dict (dict | None): Additional keys to add on.
+            method (str): The method to use in the outer body, defaults to bypass.
+
+        Returns:
+            RequestBypassV1: The request body for the Bypass V1 endpoint, the correct
+            model is determined from the RequestBypassV1 discriminator.
+        """
+        body = Helpers.get_class_attributes(DefaultValues, self.request_keys)
+        body.update(Helpers.get_class_attributes(self.manager, self.request_keys))
+        body.update(Helpers.get_class_attributes(self, self.request_keys))
+        body["method"] = method
+        body.update(update_dict or {})
+        return request_model.from_dict(body)
+
+    async def call_bypassv1_api(
+        self,
+        request_model: type[RequestBypassV1],
+        update_dict: dict | None = None,
+        method: str = "bypass",
+        endpoint: str = "bypass",
+    ) -> dict | None:
+        """Send ByPass V1 API request.
+
+        This uses the `_build_request` method to send API requests to the Bypass V1 API.
+        The endpoint can be overridden with the `endpoint` argument.
+
+        Args:
+            request_model (type[RequestBypassV1]): The request model to use.
+            update_dict (dict): Additional keys to add on.
+            method (str): The method to use in the outer body.
+            endpoint (str | None): The last part of the url path, defaults to
+                `bypass`, e.g. `/cloud/v1/deviceManaged/bypass`.
+
+        Returns:
+            bytes: The response from the API request.
+        """
+        request = self._build_request(request_model, update_dict, method)
+        url_path = BYPASS_V1_PATH + endpoint
+        resp_dict, _ = await self.manager.async_call_api(
+            url_path, "post", request, Helpers.req_header_bypass()
+        )
+
+        return resp_dict

pyvesync/utils/enum_utils.py

@@ -0,0 +1,25 @@
+"""Utilities to handle Enums."""
+
+from __future__ import annotations
+import enum
+
+
+class IntEnumMixin(enum.IntEnum):
+    """Mixin class to handle missing enum values.
+
+    Adds __missing__ method using the `extend_enum` function to
+    return a new enum member with the name "UNKNOWN" and the
+    missing value.
+    """
+
+    @classmethod
+    def _missing_(cls: type[enum.IntEnum], value: object) -> enum.IntEnum:
+        """Handle missing enum values by returning member with UNKNOWN name."""
+        for member in cls:
+            if member.value == value:
+                return member
+        unknown_enum_val = int.__new__(cls, value)  # type: ignore[call-overload]
+        unknown_enum_val._name_ = "UNKNOWN"
+        unknown_enum_val._value_ = value  # type: ignore[assignment]
+        unknown_enum_val.__objclass__ = cls.__class__  # type: ignore[assignment]
+        return unknown_enum_val