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

Add typing, correct advanced example filename

Author: FoamyGuy

adafruit_cap1188/cap1188.py

@@ -29,6 +29,11 @@
 
 from micropython import const
 
+try:
+    from typing import Tuple, Union
+except ImportError:
+    pass
+
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_CAP1188.git"
 
@@ -73,41 +78,41 @@ class CAP1188_Channel:
     """Helper class to represent a touch channel on the CAP1188. Not meant to
     be used directly."""
 
-    def __init__(self, cap1188, pin):
+    def __init__(self, cap1188: "CAP1188", pin: int) -> None:
         self._cap1188 = cap1188
         self._pin = pin
 
     @property
-    def value(self):
+    def value(self) -> bool:
         """Whether the pin is being touched or not."""
         return self._cap1188.touched() & (1 << self._pin - 1) != 0
 
     @property
-    def raw_value(self):
+    def raw_value(self) -> int:
         """The raw touch measurement."""
         return self._cap1188.delta_count(self._pin)
 
     @property
-    def threshold(self):
+    def threshold(self) -> int:
         """The touch threshold value."""
         return self._cap1188._read_register(_CAP1188_THESHOLD_1 + self._pin - 1)
 
     @threshold.setter
-    def threshold(self, value):
+    def threshold(self, value: int) -> None:
         value = int(value)
         if not 0 <= value <= 127:
             raise ValueError("Threshold value must be in range 0 to 127.")
         self._cap1188._write_register(_CAP1188_THESHOLD_1 + self._pin - 1, value)
 
-    def recalibrate(self):
+    def recalibrate(self) -> None:
         """Perform a self recalibration."""
         self._cap1188.recalibrate_pins(1 << self._pin - 1)
 
 
 class CAP1188:
     """CAP1188 driver base, must be extended for I2C/SPI interfacing."""
 
