Documentation updates

bleak/backends/bluezdbus/characteristic.py

@@ -26,7 +26,7 @@
 
 
 class BleakGATTCharacteristicBlueZDBus(BleakGATTCharacteristic):
-    """Interface for the Bleak representation of a GATT Characteristic"""
+    """GATT Characteristic implementation for the BlueZ DBus backend"""
 
     def __init__(self, obj: dict, object_path: str, service_uuid: str):
         super(BleakGATTCharacteristicBlueZDBus, self).__init__(obj)
@@ -46,26 +46,38 @@ def uuid(self) -> str:
 
     @property
     def description(self) -> str:
+        """Description for this characteristic"""
         # No description available in DBus backend.
         return ""
 
     @property
     def properties(self) -> List:
+        """Properties of this characteristic
+
+        Returns the characteristics `Flags` present in the DBus API.
+        """
         return self.obj["Flags"]
 
     @property
     def descriptors(self) -> List:
+        """List of descriptors for this service"""
         return self.__descriptors
 
     def get_descriptor(self, _uuid: str) -> Union[BleakGATTDescriptor, None]:
+        """Get a descriptor by UUID"""
         try:
             return next(filter(lambda x: x.uuid == _uuid, self.descriptors))
         except StopIteration:
             return None
 
     def add_descriptor(self, descriptor: BleakGATTDescriptor):
+        """Add a :py:class:`~BleakGATTDescriptor` to the characteristic.
+
+        Should not be used by end user, but rather by `bleak` itself.
+        """
         self.__descriptors.append(descriptor)
 
     @property
     def path(self) -> str:
+        """The DBus path. Mostly needed by `bleak`, not by end user"""
         return self.__path

bleak/backends/bluezdbus/descriptor.py

@@ -2,6 +2,8 @@
 
 
 class BleakGATTDescriptorBlueZDBus(BleakGATTDescriptor):
+    """GATT Descriptor implementation for BlueZ DBus backend"""
+
     def __init__(self, obj: dict, object_path: str, characteristic_uuid: str):
         super(BleakGATTDescriptorBlueZDBus, self).__init__(obj)
         self.__path = object_path
@@ -10,16 +12,20 @@ def __init__(self, obj: dict, object_path: str, characteristic_uuid: str):
 
     @property
     def characteristic_uuid(self) -> str:
+        """UUID for the characteristic that this descriptor belongs to"""
         return self.__characteristic_uuid
 
     @property
     def uuid(self) -> str:
+        """UUID for this descriptor"""
         return self.obj["UUID"]
 
     @property
     def handle(self) -> int:
+        """Integer handle for this descriptor"""
         return self.__handle
 
     @property
     def path(self) -> str:
+        """The DBus path. Mostly needed by `bleak`, not by end user"""
         return self.__path

bleak/backends/bluezdbus/service.py

@@ -1,34 +1,39 @@
 from typing import Union, List
 
 from bleak.backends.service import BleakGATTService
-from bleak.backends.characteristic import BleakGATTCharacteristic
 from bleak.backends.bluezdbus.characteristic import BleakGATTCharacteristicBlueZDBus
 
 
 class BleakGATTServiceBlueZDBus(BleakGATTService):
+    """GATT Service implementation for the BlueZ DBus backend"""
+
     def __init__(self, obj, path):
         super().__init__(obj)
         self.__characteristics = []
         self.__path = path
 
     @property
     def uuid(self) -> str:
+        """The UUID to this service"""
         return self.obj["UUID"]
 
     @property
-    def description(self) -> str:
-        return super(BleakGATTServiceBlueZDBus, self).description
-
-    @property
-    def characteristics(self) -> List:
+    def characteristics(self) -> List[BleakGATTCharacteristicBlueZDBus]:
+        """List of characteristics for this service"""
         return self.__characteristics
 
-    def get_characteristic(self, _uuid) -> Union[BleakGATTCharacteristic, None]:
+    def get_characteristic(self, _uuid) -> Union[BleakGATTCharacteristicBlueZDBus, None]:
+        """Get a characteristic by UUID"""
         raise NotImplementedError()
 
     def add_characteristic(self, characteristic: BleakGATTCharacteristicBlueZDBus):
+        """Add a :py:class:`~BleakGATTCharacteristicBlueZDBus` to the service.
+
+        Should not be used by end user, but rather by `bleak` itself.
+        """
         self.__characteristics.append(characteristic)
 
     @property
     def path(self):
+        """The DBus path. Mostly needed by `bleak`, not by end user"""
         return self.__path

bleak/backends/characteristic.py

@@ -7,10 +7,24 @@
 """
 import abc
 from typing import List, Union, Any
+import enum
 
 from bleak.backends.descriptor import BleakGATTDescriptor
 
 
+class GattCharacteristicsFlags(enum.Enum):
+    broadcast = 0x0001
+    read = 0x0002
+    write_without_response = 0x0004
+    write = 0x0008
+    notify = 0x0010
+    indicate = 0x0020
+    authenticated_signed_writes = 0x0040
+    extended_properties = 0x0080
+    reliable_write = 0x0100
+    writable_auxiliaries = 0x0200
+
+
 class BleakGATTCharacteristic(abc.ABC):
     """Interface for the Bleak representation of a GATT Characteristic
 
@@ -25,34 +39,42 @@ def __str__(self):
     @property
     @abc.abstractmethod
     def service_uuid(self) -> str:
-        """The uuid of the Service containing this characteristic"""
+        """The UUID of the Service containing this characteristic"""
         raise NotImplementedError()
 
     @property
     @abc.abstractmethod
     def uuid(self) -> str:
-        """The uuid of this characteristic"""
+        """The UUID for this characteristic"""
         raise NotImplementedError()
 
     @property
     @abc.abstractmethod
     def description(self) -> str:
+        """Description for this characteristic"""
         raise NotImplementedError()
 
     @property
     @abc.abstractmethod
-    def properties(self) -> List:
+    def properties(self) -> List[str]:
+        """Properties of this characteristic"""
         raise NotImplementedError()
 
     @property
     @abc.abstractmethod
     def descriptors(self) -> List:
+        """List of descriptors for this service"""
         raise NotImplementedError()
 
     @abc.abstractmethod
     def get_descriptor(self, _uuid: str) -> Union[BleakGATTDescriptor, None]:
+        """Get a descriptor by UUID"""
         raise NotImplementedError()
 
     @abc.abstractmethod
     def add_descriptor(self, descriptor: BleakGATTDescriptor):
+        """Add a :py:class:`~BleakGATTDescriptor` to the characteristic.
+
+        Should not be used by end user, but rather by `bleak` itself.
+        """
         raise NotImplementedError()

bleak/backends/descriptor.py

@@ -43,17 +43,22 @@ def __str__(self):
     @property
     @abc.abstractmethod
     def characteristic_uuid(self) -> str:
+        """UUID for the characteristic that this descriptor belongs to"""
         raise NotImplementedError()
 
     @property
     @abc.abstractmethod
     def uuid(self) -> str:
+        """UUID for this descriptor"""
         raise NotImplementedError()
 
     @property
     @abc.abstractmethod
     def handle(self) -> int:
+        """Integer handle for this descriptor"""
         raise NotImplementedError()
 
+    @property
     def description(self):
+        """A text description of what this descriptor represents"""
         return _descriptor_descriptions.get(self.uuid, ["None"])[0]

bleak/backends/dotnet/characteristic.py

@@ -43,7 +43,7 @@
 
 
 class BleakGATTCharacteristicDotNet(BleakGATTCharacteristic):
