wyzeapy 0.5.27__py3-none-any.whl → 0.5.29__py3-none-any.whl

wyzeapy/services/sensor_service.py

@@ -31,9 +31,9 @@ class SensorService(BaseService):
             sensor.device_params = await self.get_updated_params(sensor.mac)
         properties = await self._get_device_info(sensor)
 
-        for property in properties['data']['property_list']:
-            pid = property['pid']
-            value = property['value']
+        for property in properties["data"]["property_list"]:
+            pid = property["pid"]
+            value = property["value"]
 
             try:
                 if PropertyIDs(pid) == PropertyIDs.CONTACT_STATE:
@@ -45,26 +45,44 @@ class SensorService(BaseService):
 
         return sensor
 
-    async def register_for_updates(self, sensor: Sensor, callback: Callable[[Sensor], None]):
+    async def register_for_updates(
+        self, sensor: Sensor, callback: Callable[[Sensor], None]
+    ):
         _LOGGER.debug(f"Registering sensor: {sensor.nickname} for updates")
         loop = asyncio.get_event_loop()
         if not self._updater_thread:
-            self._updater_thread = Thread(target=self.update_worker, args=[loop, ], daemon=True)
+            self._updater_thread = Thread(
+                target=self.update_worker,
+                args=[
+                    loop,
+                ],
+                daemon=True,
+            )
             self._updater_thread.start()
 
         self._subscribers.append((sensor, callback))
 
     async def deregister_for_updates(self, sensor: Sensor):
-        self._subscribers = [(sense, callback) for sense, callback in self._subscribers if sense.mac != sensor.mac]
+        self._subscribers = [
+            (sense, callback)
+            for sense, callback in self._subscribers
+            if sense.mac != sensor.mac
+        ]
 
     def update_worker(self, loop):
         while True:
             for sensor, callback in self._subscribers:
                 _LOGGER.debug(f"Providing update for {sensor.nickname}")
                 try:
-                    callback(asyncio.run_coroutine_threadsafe(self.update(sensor), loop).result())
+                    callback(
+                        asyncio.run_coroutine_threadsafe(
+                            self.update(sensor), loop
+                        ).result()
+                    )
                 except UnknownApiError as e:
-                    _LOGGER.warning(f"The update method detected an UnknownApiError: {e}")
+                    _LOGGER.warning(
+                        f"The update method detected an UnknownApiError: {e}"
+                    )
                 except ClientOSError as e:
                     _LOGGER.error(f"A network error was detected: {e}")
                 except ContentTypeError as e:
@@ -74,7 +92,10 @@ class SensorService(BaseService):
         if self._devices is None:
             self._devices = await self.get_object_list()
 
-        sensors = [Sensor(device.raw_dict) for device in self._devices if
-                   device.type is DeviceTypes.MOTION_SENSOR or
-                   device.type is DeviceTypes.CONTACT_SENSOR]
+        sensors = [
+            Sensor(device.raw_dict)
+            for device in self._devices
+            if device.type is DeviceTypes.MOTION_SENSOR
+            or device.type is DeviceTypes.CONTACT_SENSOR
+        ]
         return [Sensor(sensor.raw_dict) for sensor in sensors]

wyzeapy/services/switch_service.py

@@ -36,8 +36,12 @@ class SwitchService(BaseService):
         if self._devices is None:
             self._devices = await self.get_object_list()
 
-        devices = [device for device in self._devices if device.type is DeviceTypes.PLUG or
-                   device.type is DeviceTypes.OUTDOOR_PLUG]
+        devices = [
+            device
+            for device in self._devices
+            if device.type is DeviceTypes.PLUG
+            or device.type is DeviceTypes.OUTDOOR_PLUG
+        ]
         return [Switch(switch.raw_dict) for switch in devices]
 
     async def turn_on(self, switch: Switch):

wyzeapy/services/thermostat_service.py

@@ -37,9 +37,9 @@ class Preset(Enum):
 
 
 class HVACState(Enum):
-    COOLING = 'cooling'
-    HEATING = 'heating'
-    IDLE = 'idle'
+    COOLING = "cooling"
+    HEATING = "heating"
+    IDLE = "idle"
 
 
 class Thermostat(Device):
@@ -60,7 +60,7 @@ class Thermostat(Device):
 
 class ThermostatService(BaseService):
     async def update(self, thermostat: Thermostat) -> Thermostat:
-        properties = (await self._thermostat_get_iot_prop(thermostat))['data']['props']
+        properties = (await self._thermostat_get_iot_prop(thermostat))["data"]["props"]
 
         device_props = []
         for property in properties:
@@ -87,7 +87,7 @@ class ThermostatService(BaseService):
             elif prop == ThermostatProps.TEMPERATURE:
                 thermostat.temperature = float(value)
             elif prop == ThermostatProps.IOT_STATE:
-                thermostat.available = value == 'connected'
+                thermostat.available = value == "connected"
             elif prop == ThermostatProps.HUMIDITY:
                 thermostat.humidity = int(value)
             elif prop == ThermostatProps.WORKING_STATE:
@@ -99,7 +99,9 @@ class ThermostatService(BaseService):
         if self._devices is None:
             self._devices = await self.get_object_list()
 
-        thermostats = [device for device in self._devices if device.type is DeviceTypes.THERMOSTAT]
+        thermostats = [
+            device for device in self._devices if device.type is DeviceTypes.THERMOSTAT
+        ]
 
         return [Thermostat(thermostat.raw_dict) for thermostat in thermostats]
 
@@ -110,22 +112,34 @@ class ThermostatService(BaseService):
         await self._thermostat_set_iot_prop(thermostat, ThermostatProps.HEAT_SP, temp)
 
     async def set_hvac_mode(self, thermostat: Device, hvac_mode: HVACMode):
-        await self._thermostat_set_iot_prop(thermostat, ThermostatProps.MODE_SYS, hvac_mode.value)
+        await self._thermostat_set_iot_prop(
+            thermostat, ThermostatProps.MODE_SYS, hvac_mode.value
+        )
 
     async def set_fan_mode(self, thermostat: Device, fan_mode: FanMode):
-        await self._thermostat_set_iot_prop(thermostat, ThermostatProps.FAN_MODE, fan_mode.value)
+        await self._thermostat_set_iot_prop(
+            thermostat, ThermostatProps.FAN_MODE, fan_mode.value
+        )
 
     async def set_preset(self, thermostat: Thermostat, preset: Preset):
-        await self._thermostat_set_iot_prop(thermostat, ThermostatProps.CURRENT_SCENARIO, preset.value)
+        await self._thermostat_set_iot_prop(
+            thermostat, ThermostatProps.CURRENT_SCENARIO, preset.value
+        )
 
     async def _thermostat_get_iot_prop(self, device: Device) -> Dict[Any, Any]:
         url = "https://wyze-earth-service.wyzecam.com/plugin/earth/get_iot_prop"
-        keys = 'trigger_off_val,emheat,temperature,humidity,time2temp_val,protect_time,mode_sys,heat_sp,cool_sp,' \
-                'current_scenario,config_scenario,temp_unit,fan_mode,iot_state,w_city_id,w_lat,w_lon,working_state,' \
-                'dev_hold,dev_holdtime,asw_hold,app_version,setup_state,wiring_logic_id,save_comfort_balance,' \
-                'kid_lock,calibrate_humidity,calibrate_temperature,fancirc_time,query_schedule'
+        keys = (
+            "trigger_off_val,emheat,temperature,humidity,time2temp_val,protect_time,mode_sys,heat_sp,cool_sp,"
+            "current_scenario,config_scenario,temp_unit,fan_mode,iot_state,w_city_id,w_lat,w_lon,working_state,"
+            "dev_hold,dev_holdtime,asw_hold,app_version,setup_state,wiring_logic_id,save_comfort_balance,"
+            "kid_lock,calibrate_humidity,calibrate_temperature,fancirc_time,query_schedule"
+        )
         return await self._get_iot_prop(url, device, keys)
 
