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

wyzeapy/__init__.py

@@ -7,10 +7,7 @@ import logging
 from inspect import iscoroutinefunction
 from typing import List, Optional, Set, Callable
 
-from .const import PHONE_SYSTEM_TYPE, APP_VERSION, SC, APP_VER, SV, PHONE_ID, APP_NAME, OLIVE_APP_ID, APP_INFO
-from .crypto import olive_create_signature
 from .exceptions import TwoFactorAuthenticationEnabled
-from .payload_factory import olive_create_user_info_payload
 from .services.base_service import BaseService
 from .services.bulb_service import BulbService
 from .services.camera_service import CameraService
@@ -26,7 +23,22 @@ _LOGGER = logging.getLogger(__name__)
 
 
 class Wyzeapy:
-    """A module to assist developers in interacting with the Wyze service"""
+    """A Python module to assist developers in interacting with the Wyze service API.
+
+    This class provides methods for authentication, device management, and accessing
+    various Wyze device services including:
+
+    * **Bulbs** - Control brightness, color, and power state
+    * **Switches** - Toggle power and monitor usage
+    * **Cameras** - Access video streams and control settings
+    * **Thermostats** - Manage temperature settings and modes
+    * **Locks** - Control and monitor door locks
+    * **Sensors** - Monitor motion, contact, and environmental sensors
+    * **HMS** - Manage home monitoring system
+
+    Most interactions with Wyze devices should go through this class.
+    """
+
     # _client: Client
     _auth_lib: WyzeAuthLib
 
@@ -50,9 +62,13 @@ class Wyzeapy:
     @classmethod
     async def create(cls):
         """
-        Creates the Wyzeapy class in an async way. Although this is not currently utilized
+        Creates and initializes the Wyzeapy class asynchronously.
 
-        :return: An instance of the Wyzeapy class
+        This factory method provides a way to instantiate the class using async/await syntax,
+        though it's currently a simple implementation that may be expanded in the future.
+
+        **Returns:**
+            `Wyzeapy`: A new instance of the Wyzeapy class ready for authentication.
         """
         self = cls()
         return self
@@ -61,16 +77,21 @@ class Wyzeapy:
         self, email, password, key_id, api_key, token: Optional[Token] = None
     ):
         """
-        Logs the user in and retrieves the users token
+        Authenticates with the Wyze API and retrieves the user's access token.
+
+        This method handles the authentication process, including token management
+        and service initialization. If two-factor authentication is enabled on the account,
+        it will raise an exception requiring the use of `login_with_2fa()` instead.
 
-        :param email: Users email
-        :param password: Users password
-        :param key_id: Key ID for third-party API access
-        :param api_key: API Key for third-party API access
-        :param token: Users existing token from a previous session
+        **Args:**
+        * `email` (str): User's email address for Wyze account
+        * `password` (str): User's password for Wyze account
+        * `key_id` (str): Key ID for third-party API access
+        * `api_key` (str): API Key for third-party API access
+        * `token` (Optional[Token], optional): Existing token from a previous session. Defaults to None.
 
-        :raises:
-            TwoFactorAuthenticationEnabled: indicates that the account has 2fa enabled
+        **Raises:**
+        * `TwoFactorAuthenticationEnabled`: When the account has 2FA enabled and requires verification
         """
 
         self._email = email
@@ -95,10 +116,17 @@ class Wyzeapy:
 
     async def login_with_2fa(self, verification_code) -> Token:
         """
-        Logs the user in and retrieves the users token
+        Completes the login process for accounts with two-factor authentication enabled.
+
+        This method should be called after receiving a `TwoFactorAuthenticationEnabled`
+        exception from the `login()` method. It completes the authentication process
+        using the verification code sent to the user.
 
-        :param verification_code: Users 2fa verification code
+        **Args:**
+        * `verification_code` (str): The 2FA verification code received by the user
 
+        **Returns:**
+        * `Token`: The authenticated user token object
         """
 
         _LOGGER.debug(f"Verification Code: {verification_code}")