-    def __init__(self):
+    def __init__(self) -> None:
         mid = self._read_register(_CAP1188_MANU_ID)
         if mid != _CAP1188_MID:
             raise RuntimeError(
@@ -124,7 +129,7 @@ def __init__(self):
         self._write_register(0x2F, 0x10)  # turn off input-1-sets-all-inputs feature
         self.recalibrate()
 
-    def __getitem__(self, key):
+    def __getitem__(self, key: int) -> CAP1188_Channel:
         pin = key
         index = key - 1
         if pin < 1 or pin > 8:
@@ -134,12 +139,12 @@ def __getitem__(self, key):
         return self._channels[index]
 
     @property
-    def touched_pins(self):
+    def touched_pins(self) -> Tuple[bool, bool, bool, bool, bool, bool, bool, bool]:
         """A tuple of touched state for all pins."""
         touched = self.touched()
         return tuple(bool(touched >> i & 1) for i in range(8))
 
-    def touched(self):
+    def touched(self) -> int:
         """Return 8 bit value representing touch state of all pins."""
         # clear the INT bit and any previously touched pins
         current = self._read_register(_CAP1188_MAIN_CONTROL)
@@ -148,20 +153,20 @@ def touched(self):
         return self._read_register(_CAP1188_INPUT_STATUS)
 
     @property
-    def sensitivity(self):
+    def sensitivity(self) -> int:
         """The sensitvity of touch detections. Range is 1 (least) to 128 (most)."""
         return _SENSITIVITY[self._read_register(_CAP1188_SENSITIVTY) >> 4 & 0x07]
 
     @sensitivity.setter
-    def sensitivity(self, value):
+    def sensitivity(self, value: int) -> None:
         if value not in _SENSITIVITY:
             raise ValueError("Sensitivty must be one of: {}".format(_SENSITIVITY))
         value = _SENSITIVITY.index(value) << 4
         new_setting = self._read_register(_CAP1188_SENSITIVTY) & 0x8F | value
         self._write_register(_CAP1188_SENSITIVTY, new_setting)
 
     @property
-    def averaging(self):
+    def averaging(self) -> int:
         """Samples that are taken for all active channels during the
         sensor cycle. All samples are taken consecutively on
         the same channel before the next channel is sampled
@@ -179,7 +184,7 @@ def averaging(self):
         return _AVG[register >> 4 & 0x07]
 
     @averaging.setter
-    def averaging(self, value):
+    def averaging(self, value: int) -> None:
         if value not in _AVG:
             raise ValueError("Avg must be one of: {}".format(_AVG))
         register = self._read_register(_CAP1188_AVERAGING)
@@ -189,7 +194,7 @@ def averaging(self, value):
         self._write_register(_CAP1188_AVERAGING, avg_value)
 
     @property
-    def sample(self):
+    def sample(self) -> str:
         """Determines the overall cycle time for all  measured  channels
         during normal operation. All measured channels are sampled at the
         beginning of the cycle time. If additional time is remaining, then
@@ -201,7 +206,7 @@ def sample(self):
         return _SAMP_TIME[register >> 2 & 0x03]
 
     @sample.setter
-    def sample(self, value):
+    def sample(self, value: str) -> None:
         if value not in _SAMP_TIME:
             raise ValueError("Sample Time must be one of: {}".format(_SAMP_TIME))
         register = self._read_register(_CAP1188_AVERAGING)
@@ -211,7 +216,7 @@ def sample(self, value):
         self._write_register(_CAP1188_AVERAGING, sample_value)
 
     @property
-    def cycle(self):
+    def cycle(self) -> str:
         """The programmed cycle time is only maintained if
         the total averaging time for all samples is less
         than the programmed cycle. The AVG[2:0] bits will
@@ -226,7 +231,7 @@ def cycle(self):
         return _CYCLE_TIME[register & 0x03]
 
     @cycle.setter
-    def cycle(self, value):
+    def cycle(self, value: str) -> None:
         if value not in _CYCLE_TIME:
             raise ValueError("Cycle Time must be one of: {}".format(_CYCLE_TIME))
         register = self._read_register(_CAP1188_AVERAGING)
@@ -236,26 +241,26 @@ def cycle(self, value):
         self._write_register(_CAP1188_AVERAGING, cycle_value)
 
     @property
-    def thresholds(self):
+    def thresholds(self) -> Tuple[int, int, int, int, int, int, int, int]:
         """Touch threshold value for all channels."""
         return self.threshold_values()
 
     @thresholds.setter
-    def thresholds(self, value):
+    def thresholds(self, value: int) -> None:
         value = int(value)
         if not 0 <= value <= 127:
             raise ValueError("Threshold value must be in range 0 to 127.")
         self._write_block(_CAP1188_THESHOLD_1, bytearray((value,) * 8))
 
-    def threshold_values(self):
+    def threshold_values(self) -> Tuple[int, int, int, int, int, int, int, int]:
         """Return tuple of touch threshold values for all channels."""
         return tuple(self._read_block(_CAP1188_THESHOLD_1, 8))
 
-    def recalibrate(self):
+    def recalibrate(self) -> None:
         """Perform a self recalibration on all the pins."""
         self.recalibrate_pins(0xFF)
 
-    def delta_count(self, pin):
+    def delta_count(self, pin: int) -> int:
         """Return the 8 bit delta count value for the channel."""
         if pin < 1 or pin > 8:
             raise IndexError("Pin must be a value 1-8.")
@@ -264,22 +269,22 @@ def delta_count(self, pin):
         raw_value = raw_value - 256 if raw_value & 128 else raw_value
         return raw_value
 
-    def recalibrate_pins(self, mask):
+    def recalibrate_pins(self, mask: int) -> None:
         """Recalibrate pins specified by bit mask."""
         self._write_register(_CAP1188_CAL_ACTIVATE, mask)
 
-    def _read_register(self, address):
+    def _read_register(self, address: int) -> int:
         """Return 8 bit value of register at address."""
         raise NotImplementedError
 
-    def _write_register(self, address, value):
+    def _write_register(self, address: int, value: int) -> None:
         """Write 8 bit value to register at address."""
         raise NotImplementedError
 
-    def _read_block(self, start, length):
+    def _read_block(self, start: int, length: int) -> bytearray:
         """Return byte array of values from start address to length."""
         raise NotImplementedError
 
-    def _write_block(self, start, data):
+    def _write_block(self, start: int, data: Union[bytearray, bytes]) -> None:
         """Write out data beginning at start address."""
         raise NotImplementedError

adafruit_cap1188/i2c.py

@@ -32,6 +32,12 @@
 from micropython import const
 from adafruit_cap1188.cap1188 import CAP1188
 
+try:
+    from typing import Union
+    from busio import I2C
+except ImportError:
+    pass
+
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_CAP1188.git"
 
@@ -41,34 +47,34 @@
 class CAP1188_I2C(CAP1188):
     """Driver for the CAP1188 connected over I2C."""
 
-    def __init__(self, i2c, address=_CAP1188_DEFAULT_ADDRESS):
+    def __init__(self, i2c: I2C, address: int = _CAP1188_DEFAULT_ADDRESS) -> None:
         self._i2c = i2c_device.I2CDevice(i2c, address)
         self._buf = bytearray(2)
         super().__init__()
 
-    def _read_register(self, address):
+    def _read_register(self, address: int) -> int:
         """Return 8 bit value of register at address."""
         self._buf[0] = address
         with self._i2c as i2c:
             i2c.write_then_readinto(self._buf, self._buf, out_end=1, in_start=1)
         return self._buf[1]
 
-    def _write_register(self, address, value):
+    def _write_register(self, address: int, value: int) -> None:
         """Write 8 bit value to registter at address."""
         self._buf[0] = address
         self._buf[1] = value
         with self._i2c as i2c:
             i2c.write(self._buf)
 
-    def _read_block(self, start, length):
+    def _read_block(self, start: int, length: int) -> bytearray:
         """Return byte array of values from start address to length."""
         result = bytearray(length)
         with self._i2c as i2c:
             i2c.write(bytes((start,)))
             i2c.readinto(result)
         return result
 
-    def _write_block(self, start, data):
+    def _write_block(self, start: int, data: Union[bytearray, bytes]) -> None:
         """Write out data beginning at start address."""
         with self._i2c as i2c:
             i2c.write(bytes((start,)) + data)

adafruit_cap1188/spi.py

@@ -39,16 +39,23 @@
 _CAP1188_SPI_WRITE_DATA = const(0x7E)
 _CAP1188_SPI_READ_DATA = const(0x7F)
 
+try:
+    from typing import Union
+    from busio import SPI
+    from digitalio import DigitalInOut
+except ImportError:
+    pass
+
 
 class CAP1188_SPI(CAP1188):
     """Driver for the CAP1188 connected over SPI."""
 
-    def __init__(self, spi, cs):
+    def __init__(self, spi: SPI, cs: DigitalInOut) -> None:
         self._spi = spi_device.SPIDevice(spi, cs)
         self._buf = bytearray(4)
         super().__init__()
 
-    def _read_register(self, address):
+    def _read_register(self, address: int) -> int:
         # pylint: disable=no-member
         """Return 8 bit value of register at address."""
         self._buf[0] = _CAP1188_SPI_SET_ADDR
@@ -58,7 +65,7 @@ def _read_register(self, address):
             spi.write_readinto(self._buf, self._buf)
         return self._buf[3]
 
-    def _write_register(self, address, value):
+    def _write_register(self, address: int, value: int) -> None:
         # pylint: disable=no-member
         """Write 8 bit value to registter at address."""
         self._buf[0] = _CAP1188_SPI_SET_ADDR
@@ -68,7 +75,7 @@ def _write_register(self, address, value):
         with self._spi as spi:
             spi.write(self._buf)
 
-    def _read_block(self, start, length):
+    def _read_block(self, start: int, length: int) -> bytearray:
         # pylint: disable=no-member
         """Return byte array of values from start address to length."""
         self._buf[0] = _CAP1188_SPI_SET_ADDR
@@ -80,7 +87,7 @@ def _read_block(self, start, length):
             spi.write_readinto(result, result)
         return result
 
-    def _write_block(self, start, data):
+    def _write_block(self, start: int, data: Union[bytearray, bytes]) -> None:
         # pylint: disable=no-member
         """Write out data beginning at start address."""
         self._buf[0] = _CAP1188_SPI_SET_ADDR

docs/examples.rst

@@ -13,6 +13,6 @@ Advance test
 This example show the new feature included in the library allowing the possibilite the
 configure the averaging, cycle and sample. For reference please see Sensor Datasheet.
 
-.. literalinclude:: ../examples/cap118_advancedtest.py
-    :caption: examples/cap118_advancedtest.py
+.. literalinclude:: ../examples/cap1188_advancedtest.py
+    :caption: examples/cap1188_advancedtest.py
     :linenos: