Reformatted, finished annotating and documenting

Author: Alec Delaney

adafruit_pcf8575.py

@@ -1,6 +1,7 @@
 # SPDX-FileCopyrightText: Copyright (c) 2022 ladyada for Adafruit Industries
 #
 # SPDX-License-Identifier: MIT
+
 """
 `adafruit_pcf8575`
 ================================================================================
@@ -26,8 +27,8 @@
 """
 
 try:
-    # This is only needed for typing
-    import busio  # pylint: disable=unused-import
+    from typing import Optional
+    import busio
 except ImportError:
     pass
 
@@ -41,9 +42,10 @@
 
 PCF8575_I2CADDR_DEFAULT: int = const(0x20)  # Default I2C address
 
+
 class PCF8575:
-    """
-    Interface library for PCF8575 GPIO expanders
+    """Interface library for PCF8575 GPIO expanders
+
     :param ~busio.I2C i2c_bus: The I2C bus the PCF8575 is connected to.
     :param int address: The I2C device address. Default is :const:`0x20`
     """
@@ -55,29 +57,39 @@ def __init__(
         self._writebuf = bytearray([0, 0])
         self._readbuf = bytearray([0, 0])
 
-    def get_pin(self, pin):
+    def get_pin(self, pin: int) -> "DigitalInOut":
         """Convenience function to create an instance of the DigitalInOut class
         pointing at the specified pin of this PCF8575 device.
+
         :param int pin: pin to use for digital IO, 0 to 15
         """
         assert 0 <= pin <= 15
         return DigitalInOut(pin, self)
 
-    def write_gpio(self, val):
-        """Write a full 16-bit value to the GPIO register"""
+    def write_gpio(self, val: int) -> None:
+        """Write a full 16-bit value to the GPIO register
+
+        :param int val: The value to write to the register
+        """
+
         self._writebuf[0] = val & 0xFF
         self._writebuf[1] = (val >> 8) & 0xFF
         with self.i2c_device as i2c:
             i2c.write(self._writebuf)
 
-    def read_gpio(self):
+    def read_gpio(self) -> int:
         """Read the full 16-bits of data from the GPIO register"""
         with self.i2c_device as i2c:
             i2c.readinto(self._readbuf)
         return self._readbuf[0] | (self._readbuf[1] << 8)
 
-    def write_pin(self, pin, val):
-        """Set a single GPIO pin high/pulled-up or driven low"""
+    def write_pin(self, pin: int, val: bool) -> None:
+        """Set a single GPIO pin high/pulled-up or driven low
+
+        :param int pin: The pin number
+        :param bool vale: The state to set
+        """
+
         buff = self._writebuf[0] | (self._writebuf[1] << 8)
         if val:
             # turn on the pullup (write high)
@@ -86,8 +98,12 @@ def write_pin(self, pin, val):
             # turn on the transistor (write low)
             self.write_gpio(buff & ~(1 << pin))
 
-    def read_pin(self, pin):
-        """Read a single GPIO pin as high/pulled-up or driven low"""
+    def read_pin(self, pin: int) -> bool:
+        """Read a single GPIO pin as high/pulled-up or driven low
+
+        :param int pin: The pin number
+        """
+
         return (self.read_gpio() >> pin) & 0x1
 
 
@@ -102,15 +118,22 @@ def read_pin(self, pin):
 class DigitalInOut:
     """Digital input/output of the PCF8575.  The interface is exactly the
     same as the digitalio.DigitalInOut class, however:
+
       * PCF8575 does not support pull-down resistors
       * PCF8575 does not actually have a sourcing transistor, instead there's
-      an internal pullup
+        an internal pullup
+
     Exceptions will be thrown when attempting to set unsupported pull
     configurations.
     """
 
-    def __init__(self, pin_number, pcf):
-        """Specify the pin number of the PCF8575 0..15, and instance."""
+    def __init__(self, pin_number: int, pcf: PCF8575) -> None:
+        """Specify the pin number of the PCF8575 0..15, and instance.
+
+        :param int pin_number: The pin number
+        :param PCF8575 pfc: The associated PCF8575 instance
+        """
+
         self._pin = pin_number
         self._pcf = pcf
         self._dir = (
@@ -122,44 +145,53 @@ def __init__(self, pin_number, pcf):
     # is unused by this class).  Do not remove them, instead turn off pylint
     # in this case.
     # pylint: disable=unused-argument
-    def switch_to_output(self, value=False, **kwargs):
+    def switch_to_output(self, value: bool = False, **kwargs) -> None:
         """Switch the pin state to a digital output with the provided starting
         value (True/False for high or low, default is False/low).
+
+        Note that keyword arguments are not parsed, and only included for
+        compatibility with code expecting :py:class:`digitalio.DigitalInOut`.
+
+        :param bool value: The value to set upon switching to output; default
+            is ``False``
         """
         self.direction = digitalio.Direction.OUTPUT
         self.value = value
 
-    def switch_to_input(self, pull=None, **kwargs):
+    def switch_to_input(self, pull: Optional[digitalio.Pull] = None, **kwargs) -> None:
         """Switch the pin state to a digital input which is the same as
         setting the light pullup on.  Note that true tri-state or
         pull-down resistors are NOT supported!
+
+        Note that keyword arguments are not parsed, and only included for
+        compatibility with code expecting :py:class:`digitalio.DigitalInOut`.
         """
+
         self.direction = digitalio.Direction.INPUT
         self.pull = pull
 
     # pylint: enable=unused-argument
 
     @property
-    def value(self):
-        """The value of the pin, either True for high/pulled-up or False for
-        low.
+    def value(self) -> bool:
+        """The value of the pin, either ``True`` for high/pulled-up or
+        ``False`` for low.
         """
         return self._pcf.read_pin(self._pin)
 
     @value.setter
-    def value(self, val):
+    def value(self, val: bool) -> None:
         self._pcf.write_pin(self._pin, val)
 
     @property
-    def direction(self):
-        """
-        Setting a pin to OUTPUT drives it low, setting it to
+    def direction(self) -> digitalio.Direction:
+        """Setting a pin to OUTPUT drives it low, setting it to
         an INPUT enables the light pullup.
         """
         return self._dir
 
     @direction.setter
-    def direction(self, val):
+    def direction(self, val: digitalio.Direction) -> None:
         if val == digitalio.Direction.INPUT:
             # for inputs, turn on the pullup (write high)
             self._pcf.write_pin(self._pin, True)
@@ -172,14 +204,15 @@ def direction(self, val):
             raise ValueError("Expected INPUT or OUTPUT direction!")
 
     @property
-    def pull(self):
+    def pull(self) -> digitalio.Pull:
         """
-        Pull-up is always activated so always return the same thing
+        Pull-up is always activated so this will always return the same,
+        thing: :py:attr:`digitalio.Pull.UP`
         """
         return digitalio.Pull.UP
 
     @pull.setter
-    def pull(self, val):
+    def pull(self, val: digitalio.Pull) -> None:
         if val is digitalio.Pull.UP:
             # for inputs, turn on the pullup (write high)
             self._pcf.write_pin(self._pin, True)

docs/conf.py

@@ -30,8 +30,8 @@
 
 
 intersphinx_mapping = {
-    "python": ("https://docs.python.org/3", None),"BusDevice": ("https://docs.circuitpython.org/projects/busdevice/en/latest/", None),
-    
+    "python": ("https://docs.python.org/3", None),
+    "BusDevice": ("https://docs.circuitpython.org/projects/busdevice/en/latest/", None),
     "CircuitPython": ("https://docs.circuitpython.org/en/latest/", None),
 }