@@ -109,10 +137,13 @@ class Wyzeapy:
 
     async def execute_token_callbacks(self, token: Token):
         """
-        Sends the token to the registered callback functions.
+        Sends the token to all registered callback functions.
 
-        :param token: Users token object
+        This method is called internally whenever the token is refreshed or updated,
+        allowing external components to stay in sync with token changes.
 
+        **Args:**
+        * `token` (Token): The current user token object
         """
         for callback in self._token_callbacks:
             if iscoroutinefunction(callback):
@@ -122,27 +153,52 @@ class Wyzeapy:
 
     def register_for_token_callback(self, callback_function):
         """
-        Register a callback to be called whenever the user's token is modified
+        Registers a callback function to be called whenever the user's token is modified.
 
-        :param callback_function: A callback function which expects a token object
+        This allows external components to be notified of token changes for persistence
+        or other token-dependent operations.
 
+        **Args:**
+        * `callback_function`: A function that accepts a Token object as its parameter
+
+        **Example:**
+        ```python
+        def token_updated(token):
+            print(f"Token refreshed: {token.access_token[:10]}...")
+
+        wyze = Wyzeapy()
+        wyze.register_for_token_callback(token_updated)
+        ```
         """
         self._token_callbacks.append(callback_function)
 
     def unregister_for_token_callback(self, callback_function):
         """
-        Register a callback to be called whenever the user's token is modified
+        Removes a previously registered token callback function.
 
-        :param callback_function: A callback function which expects a token object
+        This stops the specified callback from receiving token updates.
 
+        **Args:**
+        * `callback_function`: The callback function to remove from the notification list
         """
         self._token_callbacks.remove(callback_function)
 
     @property
     async def unique_device_ids(self) -> Set[str]:
         """
-        Returns a list of all device ids known to the server
-        :return: A set containing the unique device ids
+        Retrieves a set of all unique device IDs known to the Wyze server.
+
+        This property fetches all devices associated with the account and
+        extracts their MAC addresses as unique identifiers.
+
+        **Returns:**
+        * `Set[str]`: A set containing all unique device IDs (MAC addresses)
+
+        **Example:**
+        ```python
+        device_ids = await wyze.unique_device_ids
+        print(f"Found {len(device_ids)} devices")
+        ```
         """
 
         devices = await self._service.get_object_list()
@@ -155,21 +211,45 @@ class Wyzeapy:
     @property
     async def notifications_are_on(self) -> bool:
         """
-        Reports the status of the notifications
+        Checks if push notifications are enabled for the account.
+
+        This property queries the user profile to determine the current
+        notification settings status.
 
-        :return: True if the notifications are enabled
+        **Returns:**
+        * `bool`: True if notifications are enabled, False otherwise
         """
 
         response_json = await self._service.get_user_profile()
-        return response_json['data']['notification']
+        return response_json["data"]["notification"]
 
     async def enable_notifications(self):
-        """Enables notifications on the account"""
+        """Enables push notifications for the Wyze account.
+
+        This method updates the user's profile to turn on push notifications
+        for all supported devices and events.
+
+        **Example:**
+        ```python
+        # Turn on notifications
+        await wyze.enable_notifications()
+        ```
+        """
 
         await self._service.set_push_info(True)
 
     async def disable_notifications(self):
-        """Disables notifications on the account"""
+        """Disables push notifications for the Wyze account.
+
+        This method updates the user's profile to turn off push notifications
+        for all devices and events.
+
+        **Example:**
+        ```python
+        # Turn off notifications
+        await wyze.disable_notifications()
+        ```
+        """
 
         await self._service.set_push_info(False)
 