-    async def _thermostat_set_iot_prop(self, device: Device, prop: ThermostatProps, value: Any) -> None:
-        url = "https://wyze-earth-service.wyzecam.com/plugin/earth/set_iot_prop_by_topic"
+    async def _thermostat_set_iot_prop(
+        self, device: Device, prop: ThermostatProps, value: Any
+    ) -> None:
+        url = (
+            "https://wyze-earth-service.wyzecam.com/plugin/earth/set_iot_prop_by_topic"
+        )
         return await self._set_iot_prop(url, device, prop.value, value)

wyzeapy/services/update_manager.py

@@ -7,17 +7,34 @@ from ..types import Device
 import logging
 import threading
 
+"""
+Asynchronous device update scheduling and management.
+
+This module provides classes to schedule and execute periodic updates of
+Wyze devices, ensuring rate limits and fair distribution of update calls.
+"""
+
 _LOGGER = logging.getLogger(__name__)
 
 INTERVAL = 300
 MAX_SLOTS = 225
 
+
 @dataclass(order=True)
 class DeviceUpdater(object):
-    device: Device=field(compare=False)  # The device that will be updated
-    service: Any=field(compare=False)
-    update_in: int # A countdown to zero that will tell the priority queue that it is time to update this device
-    updates_per_interval: int=field(compare=False) # The number of updates that should happen every 5 minutes
+    """Represents a scheduled update task for a single device.
+
+    Attributes:
+        service: The service instance responsible for updating the device.
+        device: The Device object to be updated.
+        update_in: Countdown ticks until the next update is due.
+        updates_per_interval: Number of updates allowed per INTERVAL.
+    """
+
+    device: Device = field(compare=False)
+    service: Any = field(compare=False)
+    update_in: int  # Countdown ticks until this device should be updated
+    updates_per_interval: int = field(compare=False)
 
     def __init__(self, service, device: Device, update_interval: int):
         """
@@ -42,7 +59,7 @@ class DeviceUpdater(object):
                 self.device = await self.service.update(self.device)
                 # Callback to provide the updated info to the subscriber
                 self.device.callback_function(self.device)
-            except:
+            except Exception:
                 _LOGGER.exception("Unknown error happened during updating device info")
             finally:
                 # Release the mutex after the async call
@@ -63,11 +80,17 @@ class DeviceUpdater(object):
         if self.updates_per_interval > 1:
             self.updates_per_interval -= 1
 
+
 class UpdateManager:
-    # Holds all the logic for when to update the devices
+    """Manager for scheduling and executing periodic device updates.
+
+    Maintains a priority queue of DeviceUpdater instances and enforces rate
+    limits and fair distribution of update calls across devices.
+    """
+
     updaters = []
     removed_updaters = []
-    mutex = threading.Lock()  # Create a lock object as a class variable
+    mutex = threading.Lock()
 
     def check_if_removed(self, updater: DeviceUpdater):
         for item in self.removed_updaters:
@@ -78,7 +101,7 @@ class UpdateManager:
     # This function should be called once every second
     async def update_next(self):
         # If there are no updaters in the queue we don't need to do anything
-        if (len(self.updaters) == 0):
+        if len(self.updaters) == 0:
             _LOGGER.debug("No devices to update in queue")
             return
         while True:
@@ -92,12 +115,13 @@ class UpdateManager:
             # We then reduce the counter for all the other updaters
             self.tick_tock()
             # Then we update the target device
-            await updater.update(self.mutex) # It will only update if it is time for it to update. Otherwise it just reduces its update_in counter.
+            await updater.update(
+                self.mutex
+            )  # It will only update if it is time for it to update. Otherwise it just reduces its update_in counter.
             # Then we put it back at the end of the queue. Or the front again if it wasn't ready to update
             heappush(self.updaters, updater)
             await sleep(1)
 
-
     def filled_slots(self):
         # This just returns the number of available slots
         current_slots = 0
@@ -123,7 +147,10 @@ class UpdateManager:
 
         # When we add a new updater it has to fit within the max slots or we will not add it
         while (self.filled_slots() + updater.updates_per_interval) > MAX_SLOTS:
-            _LOGGER.debug("Reducing updates per interval to fit new device as slots are full: %s", self.filled_slots())
+            _LOGGER.debug(
+                "Reducing updates per interval to fit new device as slots are full: %s",
+                self.filled_slots(),
+            )
             # If we are overflowing the available slots we will reduce the frequency of updates evenly for all devices until we can fit in one more.
             self.decrease_updates_per_interval()
             updater.delay()

wyzeapy/services/wall_switch_service.py

@@ -41,7 +41,7 @@ class WallSwitch(Device):
 
 class WallSwitchService(BaseService):
     async def update(self, switch: WallSwitch) -> WallSwitch:
-        properties = (await self._wall_switch_get_iot_prop(switch))['data']['props']
+        properties = (await self._wall_switch_get_iot_prop(switch))["data"]["props"]
 
         device_props = []
         for prop_key, prop_value in properties.items():
@@ -67,9 +67,11 @@ class WallSwitchService(BaseService):
         if self._devices is None:
             self._devices = await self.get_object_list()
 
-        switches = [device for device in self._devices
-                    if device.type is DeviceTypes.COMMON 
-                    and device.product_model == "LD_SS1"]
+        switches = [
+            device
+            for device in self._devices
+            if device.type is DeviceTypes.COMMON and device.product_model == "LD_SS1"
+        ]
 
         return [WallSwitch(switch.raw_dict) for switch in switches]
 
@@ -89,7 +91,9 @@ class WallSwitchService(BaseService):
         await self._wall_switch_set_iot_prop(switch, WallSwitchProps.SWITCH_POWER, True)
 
     async def power_off(self, switch: WallSwitch):
-        await self._wall_switch_set_iot_prop(switch, WallSwitchProps.SWITCH_POWER, False)
+        await self._wall_switch_set_iot_prop(
+            switch, WallSwitchProps.SWITCH_POWER, False
+        )
 
     async def iot_on(self, switch: WallSwitch):
         await self._wall_switch_set_iot_prop(switch, WallSwitchProps.SWITCH_IOT, True)
@@ -97,14 +101,20 @@ class WallSwitchService(BaseService):
     async def iot_off(self, switch: WallSwitch):
         await self._wall_switch_set_iot_prop(switch, WallSwitchProps.SWITCH_IOT, False)
 
-    async def set_single_press_type(self, switch: WallSwitch, single_press_type: SinglePressType):
-        await self._wall_switch_set_iot_prop(switch, WallSwitchProps.SINGLE_PRESS_TYPE, single_press_type.value)
+    async def set_single_press_type(
+        self, switch: WallSwitch, single_press_type: SinglePressType
+    ):
+        await self._wall_switch_set_iot_prop(
+            switch, WallSwitchProps.SINGLE_PRESS_TYPE, single_press_type.value
+        )
 
     async def _wall_switch_get_iot_prop(self, device: Device) -> Dict[Any, Any]:
         url = "https://wyze-sirius-service.wyzecam.com//plugin/sirius/get_iot_prop"
         keys = "iot_state,switch-power,switch-iot,single_press_type"
         return await self._get_iot_prop(url, device, keys)
 
-    async def _wall_switch_set_iot_prop(self, device: Device, prop: WallSwitchProps, value: Any) -> None:
+    async def _wall_switch_set_iot_prop(
+        self, device: Device, prop: WallSwitchProps, value: Any
+    ) -> None:
         url = "https://wyze-sirius-service.wyzecam.com//plugin/sirius/set_iot_prop_by_topic"
         return await self._set_iot_prop(url, device, prop.value, value)

wyzeapy/types.py

@@ -3,6 +3,11 @@
 #  of the attached license. You should have received a copy of
 #  the license with this file. If not, please write to:
 #  katie@mulliken.net to receive a copy
+"""
+Type definitions and data models for Wyzeapy library, including devices, events,
+and API response code enums.
+"""
+
 from enum import Enum
 from typing import Union, List, Dict, Any
 
@@ -79,15 +84,17 @@ class Sensor(Device):
     @property
     def activity_detected(self) -> int:
         if self.type is DeviceTypes.CONTACT_SENSOR:
-            return int(self.device_params['open_close_state'])
+            return int(self.device_params["open_close_state"])
         elif self.type is DeviceTypes.MOTION_SENSOR:
-            return int(self.device_params['motion_state'])
+            return int(self.device_params["motion_state"])
         else:
-            raise AssertionError("Device must be of type CONTACT_SENSOR or MOTION_SENSOR")
+            raise AssertionError(
+                "Device must be of type CONTACT_SENSOR or MOTION_SENSOR"
+            )
 
     @property
     def is_low_battery(self) -> int:
-        return int(self.device_params['is_low_battery'])
+        return int(self.device_params["is_low_battery"])
 
 
 class PropertyIDs(Enum):
@@ -104,11 +111,11 @@ class PropertyIDs(Enum):
     CONTACT_STATE = "P1301"
     MOTION_STATE = "P1302"
     CAMERA_SIREN = "P1049"
-    ACCESSORY = "P1056" # Is state for camera accessories, like garage doors, light sockets, and floodlights.
+    ACCESSORY = "P1056"  # Is state for camera accessories, like garage doors, light sockets, and floodlights.
     SUN_MATCH = "P1528"
     MOTION_DETECTION = "P1047"  # Current Motion Detection State of the Camera
     MOTION_DETECTION_TOGGLE = "P1001"  # This toggles Camera Motion Detection On/Off
-    WCO_MOTION_DETECTION = "P1029" # Wyze cam outdoor requires both P1047 and P1029 to be set.  P1029 is set via set_property_list
+    WCO_MOTION_DETECTION = "P1029"  # Wyze cam outdoor requires both P1047 and P1029 to be set.  P1029 is set via set_property_list
 
 
 class WallSwitchProps(Enum):
@@ -153,7 +160,7 @@ class ResponseCodes(Enum):
     SUCCESS = "1"
     PARAMETER_ERROR = "1001"
     ACCESS_TOKEN_ERROR = "2001"
-    DEVICE_OFFLINE = '3019'
+    DEVICE_OFFLINE = "3019"
 
 
 class ResponseCodesLock(Enum):
@@ -205,9 +212,9 @@ class Event:
 
 
 class HMSStatus(Enum):
-    DISARMED = 'disarmed'
-    HOME = 'home'
-    AWAY = 'away'
+    DISARMED = "disarmed"
+    HOME = "home"
+    AWAY = "away"
 
 
 class DeviceMgmtToggleType:
@@ -217,6 +224,7 @@ class DeviceMgmtToggleType:
 
 
 class DeviceMgmtToggleProps(Enum):
-    EVENT_RECORDING_TOGGLE = DeviceMgmtToggleType("cam_event_recording", "ge.motion_detect_recording")
+    EVENT_RECORDING_TOGGLE = DeviceMgmtToggleType(
+        "cam_event_recording", "ge.motion_detect_recording"
+    )
     NOTIFICATION_TOGGLE = DeviceMgmtToggleType("cam_device_notify", "ge.push_switch")
-

wyzeapy/utils.py

@@ -4,6 +4,7 @@
 #  the license with this file. If not, please write to:
 #  katie@mulliken.net to receive a copy
 import base64
+import binascii
 import hashlib
 from typing import Dict, Any, List, Optional
 
@@ -12,6 +13,10 @@ from Crypto.Cipher import AES
 from .exceptions import ParameterError, AccessTokenError, UnknownApiError
 from .types import ResponseCodes, PropertyIDs, Device, Event
 
+"""
+Utility functions for encryption, decryption, error handling, and common Wyze API tasks.
+"""
+
 PADDING = bytes.fromhex("05")
 
 
@@ -43,7 +48,7 @@ def wyze_encrypt(key, text):
     cipher = AES.new(key, AES.MODE_CBC, iv)
     enc = cipher.encrypt(raw)
     b64_enc = base64.b64encode(enc).decode("ascii")
-    b64_enc = b64_enc.replace("/", r'\/')
+    b64_enc = b64_enc.replace("/", r"\/")
     return b64_enc
 
 
@@ -56,7 +61,7 @@ def wyze_decrypt(key, enc):
     """
     enc = base64.b64decode(enc)
 
