pyezvizapi 1.0.1.7__py3-none-any.whl → 1.0.1.8__py3-none-any.whl

pyezvizapi/constants.py

@@ -1,4 +1,9 @@
-"""Device switch types relationship."""
+"""Constants and enums used by the Ezviz Cloud API wrapper.
+
+Includes default timeouts, request headers used to emulate the mobile
+client, and a large collection of enums that map integers/strings from
+the Ezviz API to descriptive names.
+"""
 
 from enum import Enum, unique
 

pyezvizapi/exceptions.py

@@ -1,33 +1,33 @@
-"""PyEzviz Exceptions."""
+"""Custom exceptions raised by the Ezviz Cloud API wrapper."""
 
 
 class PyEzvizError(Exception):
-    """Ezviz api exception."""
+    """Base exception for all Ezviz API related errors."""
 
 
 class InvalidURL(PyEzvizError):
-    """Invalid url exception."""
+    """Raised when a request fails due to an invalid URL or proxy settings."""
 
 
 class HTTPError(PyEzvizError):
-    """Invalid host exception."""
+    """Raised when a non-success HTTP status code is returned by the API."""
 
 
 class InvalidHost(PyEzvizError):
-    """Invalid host exception."""
+    """Raised when a hostname/IP is invalid or a TCP connection fails."""
 
 
 class AuthTestResultFailed(PyEzvizError):
-    """Authentication failed."""
+    """Raised by RTSP auth test helpers if credentials are invalid."""
 
 
 class EzvizAuthTokenExpired(PyEzvizError):
-    """Authentication failed because token is invalid or expired."""
+    """Raised when a stored session token is no longer valid (expired/revoked)."""
 
 
 class EzvizAuthVerificationCode(PyEzvizError):
-    """Authentication failed because MFA verification code is required."""
+    """Raised when a login or action requires an MFA (verification) code."""
 
 
 class DeviceException(PyEzvizError):
-    """The device network is abnormal, please check the device network or try again."""
+    """Raised when the physical device reports network or operational issues."""

pyezvizapi/light_bulb.py

@@ -1,4 +1,9 @@
-"""Ezviz camera api."""
+"""Ezviz light bulb API.
+
+Light-bulb specific helpers to read device status and control
+features exposed via the Ezviz cloud API (on/off, brightness,
+color temperature, etc.).
+"""
 
 from __future__ import annotations
 
@@ -11,53 +16,84 @@ from .utils import fetch_nested_value
 
 if TYPE_CHECKING:
     from .client import EzvizClient
+from .models import EzvizDeviceRecord
 
 
 class EzvizLightBulb:
-    """Initialize Ezviz Light Bulb object."""
+    """Representation of an Ezviz light bulb.
+
+    Provides a thin, typed wrapper over the pagelist/device payload
+    for a light bulb, plus convenience methods to toggle and set
+    brightness. This class mirrors the camera interface where
+    possible to keep integration code simple.
+    """
 
     def __init__(
-        self, client: EzvizClient, serial: str, device_obj: dict | None = None
+        self,
+        client: EzvizClient,
+        serial: str,
+        device_obj: EzvizDeviceRecord | dict | None = None,
     ) -> None:
-        """Initialize the light bulb object."""
+        """Initialize the light bulb object.
+
+        Raises:
+            InvalidURL: If the API endpoint/connection is invalid when fetching device info.
+            HTTPError: If the API returns a non-success HTTP status while fetching device info.
+            PyEzvizError: On Ezviz API contract errors or decoding failures.
+        """
         self._client = client
         self._serial = serial
-        self._device = (
-            device_obj if device_obj else self._client.get_device_infos(self._serial)
-        )
+        if device_obj is None:
+            self._device = self._client.get_device_infos(self._serial)
+        elif isinstance(device_obj, EzvizDeviceRecord):
+            self._device = dict(device_obj.raw)
+        else:
+            self._device = device_obj
         self._feature_json = self.get_feature_json()
-        self._switch: dict[int, bool] = {
-            switch["type"]: switch["enable"] for switch in self._device["SWITCH"]
-        }
+        switches = self._device.get("SWITCH") or []
+        self._switch: dict[int, bool] = {}
+        if isinstance(switches, list):
+            for switch in switches:
+                if not isinstance(switch, dict):
+                    continue
+                t = switch.get("type")
+                en = switch.get("enable")
+                if isinstance(t, int) and isinstance(en, (bool, int)):
+                    self._switch[t] = bool(en)
         if DeviceSwitchType.ALARM_LIGHT.value not in self._switch:
             # trying to have same interface as the camera's light
             self._switch[DeviceSwitchType.ALARM_LIGHT.value] = self.get_feature_item(
                 "light_switch"
             )["dataValue"]
 