@@ -178,13 +258,29 @@ class Wyzeapy:
         cls, email: str, password: str, key_id: str, api_key: str
     ) -> bool:
         """
-        Checks to see if a username and password return a valid login
-
-        :param email: The users email
-        :param password: The users password
-        :param key_id: Key ID for third-party API access
-        :param api_key: API Key for third-party API access
-        :return: True if the account can connect
+        Validates if the provided credentials can successfully authenticate with the Wyze API.
+
+        This method attempts to log in with the provided credentials and returns whether
+        the authentication was successful. It's useful for validating credentials without
+        needing to handle the full login process.
+
+        **Args:**
+        * `email` (str): The user's email address
+        * `password` (str): The user's password
+        * `key_id` (str): Key ID for third-party API access
+        * `api_key` (str): API Key for third-party API access
+
+        **Returns:**
+        * `bool`: True if the credentials are valid and authentication succeeded
+
+        **Example:**
+        ```python
+        is_valid = await Wyzeapy.valid_login("user@example.com", "password123", "key_id", "api_key")
+        if is_valid:
+            print("Credentials are valid")
+        else:
+            print("Invalid credentials")
+        ```
         """
 
         self = cls()
@@ -194,7 +290,21 @@ class Wyzeapy:
 
     @property
     async def bulb_service(self) -> BulbService:
-        """Returns an instance of the bulb service"""
+        """Provides access to the Wyze Bulb service.
+
+        This property lazily initializes and returns a BulbService instance
+        for controlling and monitoring Wyze bulbs.
+
+        **Returns:**
+        * `BulbService`: An instance of the bulb service for interacting with Wyze bulbs
+
+        **Example:**
+        ```python
+        # Get all bulbs
+        bulb_service = await wyze.bulb_service
+        bulbs = await bulb_service.get_bulbs()
+        ```
+        """
 
         if self._bulb_service is None:
             self._bulb_service = BulbService(self._auth_lib)
@@ -202,7 +312,21 @@ class Wyzeapy:
 
     @property
     async def switch_service(self) -> SwitchService:
-        """Returns an instance of the switch service"""
+        """Provides access to the Wyze Switch service.
+
+        This property lazily initializes and returns a SwitchService instance
+        for controlling and monitoring Wyze plugs and switches.
+
+        **Returns:**
+        * `SwitchService`: An instance of the switch service for interacting with Wyze switches
+
+        **Example:**
+        ```python
+        # Get all switches
+        switch_service = await wyze.switch_service
+        switches = await switch_service.get_switches()
+        ```
+        """
 
         if self._switch_service is None:
             self._switch_service = SwitchService(self._auth_lib)
@@ -210,7 +334,21 @@ class Wyzeapy:
 
     @property
     async def camera_service(self) -> CameraService:
-        """Returns an instance of the camera service"""
+        """Provides access to the Wyze Camera service.
+
+        This property lazily initializes and returns a CameraService instance
+        for controlling and monitoring Wyze cameras.
+
+        **Returns:**
+        * `CameraService`: An instance of the camera service for interacting with Wyze cameras
+
+        **Example:**
+        ```python
+        # Get all cameras
+        camera_service = await wyze.camera_service
+        cameras = await camera_service.get_cameras()
+        ```
+        """
 
         if self._camera_service is None:
             self._camera_service = CameraService(self._auth_lib)
@@ -218,7 +356,21 @@ class Wyzeapy:
 
     @property
     async def thermostat_service(self) -> ThermostatService:
-        """Returns an instance of the thermostat service"""
+        """Provides access to the Wyze Thermostat service.
+
+        This property lazily initializes and returns a ThermostatService instance
+        for controlling and monitoring Wyze thermostats.
+
+        **Returns:**
+        * `ThermostatService`: An instance of the thermostat service for interacting with Wyze thermostats
+
+        **Example:**
+        ```python
+        # Get all thermostats
+        thermostat_service = await wyze.thermostat_service
+        thermostats = await thermostat_service.get_thermostats()
+        ```
+        """
 
         if self._thermostat_service is None:
             self._thermostat_service = ThermostatService(self._auth_lib)
@@ -226,7 +378,21 @@ class Wyzeapy:
 
     @property
     async def hms_service(self) -> HMSService:
-        """Returns an instance of the hms service"""
+        """Provides access to the Wyze Home Monitoring Service (HMS).
+
+        This property lazily initializes and returns an HMSService instance
+        for controlling and monitoring the Wyze home security system.
+
+        **Returns:**
+        * `HMSService`: An instance of the HMS service for interacting with Wyze home monitoring
+
+        **Example:**
+        ```python
+        # Get HMS status
+        hms_service = await wyze.hms_service
+        status = await hms_service.get_hms_status()
+        ```
+        """
 
         if self._hms_service is None:
             self._hms_service = await HMSService.create(self._auth_lib)
@@ -234,7 +400,21 @@ class Wyzeapy:
 
     @property
     async def lock_service(self) -> LockService:
-        """Returns an instance of the lock service"""
+        """Provides access to the Wyze Lock service.
+
+        This property lazily initializes and returns a LockService instance
+        for controlling and monitoring Wyze locks.
+
+        **Returns:**
+        * `LockService`: An instance of the lock service for interacting with Wyze locks
+
+        **Example:**
+        ```python
+        # Get all locks
+        lock_service = await wyze.lock_service
+        locks = await lock_service.get_locks()
+        ```
+        """
 
         if self._lock_service is None:
             self._lock_service = LockService(self._auth_lib)
@@ -242,7 +422,21 @@ class Wyzeapy:
 
     @property
     async def sensor_service(self) -> SensorService:
-        """Returns an instance of the sensor service"""
+        """Provides access to the Wyze Sensor service.
+
+        This property lazily initializes and returns a SensorService instance
+        for monitoring Wyze sensors such as contact sensors, motion sensors, etc.
+
+        **Returns:**
+        * `SensorService`: An instance of the sensor service for interacting with Wyze sensors
+
+        **Example:**
+        ```python
+        # Get all sensors
+        sensor_service = await wyze.sensor_service
+        sensors = await sensor_service.get_sensors()
+        ```
+        """
 
         if self._sensor_service is None:
             self._sensor_service = SensorService(self._auth_lib)
@@ -250,7 +444,21 @@ class Wyzeapy:
 
     @property
     async def wall_switch_service(self) -> WallSwitchService:
-        """Returns an instance of the switch service"""
+        """Provides access to the Wyze Wall Switch service.
+
+        This property lazily initializes and returns a WallSwitchService instance
+        for controlling and monitoring Wyze wall switches.
+
+        **Returns:**
+        * `WallSwitchService`: An instance of the wall switch service for interacting with Wyze wall switches
+
+        **Example:**
+        ```python
+        # Get all wall switches
+        wall_switch_service = await wyze.wall_switch_service
+        switches = await wall_switch_service.get_wall_switches()
+        ```
+        """
 
         if self._wall_switch_service is None:
             self._wall_switch_service = WallSwitchService(self._auth_lib)
@@ -258,7 +466,21 @@ class Wyzeapy:
 
     @property
     async def switch_usage_service(self) -> SwitchUsageService:
-        """Returns an instance of the switch usage service"""
+        """Provides access to the Wyze Switch Usage service.
+
+        This property lazily initializes and returns a SwitchUsageService instance
+        for retrieving usage statistics from Wyze switches and plugs.
+
+        **Returns:**
+        * `SwitchUsageService`: An instance of the switch usage service for accessing Wyze switch usage data
+
+        **Example:**
+        ```python
+        # Get usage data for a switch
+        usage_service = await wyze.switch_usage_service
+        usage = await usage_service.get_usage_records(switch_mac)
+        ```
+        """
         if self._switch_usage_service is None:
             self._switch_usage_service = SwitchUsageService(self._auth_lib)
         return self._switch_usage_service

wyzeapy/const.py

@@ -3,16 +3,21 @@
 #  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
+# Standard library imports
 import uuid
 
-# Here is where all the *magic* lives
+# Module constants for application identification, API credentials, and crypto secrets
+"""
+Configuration constants for Wyze API integration, including app metadata,
+API keys, and cryptographic secrets.
+"""
 PHONE_SYSTEM_TYPE = "1"
 API_KEY = "WMXHYf79Nr5gIlt3r0r7p9Tcw5bvs6BB4U8O8nGJ"
 APP_VERSION = "2.18.43"
 APP_VER = "com.hualai.WyzeCam___2.18.43"
 APP_NAME = "com.hualai.WyzeCam"
 PHONE_ID = str(uuid.uuid4())