-    """Interface for the Bleak representation of a GATT Characteristic"""
+    """GATT Characteristic implementation for the .NET backend"""
 
     def __init__(self, obj: GattCharacteristic):
         super().__init__(obj)
@@ -71,21 +71,29 @@ def uuid(self) -> str:
 
     @property
     def description(self) -> str:
+        """Description for this characteristic"""
         return self.obj.UserDescription
 
     @property
     def properties(self) -> List:
+        """Properties of this characteristic"""
         return self.__props
 
     @property
     def descriptors(self) -> List[BleakGATTDescriptorDotNet]:
+        """List of descriptors for this service"""
         return self.__descriptors
 
     def get_descriptor(self, _uuid) -> Union[BleakGATTDescriptorDotNet, None]:
+        """Get a descriptor by UUID"""
         try:
             return next(filter(lambda x: x.uuid == _uuid, self.descriptors))
         except StopIteration:
             return None
 
     def add_descriptor(self, descriptor: BleakGATTDescriptor):
+        """Add a :py:class:`~BleakGATTDescriptor` to the characteristic.
+
+        Should not be used by end user, but rather by `bleak` itself.
+        """
         self.__descriptors.append(descriptor)

bleak/backends/dotnet/descriptor.py

@@ -11,7 +11,7 @@
 
 
 class BleakGATTDescriptorDotNet(BleakGATTDescriptor):
-    """Interface for the Bleak representation of a GATT Descriptor"""
+    """GATT Descriptor implementation for .NET backend"""
 
     def __init__(self, obj: GattDescriptor, characteristic_uuid: str):
         super(BleakGATTDescriptorDotNet, self).__init__(obj)
@@ -22,13 +22,16 @@ def __str__(self):
         return "{0}: (Handle: {1})".format(self.uuid, self.handle)
 
     @property
-    def characteristic_uuid(self):
+    def characteristic_uuid(self) -> str:
+        """UUID for the characteristic that this descriptor belongs to"""
         return self.__characteristic_uuid
 
     @property
-    def uuid(self):
+    def uuid(self) -> str:
+        """UUID for this descriptor"""
         return self.obj.Uuid.ToString()
 
     @property
-    def handle(self):
+    def handle(self) -> int:
+        """Integer handle for this descriptor"""
         return self.obj.AttributeHandle

bleak/backends/dotnet/service.py

@@ -1,14 +1,13 @@
-from typing import List
+from typing import List, Union
 
-
-from bleak.uuids import uuidstr_to_str
 from bleak.backends.service import BleakGATTService
 from bleak.backends.dotnet.characteristic import BleakGATTCharacteristicDotNet
 
 from Windows.Devices.Bluetooth.GenericAttributeProfile import GattDeviceService
 
 
 class BleakGATTServiceDotNet(BleakGATTService):
+    """GATT Characteristic implementation for the .NET backend"""
     def __init__(self, obj: GattDeviceService):
         super().__init__(obj)
         self.__characteristics = [
@@ -20,18 +19,20 @@ def uuid(self):
         return self.obj.Uuid.ToString()
 
     @property
-    def description(self):
-        return super(BleakGATTServiceDotNet, self).description
-
-    @property
-    def characteristics(self) -> List:
+    def characteristics(self) -> List[BleakGATTCharacteristicDotNet]:
+        """List of characteristics for this service"""
         return self.__characteristics
 
-    def get_characteristic(self, _uuid):
+    def get_characteristic(self, _uuid) -> Union[BleakGATTCharacteristicDotNet, None]:
+        """Get a characteristic by UUID"""
         try:
             return next(filter(lambda x: x.uuid == _uuid, self.characteristics))
         except StopIteration:
             return None
 
     def add_characteristic(self, characteristic: BleakGATTCharacteristicDotNet):
+        """Add a :py:class:`~BleakGATTCharacteristicDotNet` to the service.
+
+        Should not be used by end user, but rather by `bleak` itself.
+        """
         self.__characteristics.append(characteristic)