-    def fetch_key(self, keys: list, default_value: Any = None) -> Any:
-        """Fetch dictionary key."""
+    def fetch_key(self, keys: list[Any], default_value: Any = None) -> Any:
+        """Fetch a nested key from the device payload.
+
+        Uses the same semantics as the camera helper.
+        """
         return fetch_nested_value(self._device, keys, default_value)
 
-    def _local_ip(self) -> Any:
-        """Fix empty ip value for certain cameras."""
-        if (
-            self.fetch_key(["WIFI", "address"])
-            and self._device["WIFI"]["address"] != "0.0.0.0"
-        ):
-            return self._device["WIFI"]["address"]
+    def _local_ip(self) -> str:
+        """Best-effort local IP address for devices that report 0.0.0.0."""
+        wifi = self._device.get("WIFI") or {}
+        addr = wifi.get("address")
+        if isinstance(addr, str) and addr != "0.0.0.0":
+            return addr
 
         # Seems to return none or 0.0.0.0 on some.
-        if (
-            self.fetch_key(["CONNECTION", "localIp"])
-            and self._device["CONNECTION"]["localIp"] != "0.0.0.0"
-        ):
-            return self._device["CONNECTION"]["localIp"]
+        conn = self._device.get("CONNECTION") or {}
+        local_ip = conn.get("localIp")
+        if isinstance(local_ip, str) and local_ip != "0.0.0.0":
+            return local_ip
 
         return "0.0.0.0"
 
     def get_feature_json(self) -> Any:
-        """Parse the FEATURE json."""
+        """Parse the FEATURE JSON string into a Python structure.
+
+        Raises:
+            PyEzvizError: If the FEATURE JSON cannot be decoded.
+        """
         try:
             json_output = json.loads(self._device["FEATURE"]["featureJson"])
 
@@ -67,7 +103,7 @@ class EzvizLightBulb:
         return json_output
 
     def get_feature_item(self, key: str, default_value: Any = None) -> Any:
-        """Get items from FEATURE."""
+        """Return a feature item by key from the parsed FEATURE structure."""
         items = self._feature_json["featureItemDtos"]
 
         for item in items:
@@ -77,11 +113,11 @@ class EzvizLightBulb:
         return default_value if default_value else {"dataValue": ""}
 
     def get_product_id(self) -> Any:
-        """Get product id."""
+        """Return the product ID from the FEATURE metadata."""
         return self._feature_json["productId"]
 
     def status(self) -> dict[Any, Any]:
-        """Return the status of the light bulb."""
+        """Return a status dictionary mirroring the camera status shape where possible."""
         return {
             "serial": self._serial,
             "name": self.fetch_key(["deviceInfos", "name"]),
@@ -118,7 +154,16 @@ class EzvizLightBulb:
         }
 
     def _write_state(self, state: bool | None = None) -> bool:
-        """Set the light bulb state."""
+        """Set the light bulb state.
+
+        If ``state`` is None, the current state will be toggled.
+        Returns True on success.
+
+        Raises:
+            PyEzvizError: On API failures.
+            InvalidURL: If the API endpoint/connection is invalid.
+            HTTPError: If the API returns a non-success HTTP status.
+        """
         item = self.get_feature_item("light_switch")
 
         return self._client.set_device_feature_by_key(
@@ -131,15 +176,19 @@ class EzvizLightBulb:
     def set_brightness(self, value: int) -> bool:
         """Set the light bulb brightness.
 
-        The value must be in range 1-100.
+        The value must be in range 1–100. Returns True on success.
 
+        Raises:
+            PyEzvizError: On API failures.
+            InvalidURL: If the API endpoint/connection is invalid.
+            HTTPError: If the API returns a non-success HTTP status.
         """
         return self._client.set_device_feature_by_key(
             self._serial, self.get_product_id(), value, "brightness"
         )
 
     def toggle_switch(self) -> bool:
-        """Toggle on/off light bulb."""
+        """Toggle the light bulb on/off."""
         return self._write_state()
 
     def power_on(self) -> bool:

pyezvizapi/models.py

@@ -0,0 +1,103 @@
+"""Lightweight models for Ezviz API payloads."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class EzvizDeviceRecord:
+    """A light, ergonomic view over Ezviz get_device_infos() output.
+
+    Captures commonly used fields with a stable API while preserving
+    the full raw mapping for advanced/one-off access.
+    """
+
+    serial: str
+    name: str | None
+    device_category: str | None
+    device_sub_category: str | None
+    version: str | None
+    status: int | None
+
+    # Popular sections (pass-through subsets)
+    support_ext: Mapping[str, Any] | None = None
+    connection: Mapping[str, Any] | None = None
+    wifi: Mapping[str, Any] | None = None
+    qos: Mapping[str, Any] | None = None
+    vtm: Mapping[str, Any] | None = None
+    cloud: Mapping[str, Any] | None = None
+    p2p: Any | None = None
+    time_plan: Any | None = None
+    optionals: Mapping[str, Any] | None = None
+
+    # Switches collapsed to a simple type->enabled map for convenience
+    switches: Mapping[int, bool] = field(default_factory=dict)
+
+    # Full unmodified mapping for anything not yet modeled
+    raw: Mapping[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, serial: str, data: Mapping[str, Any]) -> EzvizDeviceRecord:
+        """Build EzvizDeviceRecord from raw pagelist mapping.
+
+        Tolerates missing or partially shaped keys.
+        """
+        device_infos = data.get("deviceInfos", {}) or {}
+        status = (data.get("STATUS", {}) or {})
+        optionals = status.get("optionals") if isinstance(status, dict) else None
+
+        # Collapse SWITCH list[{type, enable}] to {type: enable}
+        switches_list = data.get("SWITCH") or []
+        switches: dict[int, bool] = {}
+        for item in switches_list if isinstance(switches_list, list) else []:
+            t = item.get("type")
+            en = item.get("enable")
+            if isinstance(t, int) and isinstance(en, (bool, int)):
+                switches[t] = bool(en)
+
+        return cls(
+            serial=serial,
+            name=device_infos.get("name"),
+            device_category=device_infos.get("deviceCategory") or device_infos.get("device_category"),
+            device_sub_category=device_infos.get("deviceSubCategory") or device_infos.get("device_sub_category"),
+            version=device_infos.get("version"),
+            status=device_infos.get("status") or status.get("globalStatus") if isinstance(status, dict) else None,
+            support_ext=device_infos.get("supportExt"),
+            connection=data.get("CONNECTION"),
+            wifi=data.get("WIFI"),
+            qos=data.get("QOS"),
+            vtm=next(iter((data.get("VTM") or {}).values()), None),
+            cloud=next(iter((data.get("CLOUD") or {}).values()), None),
+            p2p=data.get("P2P"),
+            time_plan=data.get("TIME_PLAN"),
+            optionals=optionals if isinstance(optionals, dict) else None,
+            switches=switches,
+            raw=data,
+        )
+
+
+def build_device_records_map(devices: Mapping[str, Any]) -> dict[str, EzvizDeviceRecord]:
+    """Convert get_device_infos() mapping → {serial: EzvizDeviceRecord}.
+
+    Keeps behavior robust to partial/missing keys.
+    """
+    out: dict[str, EzvizDeviceRecord] = {}
+    for serial, payload in (devices or {}).items():
+        try:
+            out[serial] = EzvizDeviceRecord.from_api(serial, payload)
+        except (TypeError, KeyError, ValueError):
+            # Do not crash on unexpected shapes; fall back to raw wrapper
+            out[serial] = EzvizDeviceRecord(
+                serial=serial,
+                name=(payload.get("deviceInfos") or {}).get("name"),
+                device_category=(payload.get("deviceInfos") or {}).get("deviceCategory"),
+                device_sub_category=(payload.get("deviceInfos") or {}).get("deviceSubCategory"),
+                version=(payload.get("deviceInfos") or {}).get("version"),
+                status=(payload.get("deviceInfos") or {}).get("status"),
+                raw=payload,
+                switches={},
+            )
+    return out

pyezvizapi/mqtt.py

@@ -97,10 +97,10 @@ EXT_FIELD_NAMES: Final[tuple[str, ...]] = (
     "status_flag",
     "file_id",
     "is_encrypted",
-    "encrypted_pwd_hash",
+    "picChecksum",
     "unknown_flag",
     "unused5",
-    "alarm_log_id",
+    "msgId",
     "image",
     "device_name",
     "unused6",
@@ -221,6 +221,8 @@ class MQTTClient:
 
         Raises:
           PyEzvizError: If required Ezviz credentials are missing or registration/start fails.
+          InvalidURL: If a push API endpoint is invalid or unreachable.
+          HTTPError: If a push API request returns a non-success status.
         """
         self._register_ezviz_push()
         self._start_ezviz_push()
@@ -258,8 +260,9 @@ class MQTTClient:
         self, client: mqtt.Client, userdata: Any, mid: int, granted_qos: tuple[int, ...]
     ) -> None:
         """Handle subscription acknowledgement from the broker."""
