Merge pull request #18 from tekktrik/doc/add-typing

Add type annotations

Author: tannewt

adafruit_ble_adafruit/adafruit_service.py

@@ -39,6 +39,12 @@
 from adafruit_ble.uuid import VendorUUID
 from adafruit_ble.services import Service
 
+try:
+    from typing import Optional
+    from _bleio import ScanEntry
+except ImportError:
+    pass
+
 
 _MANUFACTURING_DATA_ADT = const(0xFF)
 _ADAFRUIT_COMPANY_ID = const(0x0822)
@@ -69,7 +75,7 @@ class AdafruitServerAdvertisement(
     pid = ManufacturerDataField(_PID_DATA_ID, "<H")
     """The USB PID (product id) for this board."""
 
-    def __init__(self, *, entry=None):
+    def __init__(self, *, entry: Optional[ScanEntry] = None) -> None:
         super().__init__(entry=entry)
         # Return early if things have been set by an existing ScanEntry.
         if entry:
@@ -84,14 +90,14 @@ class AdafruitService(Service):
     """Common superclass for all Adafruit board services."""
 
     @staticmethod
-    def adafruit_service_uuid(n):
+    def adafruit_service_uuid(n: int) -> VendorUUID:
         """Generate a VendorUUID which fills in a 16-bit value in the standard
         Adafruit Service UUID: ADAFnnnn-C332-42A8-93BD-25E905756CB8.
         """
         return VendorUUID("ADAF{:04x}-C332-42A8-93BD-25E905756CB8".format(n))
 
     @classmethod
-    def measurement_period_charac(cls, msecs=1000):
+    def measurement_period_charac(cls, msecs: int = 1000) -> Int32Characteristic:
         """Create a measurement_period Characteristic for use by a subclass."""
         return Int32Characteristic(
             uuid=cls.adafruit_service_uuid(0x0001),
@@ -100,7 +106,7 @@ def measurement_period_charac(cls, msecs=1000):
         )
 
     @classmethod
-    def service_version_charac(cls, version=1):
+    def service_version_charac(cls, version: int = 1) -> Uint32Characteristic:
         """Create a service_version Characteristic for use by a subclass."""
         return Uint32Characteristic(
             uuid=cls.adafruit_service_uuid(0x0002),

adafruit_ble_adafruit/addressable_pixel_service.py

@@ -24,6 +24,11 @@
 from adafruit_ble.characteristics.int import Uint8Characteristic, Uint16Characteristic
 from adafruit_ble_adafruit.adafruit_service import AdafruitService
 
+try:
+    from typing import Optional
+except ImportError:
+    pass
+
 PixelValues = namedtuple(
     "PixelValues",
     ("start", "write_now", "data"),
@@ -57,14 +62,14 @@ class _PixelPacket(ComplexCharacteristic):
 
     uuid = AdafruitService.adafruit_service_uuid(0x903)
 
-    def __init__(self):
+    def __init__(self) -> None:
         super().__init__(
             properties=Characteristic.WRITE,
             read_perm=Attribute.NO_ACCESS,
             max_length=self.MAX_LENGTH,
         )
 
-    def bind(self, service):
+    def bind(self, service: "AddressablePixelService") -> _bleio.PacketBuffer:
         """Binds the characteristic to the given Service."""
         bound_characteristic = super().bind(service)
         return _bleio.PacketBuffer(bound_characteristic, buffer_size=1)
@@ -98,12 +103,12 @@ class AddressablePixelService(AdafruitService):
     _pixel_packet = _PixelPacket()
     """Pixel-setting data."""
 
-    def __init__(self, service=None):
+    def __init__(self, service: Optional["AddressablePixelService"] = None) -> None:
         self._pixel_packet_buf = bytearray(_PixelPacket.MAX_LENGTH)
         super().__init__(service=service)
 
     @property
-    def values(self):
+    def values(self) -> Optional[PixelValues]:
         """Return a tuple (start, write_now, data) corresponding to the
         different parts of ``_pixel_packet``.
         """

adafruit_ble_adafruit/button_service.py

@@ -38,7 +38,7 @@ class ButtonService(AdafruitService):
     measurement_period = AdafruitService.measurement_period_charac(0)
     """Initially 0: send notification only on changes. -1 means stop reading."""
 
-    def set_pressed(self, switch, button_a, button_b):
+    def set_pressed(self, switch: bool, button_a: bool, button_b: bool) -> None:
         """Update the pressed value all at once."""
         pressed = 0
         if switch:
@@ -51,16 +51,16 @@ def set_pressed(self, switch, button_a, button_b):
             self.pressed = pressed
 
     @property
-    def switch(self):
+    def switch(self) -> bool:
         """``True`` when the slide switch is set to the left; ``False`` when to the right."""
         return bool(self.pressed & 0x1)
 
     @property
-    def button_a(self):
+    def button_a(self) -> bool:
         """``True`` when Button A is pressed."""
         return bool(self.pressed & 0x2)
 
     @property
-    def button_b(self):
+    def button_b(self) -> bool:
         """``True`` when Button B is pressed."""
         return bool(self.pressed & 0x4)

adafruit_ble_adafruit/tone_service.py

@@ -22,22 +22,27 @@
 from adafruit_ble.characteristics import Characteristic, ComplexCharacteristic
 from adafruit_ble_adafruit.adafruit_service import AdafruitService
 
+try:
+    from typing import Optional, Tuple
+except ImportError:
+    pass
+
 
 class _TonePacket(ComplexCharacteristic):
     uuid = AdafruitService.adafruit_service_uuid(0xC01)
 
     format = "<HI"
     format_size = struct.calcsize(format)
 
-    def __init__(self):
+    def __init__(self) -> None:
         super().__init__(
             properties=Characteristic.WRITE,
             read_perm=Attribute.NO_ACCESS,
             max_length=self.format_size,
             fixed_length=True,
         )
 
-    def bind(self, service):
+    def bind(self, service: "ToneService") -> PacketBuffer:
         """Binds the characteristic to the given Service."""
         bound_characteristic = super().bind(service)
         return PacketBuffer(bound_characteristic, buffer_size=1)
@@ -54,20 +59,20 @@ class ToneService(AdafruitService):
     if duration == 0, play indefinitely.
     """
 
-    def __init__(self, service=None):
+    def __init__(self, service: Optional["ToneService"] = None) -> None:
         super().__init__(service=service)
         self._tone_packet_buf = bytearray(_TonePacket.format_size)
 
     @property
-    def tone(self):
+    def tone(self) -> Optional[Tuple[int, int]]:
         """Return (frequency, duration), or None if no value available"""
         buf = self._tone_packet_buf
         if self._tone_packet.readinto(buf) == 0:
             # No new values available.
             return None
         return struct.unpack(_TonePacket.format, buf)
 
-    def play(self, frequency, duration):
+    def play(self, frequency: int, duration: float) -> None:
         """
         Frequency is in Hz. If frequency == 0, a tone being played is turned off.
         Duration is in seconds. If duration == 0, play indefinitely.