Add BleakCharacteristicNotFoundError (#1439)

It's not uncommon for devices to change its set of supported characteristics, for example during an initial setup.
Without a specialized exception class it's tricky to detect when this happens.

CHANGELOG.rst

@@ -10,6 +10,10 @@ and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0
 `Unreleased`_
 =============
 
+Added
+-----
+* Added ``BleakCharacteristicNotFoundError`` which is raised if a device does not support a characteristic.
+
 Changed
 -------
 * Updated PyObjC dependency on macOS to v10.x.

bleak/__init__.py

@@ -57,7 +57,7 @@
     get_platform_scanner_backend_type,
 )
 from .backends.service import BleakGATTServiceCollection
-from .exc import BleakError
+from .exc import BleakCharacteristicNotFoundError, BleakError
 from .uuids import normalize_uuid_str
 
 if TYPE_CHECKING:
@@ -766,7 +766,7 @@ async def write_gatt_char(
             characteristic = self.services.get_characteristic(char_specifier)
 
         if not characteristic:
-            raise BleakError(f"Characteristic {char_specifier} was not found!")
+            raise BleakCharacteristicNotFoundError(char_specifier)
 
         if response is None:
             # if not specified, prefer write-with-response over write-without-
@@ -819,7 +819,7 @@ def callback(sender: BleakGATTCharacteristic, data: bytearray):
             characteristic = char_specifier
 
         if not characteristic:
-            raise BleakError(f"Characteristic {char_specifier} not found!")
+            raise BleakCharacteristicNotFoundError(char_specifier)
 
         if inspect.iscoroutinefunction(callback):
 

bleak/backends/bluezdbus/client.py

@@ -26,7 +26,12 @@
 from dbus_fast.signature import Variant
 
 from ... import BleakScanner
-from ...exc import BleakDBusError, BleakError, BleakDeviceNotFoundError
+from ...exc import (
+    BleakCharacteristicNotFoundError,
+    BleakDBusError,
+    BleakDeviceNotFoundError,
+    BleakError,
+)
 from ..characteristic import BleakGATTCharacteristic
 from ..client import BaseBleakClient, NotifyCallback
 from ..device import BLEDevice
@@ -725,11 +730,7 @@ async def read_gatt_char(
                 )
                 return value
 
-            raise BleakError(
-                "Characteristic with UUID {0} could not be found!".format(
-                    char_specifier
-                )
-            )
+            raise BleakCharacteristicNotFoundError(char_specifier)
 
         while True:
             assert self._bus
@@ -977,7 +978,7 @@ async def stop_notify(
         else:
             characteristic = char_specifier
         if not characteristic:
-            raise BleakError("Characteristic {} not found!".format(char_specifier))
+            raise BleakCharacteristicNotFoundError(char_specifier)
 
         reply = await self._bus.call(
             Message(

bleak/backends/corebluetooth/client.py

@@ -24,7 +24,11 @@
 from Foundation import NSArray, NSData
 
 from ... import BleakScanner
-from ...exc import BleakError, BleakDeviceNotFoundError
+from ...exc import (
+    BleakCharacteristicNotFoundError,
+    BleakDeviceNotFoundError,
+    BleakError,
+)
 from ..characteristic import BleakGATTCharacteristic
 from ..client import BaseBleakClient, NotifyCallback
 from ..device import BLEDevice
@@ -273,7 +277,7 @@ async def read_gatt_char(
         else:
             characteristic = char_specifier
         if not characteristic:
-            raise BleakError("Characteristic {} was not found!".format(char_specifier))
+            raise BleakCharacteristicNotFoundError(char_specifier)
 
         output = await self._delegate.read_characteristic(
             characteristic.obj, use_cached=use_cached
@@ -373,7 +377,7 @@ async def stop_notify(
         else:
             characteristic = char_specifier
         if not characteristic:
-            raise BleakError("Characteristic {} not found!".format(char_specifier))
+            raise BleakCharacteristicNotFoundError(char_specifier)
 
         await self._delegate.stop_notifications(characteristic.obj)
 

bleak/backends/p4android/client.py

@@ -11,7 +11,7 @@
 from android.broadcast import BroadcastReceiver
 from jnius import java_method
 
-from ...exc import BleakError
+from ...exc import BleakCharacteristicNotFoundError, BleakError
 from ..characteristic import BleakGATTCharacteristic
 from ..client import BaseBleakClient, NotifyCallback
 from ..device import BLEDevice
@@ -316,9 +316,7 @@ async def read_gatt_char(
             characteristic = char_specifier
 
         if not characteristic:
-            raise BleakError(
-                f"Characteristic with UUID {char_specifier} could not be found!"
-            )
+            raise BleakCharacteristicNotFoundError(char_specifier)
 
         (value,) = await self.__callbacks.perform_and_wait(
             dispatchApi=self.__gatt.readCharacteristic,
@@ -469,7 +467,7 @@ async def stop_notify(
         else:
             characteristic = char_specifier
         if not characteristic:
-            raise BleakError(f"Characteristic {char_specifier} not found!")
+            raise BleakCharacteristicNotFoundError(char_specifier)
 
         await self.write_gatt_descriptor(
             characteristic.notification_descriptor,

bleak/backends/winrt/client.py

@@ -101,7 +101,12 @@
     from bleak_winrt.windows.storage.streams import Buffer as WinBuffer
 
 from ... import BleakScanner
-from ...exc import PROTOCOL_ERROR_CODES, BleakDeviceNotFoundError, BleakError
+from ...exc import (
+    PROTOCOL_ERROR_CODES,
+    BleakCharacteristicNotFoundError,
+    BleakDeviceNotFoundError,
+    BleakError,
+)
 from ..characteristic import BleakGATTCharacteristic
 from ..client import BaseBleakClient, NotifyCallback
 from ..device import BLEDevice
@@ -820,7 +825,7 @@ async def read_gatt_char(
         else:
             characteristic = char_specifier
         if not characteristic:
-            raise BleakError(f"Characteristic {char_specifier} was not found!")
+            raise BleakCharacteristicNotFoundError(char_specifier)
 
         value = bytearray(
             _ensure_success(
@@ -1007,7 +1012,7 @@ async def stop_notify(
         else:
             characteristic = char_specifier
         if not characteristic:
-            raise BleakError(f"Characteristic {char_specifier} not found!")
+            raise BleakCharacteristicNotFoundError(char_specifier)
 
         _ensure_success(
             await characteristic.obj.write_client_characteristic_configuration_descriptor_async(

bleak/exc.py

@@ -1,5 +1,6 @@
 # -*- coding: utf-8 -*-
-from typing import Optional
+import uuid
+from typing import Optional, Union
 
 
 class BleakError(Exception):
@@ -8,6 +9,24 @@ class BleakError(Exception):
     pass
 
 
+class BleakCharacteristicNotFoundError(BleakError):
+    """
+    Exception which is raised if a device does not support a characteristic.
+
+    .. versionadded: 0.22.0
+    """
+
+    char_specifier: Union[int, str, uuid.UUID]
+
+    def __init__(self, char_specifier: Union[int, str, uuid.UUID]) -> None:
+        """
+        Args:
+            characteristic (str): handle or UUID of the characteristic which was not found
+        """
+        super().__init__(f"Characteristic {char_specifier} was not found!")
+        self.char_specifier = char_specifier
+
+
 class BleakDeviceNotFoundError(BleakError):
     """
     Exception which is raised if a device can not be found by ``connect``, ``pair`` and ``unpair``.