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

Add type annotations

Author: FoamyGuy

adafruit_mlx90393.py

@@ -34,6 +34,13 @@
 from adafruit_bus_device.i2c_device import I2CDevice
 from micropython import const
 
+try:
+    from typing import Tuple
+    from circuitpython_typing import ReadableBuffer
+    from busio import I2C
+except ImportError:
+    pass
+
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_MLX90393.git"
 
@@ -162,6 +169,9 @@ class MLX90393:  # pylint: disable=too-many-instance-attributes
     :param i2c_bus: The I2C bus the device is connected to
     :param int address: The I2C device address. Defaults to :const:`0x0C`
     :param int gain: The gain level to apply. Defaults to :const:`GAIN_1X`
+    :param int resolution: The resolution level to use.  Defaults to :const:`RESOLUTION_16`
+    :param int filt: The filter to use. Defaults to :const:`FILTER_7`
+    :param int oversampling: The oversampleing setting to use. Defaults to :const:`OSR_3`
     :param bool debug: Enable debug output. Defaults to `False`
 
 
@@ -190,16 +200,16 @@ class MLX90393:  # pylint: disable=too-many-instance-attributes
 
     """
 
-    def __init__(
+    def __init__(  # pylint: disable=too-many-arguments
         self,
-        i2c_bus,
-        address=0x0C,
-        gain=GAIN_1X,
-        resolution=RESOLUTION_16,
-        filt=FILTER_7,
-        oversampling=OSR_3,
-        debug=False,
-    ):  # pylint: disable=too-many-arguments
+        i2c_bus: I2C,
+        address: int = 0x0C,
+        gain: int = GAIN_1X,
+        resolution: int = RESOLUTION_16,
+        filt: int = FILTER_7,
+        oversampling: int = OSR_3,
+        debug: bool = False,
+    ) -> None:
         self.i2c_device = I2CDevice(i2c_bus, address)
         self._debug = debug
         self._status_last = 0
@@ -225,12 +235,12 @@ def __init__(
         # Set gain to the supplied level
         self.gain = self._gain_current
 
-    def _transceive(self, payload, rxlen=0):
+    def _transceive(self, payload: ReadableBuffer, rxlen: int = 0) -> bytearray:
         """
         Writes the specified 'payload' to the sensor
         Returns the results of the write attempt.
 
-        :param bytes payload: The byte array to write to the sensor
+        :param ReadableBuffer payload: The byte array to write to the sensor
         :param int rxlen: numbers of bytes to read back. Defaults to :const:`0`
 
         """
@@ -266,21 +276,21 @@ def _transceive(self, payload, rxlen=0):
         return data
 
     @property
-    def last_status(self):
+    def last_status(self) -> int:
         """
         The last status byte received from the sensor.
         """
         return self._status_last
 
     @property
-    def gain(self):
+    def gain(self) -> int:
         """
         The gain setting for the device.
         """
         return self._gain_current
 
     @gain.setter
-    def gain(self, value):
+    def gain(self, value: int) -> None:
         if value > GAIN_1X or value < GAIN_5X:
             raise ValueError("Invalid GAIN setting")
         if self._debug:
@@ -298,36 +308,36 @@ def gain(self, value):
         )
 
     @property
-    def resolution_x(self):
+    def resolution_x(self) -> int:
         """The X axis resolution."""
         return self._res_x
 
     @resolution_x.setter
-    def resolution_x(self, resolution):
+    def resolution_x(self, resolution: int) -> None:
         self._set_resolution(0, resolution)
         self._res_x = resolution
 
     @property
-    def resolution_y(self):
+    def resolution_y(self) -> int:
         """The Y axis resolution."""
         return self._res_y
 
     @resolution_y.setter
-    def resolution_y(self, resolution):
+    def resolution_y(self, resolution: int) -> None:
         self._set_resolution(1, resolution)
         self._res_y = resolution
 
     @property
-    def resolution_z(self):
+    def resolution_z(self) -> int:
         """The Z axis resolution."""
         return self._res_z
 
     @resolution_z.setter
-    def resolution_z(self, resolution):
+    def resolution_z(self, resolution: int) -> None:
         self._set_resolution(2, resolution)
         self._res_z = resolution
 
-    def _set_resolution(self, axis, resolution):
+    def _set_resolution(self, axis: int, resolution: int) -> None:
         if resolution not in (
             RESOLUTION_16,
             RESOLUTION_17,
@@ -343,12 +353,12 @@ def _set_resolution(self, axis, resolution):
         self.write_reg(_CMD_REG_CONF3, reg)
 
     @property
-    def filter(self):
+    def filter(self) -> int:
         """The filter level."""
         return self._filter
 
     @filter.setter
-    def filter(self, level):
+    def filter(self, level: int) -> None:
         if level not in range(8):
             raise ValueError("Incorrect filter level.")
         reg = self.read_reg(_CMD_REG_CONF3)
@@ -358,12 +368,12 @@ def filter(self, level):
         self._filter = level
 
     @property
-    def oversampling(self):
+    def oversampling(self) -> int:
         """The oversampling level."""
         return self._osr
 
     @oversampling.setter
-    def oversampling(self, level):
+    def oversampling(self, level: int) -> None:
         if level not in range(4):
             raise ValueError("Incorrect oversampling level.")
         reg = self.read_reg(_CMD_REG_CONF3)
@@ -372,7 +382,7 @@ def oversampling(self, level):
         self.write_reg(_CMD_REG_CONF3, reg)
         self._osr = level
 
-    def display_status(self):
+    def display_status(self) -> None:
         """
         Prints out the content of the last status byte in a human-readable
         format.
