feat: add SwitchbotAuthenticationError exception

switchbot/__init__.py

@@ -4,7 +4,7 @@
 from bleak_retry_connector import close_stale_connections, get_device
 
 from .adv_parser import SwitchbotSupportedType, parse_advertisement_data
-from .const import LockStatus, SwitchbotModel
+from .const import LockStatus, SwitchbotModel, SwitchbotAuthenticationError
 from .devices.base_light import SwitchbotBaseLight
 from .devices.bot import Switchbot
 from .devices.bulb import SwitchbotBulb
@@ -24,6 +24,7 @@
     "parse_advertisement_data",
     "GetSwitchbotDevices",
     "SwitchBotAdvertisement",
+    "SwitchbotAuthenticationError",
     "ColorMode",
     "LockStatus",
     "SwitchbotBaseLight",

switchbot/const.py

@@ -10,6 +10,14 @@
 from .enum import StrEnum
 
 
+class SwitchbotAuthenticationError(RuntimeError):
+    """Raised when authentication fails.
+
+    This exception inherits from RuntimeError to avoid breaking existing code
+    but will be changed to Exception in a future release.
+    """
+
+
 class SwitchbotModel(StrEnum):
 
     BOT = "WoHand"

switchbot/devices/lock.py

@@ -15,7 +15,7 @@
 from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
 
 from ..api_config import SWITCHBOT_APP_API_BASE_URL, SWITCHBOT_APP_COGNITO_POOL
-from ..const import LockStatus
+from ..const import LockStatus, SwitchbotAuthenticationError
 from .device import SwitchbotDevice, SwitchbotOperationError
 
 COMMAND_HEADER = "57"
@@ -103,16 +103,18 @@ def retrieve_encryption_key(device_mac: str, username: str, password: str):
                 },
             )
         except cognito_idp_client.exceptions.NotAuthorizedException as err:
-            raise RuntimeError("Failed to authenticate") from err
+            raise SwitchbotAuthenticationError("Failed to authenticate") from err
         except BaseException as err:
-            raise RuntimeError("Unexpected error during authentication") from err
+            raise SwitchbotAuthenticationError(
+                "Unexpected error during authentication"
+            ) from err
 
         if (
             auth_response is None
             or "AuthenticationResult" not in auth_response
             or "AccessToken" not in auth_response["AuthenticationResult"]
         ):
-            raise RuntimeError("Unexpected authentication response")
+            raise SwitchbotAuthenticationError("Unexpected authentication response")
 
         access_token = auth_response["AuthenticationResult"]["AccessToken"]
         key_response = requests.post(
@@ -126,7 +128,7 @@ def retrieve_encryption_key(device_mac: str, username: str, password: str):
         )
         key_response_content = json.loads(key_response.content)
         if key_response_content["statusCode"] != 100:
-            raise RuntimeError(
+            raise SwitchbotAuthenticationError(
                 f"Unexpected status code returned by SwitchBot API: {key_response_content['statusCode']}"
             )