-        _LOGGER.info("Subscribed: mid=%s qos=%s", mid, granted_qos)
-        _LOGGER.info("Subscribed to EZVIZ MQTT topic: %s", self._topic)
+        _LOGGER.debug(
+            "MQTT subscribed: topic=%s mid=%s qos=%s", self._topic, mid, granted_qos
+        )
 
     def _on_connect(
         self, client: mqtt.Client, userdata: Any, flags: dict, rc: int
@@ -277,14 +280,17 @@ class MQTTClient:
         session_present = (
             flags.get("session present") if isinstance(flags, dict) else None
         )
-        _LOGGER.info(
-            "Connected to EZVIZ broker rc=%s session_present=%s", rc, session_present
-        )
+        _LOGGER.debug("MQTT connected: rc=%s session_present=%s", rc, session_present)
         if rc == 0 and not session_present:
             client.subscribe(self._topic, qos=2)
         if rc != 0:
             # Let paho handle reconnects (reconnect_delay_set configured)
-            _LOGGER.error("MQTT connection failed, return code: %s", rc)
+            _LOGGER.error(
+                "MQTT connect failed: serial=%s code=%s msg=%s",
+                "unknown",
+                rc,
+                "connect_failed",
+            )
 
     def _on_disconnect(self, client: mqtt.Client, userdata: Any, rc: int) -> None:
         """Called when the MQTT client disconnects from the broker.
@@ -296,7 +302,12 @@ class MQTTClient:
             userdata (Any): The user data passed to the client (not used).
             rc (int): Disconnect result code. 0 indicates a clean disconnect.
         """
-        _LOGGER.warning("Disconnected from EZVIZ MQTT broker (rc=%s)", rc)
+        _LOGGER.debug(
+            "MQTT disconnected: serial=%s code=%s msg=%s",
+            "unknown",
+            rc,
+            "disconnected",
+        )
 
     def _on_message(
         self, client: mqtt.Client, userdata: Any, msg: mqtt.MQTTMessage
@@ -314,15 +325,30 @@ class MQTTClient:
         try:
             decoded = self.decode_mqtt_message(msg.payload)
         except PyEzvizError as err:
-            _LOGGER.warning("Failed to decode MQTT message: %s", err)
+            _LOGGER.warning("MQTT_decode_error: msg=%s", str(err))
             return
 
-        device_serial = decoded.get("ext", {}).get("device_serial")
+        ext: dict[str, Any] = (
+            decoded.get("ext", {}) if isinstance(decoded.get("ext"), dict) else {}
+        )
+        device_serial = ext.get("device_serial")
+        alert_code = ext.get("alert_type_code")
+        msg_id = ext.get("msgId")
+
         if device_serial:
             self._cache_message(device_serial, decoded)
-            _LOGGER.debug("Stored message for device_serial %s", device_serial)
+            _LOGGER.debug(
+                "mqtt_msg: serial=%s alert_code=%s msg_id=%s",
+                device_serial,
+                alert_code,
+                msg_id,
+            )
         else:
-            _LOGGER.warning("Received message with no device_serial: %s", decoded)
+            _LOGGER.warning(
+                "MQTT_message_missing_serial: alert_code=%s msg_id=%s",
+                alert_code,
+                msg_id,
+            )
 
         if self._on_message_callback:
             try:
@@ -438,7 +464,9 @@ class MQTTClient:
             )
 
         self._mqtt_data["ticket"] = json_output["ticket"]
-        _LOGGER.info("EZVIZ MQTT ticket acquired")
+        _LOGGER.debug(
+            "MQTT ticket acquired: client_id=%s", self._mqtt_data["mqtt_clientid"]
+        )
 
     def _stop_ezviz_push(self) -> None:
         """Stop push notifications for this client via the Ezviz API.