@@ -389,9 +399,11 @@ def display_status(self):
         print("Reset status             :", (self._status_last & (1 << 2)) > 0)
         print("Response bytes available :", avail)
 
-    def read_reg(self, reg):
+    def read_reg(self, reg: int) -> int:
         """
         Gets the current value of the specified register.
+
+        :param int reg: The register to read
         """
         # Write 'value' to the specified register
         payload = bytes([_CMD_RR, reg << 2])
@@ -411,9 +423,12 @@ def read_reg(self, reg):
             print("\t  Status :", hex(data[0]))
         return val
 
-    def write_reg(self, reg, value):
+    def write_reg(self, reg: int, value: int) -> None:
         """
         Writes the 16-bit value to the supplied register.
+
+        :param int reg: The register to write to
+        :param int value: The value to write to the register
         """
         self._transceive(
             bytes(
@@ -426,7 +441,7 @@ def write_reg(self, reg, value):
             )
         )
 
-    def reset(self):
+    def reset(self) -> None:
         """
         Performs a software reset of the sensor.
         """
@@ -442,7 +457,7 @@ def reset(self):
         return self._status_last
 
     @property
-    def read_data(self):
+    def read_data(self) -> Tuple[int, int, int]:
         """
         Reads a single X/Y/Z sample from the magnetometer.
         """
@@ -469,7 +484,7 @@ def read_data(self):
         return m_x, m_y, m_z
 
     # pylint: disable=no-self-use
-    def _unpack_axis_data(self, resolution, data):
+    def _unpack_axis_data(self, resolution: int, data: ReadableBuffer) -> int:
         # see datasheet
         if resolution == RESOLUTION_19:
             (value,) = struct.unpack(">H", data)
@@ -482,7 +497,7 @@ def _unpack_axis_data(self, resolution, data):
         return value
 
     @property
-    def magnetic(self):
+    def magnetic(self) -> Tuple[float, float, float]:
         """
         The processed magnetometer sensor values.
         A 3-tuple of X, Y, Z axis values in microteslas that are signed floats.

requirements.txt

@@ -2,5 +2,6 @@
 #
 # SPDX-License-Identifier: Unlicense
 
-Adafruit-Blinka
+Adafruit-Blinka>=7.0.0
 adafruit-circuitpython-busdevice
+adafruit-circuitpython-typing

setup.py

@@ -34,7 +34,11 @@
     # Author details
     author="Adafruit Industries",
     author_email="[email protected]",
-    install_requires=["Adafruit-Blinka", "adafruit-circuitpython-busdevice"],
+    install_requires=[
+        "Adafruit-Blinka>=7.0.0",
+        "adafruit-circuitpython-busdevice",
+        "adafruit-circuitpython-typing",
+    ],
     # Choose your license
     license="MIT",
     # See https://pypi.python.org/pypi?%3Aaction=list_classifiers