-    key = key.encode('ascii')
+    key = key.encode("ascii")
     iv = key
     cipher = AES.new(key, AES.MODE_CBC, iv)
     decrypt = cipher.decrypt(enc)
@@ -66,31 +71,80 @@ def wyze_decrypt(key, enc):
     return decrypt_txt
 
 
+def wyze_decrypt_cbc(key: str, enc_hex_str: str) -> str:
+    """
+    Decrypt a hex-encoded string using Wyze's CBC decryption with MD5 based key.
+
+    Args:
+        key: The secret key string.
+        enc_hex_str: The encrypted data as a hex string.
+
+    Returns:
+        The decrypted plaintext string.
+    """
+    key_hash = hashlib.md5(key.encode("utf-8")).digest()
+
+    iv = b"0123456789ABCDEF"
+    cipher = AES.new(key_hash, AES.MODE_CBC, iv)
+
+    encrypted_bytes = binascii.unhexlify(enc_hex_str)
+    decrypted_bytes = cipher.decrypt(encrypted_bytes)
+
+    # PKCS5Padding
+    padding_length = decrypted_bytes[-1]
+    return decrypted_bytes[:-padding_length].decode()
+
+
 def create_password(password: str) -> str:
+    """
+    Derive the Wyze API password hash using a triple MD5 hashing scheme.
+
+    Args:
+        password: The plain user password string.
+
+    Returns:
+        The hashed password as a hex string.
+    """
     hex1 = hashlib.md5(password.encode()).hexdigest()
     hex2 = hashlib.md5(hex1.encode()).hexdigest()
     return hashlib.md5(hex2.encode()).hexdigest()
 
 
 def check_for_errors_standard(service, response_json: Dict[str, Any]) -> None:
-    response_code = response_json['code']
+    """
+    Check for standard Wyze API error codes and raise exceptions as needed.
+
+    Args:
+        service: The service instance triggering the call.
+        response_json: The JSON response from the API.
+    """
+    response_code = response_json["code"]
     if response_code != ResponseCodes.SUCCESS.value:
         if response_code == ResponseCodes.PARAMETER_ERROR.value:
-            raise ParameterError(response_code, response_json['msg'])
+            raise ParameterError(response_code, response_json["msg"])
         elif response_code == ResponseCodes.ACCESS_TOKEN_ERROR.value:
             service._auth_lib.token.expired = True
-            raise AccessTokenError(response_code, "Access Token expired, attempting to refresh")
+            raise AccessTokenError(
+                response_code, "Access Token expired, attempting to refresh"
+            )
         elif response_code == ResponseCodes.DEVICE_OFFLINE.value:
             return
         else:
-            raise UnknownApiError(response_code, response_json['msg'])
+            raise UnknownApiError(response_code, response_json["msg"])
 
 
 def check_for_errors_lock(service, response_json: Dict[str, Any]) -> None:
-    if response_json['ErrNo'] != 0:
-        if response_json.get('code') == ResponseCodes.PARAMETER_ERROR.value:
+    """
+    Check for lock-specific API errors and raise exceptions as needed.
+
+    Args:
+        service: The lock service instance.
+        response_json: The JSON response from the lock API.
+    """
+    if response_json["ErrNo"] != 0:
+        if response_json.get("code") == ResponseCodes.PARAMETER_ERROR.value:
             raise ParameterError(response_json)
-        elif response_json.get('code') == ResponseCodes.ACCESS_TOKEN_ERROR.value:
+        elif response_json.get("code") == ResponseCodes.ACCESS_TOKEN_ERROR.value:
             service._auth_lib.token.expired = True
             raise AccessTokenError("Access Token expired, attempting to refresh")
         else:
@@ -98,8 +152,15 @@ def check_for_errors_lock(service, response_json: Dict[str, Any]) -> None:
 
 
 def check_for_errors_devicemgmt(service, response_json: Dict[Any, Any]) -> None:
-    if response_json['status'] != 200:
-        if "InvalidTokenError>" in response_json['response']['errors'][0]['message']:
+    """
+    Check for device management API errors and raise exceptions as needed.
+
+    Args:
+        service: The device management service instance.
+        response_json: The JSON response from the device management API.
+    """
+    if response_json["status"] != 200:
+        if "InvalidTokenError>" in response_json["response"]["errors"][0]["message"]:
             service._auth_lib.token.expired = True
             raise AccessTokenError("Access Token expired, attempting to refresh")
         else:
@@ -107,20 +168,45 @@ def check_for_errors_devicemgmt(service, response_json: Dict[Any, Any]) -> None:
 
 
 def check_for_errors_iot(service, response_json: Dict[Any, Any]) -> None:
-    if response_json['code'] != 1:
-        if str(response_json['code']) == ResponseCodes.ACCESS_TOKEN_ERROR.value:
+    """
+    Check for IoT API errors and raise exceptions as needed.
+
+    Args:
+        service: The IoT service instance.
+        response_json: The JSON response from the IoT API.
+    """
+    if response_json["code"] != 1:
+        if str(response_json["code"]) == ResponseCodes.ACCESS_TOKEN_ERROR.value:
             service._auth_lib.token.expired = True
             raise AccessTokenError("Access Token expired, attempting to refresh")
         else:
             raise UnknownApiError(response_json)
 
+
 def check_for_errors_hms(service, response_json: Dict[Any, Any]) -> None:
-    if response_json['message'] is None:
+    """
+    Check for home monitoring system (HMS) API errors and raise exceptions as needed.
+
+    Args:
+        service: The HMS service instance.
+        response_json: The JSON response from the HMS API.
+    """
+    if response_json["message"] is None:
         service._auth_lib.token.expired = True
         raise AccessTokenError("Access Token expired, attempting to refresh")
 
 
 def return_event_for_device(device: Device, events: List[Event]) -> Optional[Event]:
+    """
+    Retrieve the most recent event matching a given device from a list of events.
+
+    Args:
+        device: The device to match against event.device_mac.
+        events: List of events to search.
+
+    Returns:
+        The first matching Event or None if no match is found.
+    """
     for event in events:
         if event.device_mac == device.mac:
             return event
@@ -129,4 +215,14 @@ def return_event_for_device(device: Device, events: List[Event]) -> Optional[Eve
 
 
 def create_pid_pair(pid_enum: PropertyIDs, value: str) -> Dict[str, str]:
+    """
+    Create a property ID/value pair dictionary for API payloads.
+
+    Args:
+        pid_enum: PropertyIDs enum member for the property.
+        value: The value to set for the property.
+
+    Returns:
+        A dict with 'pid' and 'pvalue' keys for the Wyze API.
+    """
     return {"pid": pid_enum.value, "pvalue": value}