-APP_INFO = 'wyze_android_2.19.14'  # Required for the thermostat
+APP_INFO = "wyze_android_2.19.14"  # Required for the thermostat
 SC = "9f275790cab94a72bd206c8876429f3c"
 SV = "9d74946e652647e9b6c9d59326aef104"
 CLIENT_VER = "2"
@@ -20,7 +25,7 @@ SOURCE = "ios/WZCameraSDK"
 APP_PLATFORM = "ios"
 
 # Crypto secrets
-OLIVE_SIGNING_SECRET = 'wyze_app_secret_key_132'  # Required for the thermostat
-OLIVE_APP_ID = '9319141212m2ik'  # Required for the thermostat
+OLIVE_SIGNING_SECRET = "wyze_app_secret_key_132"  # Required for the thermostat
+OLIVE_APP_ID = "9319141212m2ik"  # Required for the thermostat
 FORD_APP_KEY = "275965684684dbdaf29a0ed9"  # Required for the locks
 FORD_APP_SECRET = "4deekof1ba311c5c33a9cb8e12787e8c"  # Required for the locks

wyzeapy/crypto.py

@@ -10,8 +10,24 @@ from typing import Dict, Union, Any
 
 from .const import FORD_APP_SECRET, OLIVE_SIGNING_SECRET
 
+"""
+Cryptographic helper functions for creating API request signatures.
+"""
 
-def olive_create_signature(payload: Union[Dict[Any, Any], str], access_token: str) -> str:
+
+def olive_create_signature(
+    payload: Union[Dict[Any, Any], str], access_token: str
+) -> str:
+    """
+    Compute the olive (Wyze) API request signature using HMAC-MD5.
+
+    Args:
+        payload: The request payload as a dict or raw string.
+        access_token: The access token string for signing.
+
+    Returns:
+        The computed signature as a hex string.
+    """
     if isinstance(payload, dict):
         body = ""
         for item in sorted(payload):
@@ -28,7 +44,20 @@ def olive_create_signature(payload: Union[Dict[Any, Any], str], access_token: st
     return hmac.new(secret.encode(), body.encode(), hashlib.md5).hexdigest()
 
 
-def ford_create_signature(url_path: str, request_method: str, payload: Dict[Any, Any]) -> str:
+def ford_create_signature(
+    url_path: str, request_method: str, payload: Dict[Any, Any]
+) -> str:
+    """
+    Compute the ford (Lock) API request signature using MD5 of URL-encoded buffer.
+
+    Args:
+        url_path: The URL path of the request.
+        request_method: HTTP method (e.g., 'GET', 'POST').
+        payload: The request payload dict to include in the signature.
+
+    Returns:
+        The computed signature as a hex string.
+    """
     string_buf = request_method + url_path
     for entry in sorted(payload.keys()):
         string_buf += entry + "=" + payload[entry] + "&"

wyzeapy/exceptions.py

@@ -3,31 +3,34 @@
 #  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
-from typing import Dict, Any
+"""
+Custom exception classes for Wyzeapy API interactions.
+"""
 
 
 class ActionNotSupported(Exception):
-    def __init__(self, device_type: str):
-        message = "The action specified is not supported by device type: {}".format(device_type)
+    """Raised when an unsupported action is requested for a device type."""
 
+    def __init__(self, device_type: str):
+        message = f"The action specified is not supported by device type: {device_type}"
         super().__init__(message)
 
 
 class ParameterError(Exception):
-    pass
+    """Raised when invalid parameters are provided to an API call."""
 
 
 class AccessTokenError(Exception):
-    pass
+    """Raised when the access token is invalid or has expired."""
 
 
 class LoginError(Exception):
-    pass
+    """Raised during authentication or login failures."""
 
 
 class UnknownApiError(Exception):
-    pass
+    """Raised for unexpected or generic API errors."""
 
 
 class TwoFactorAuthenticationEnabled(Exception):
-    pass
+    """Raised when two-factor authentication is required for login."""