Merge pull request #23 from BiffoBear/Add_typing

Add typing

Author: FoamyGuy

adafruit_rgbled.py

@@ -18,6 +18,15 @@
 * Adafruit CircuitPython firmware for the supported boards:
   https://github.com/adafruit/circuitpython/releases
 """
+try:
+    from typing import Union, Optional, Type
+    from types import TracebackType
+    from microcontroller import Pin
+    from adafruit_pca9685 import PWMChannel
+    from circuitpython_typing.led import ColorBasedColorUnion
+except ImportError:
+    pass
+
 from pwmio import PWMOut
 
 __version__ = "0.0.0+auto.0"
@@ -26,24 +35,9 @@
 
 class RGBLED:
     """
-    Creates a RGBLED object given three physical pins or PWMOut objects.
-
-    :param red_pin: The physical pin connected to a red LED anode.
-    :type ~microcontroller.Pin: Microcontroller's red_pin.
-    :type pwmio.PWMOut: PWMOut object associated with red_pin.
-    :type PWMChannel: PCA9685 PWM channel associated with red_pin.
-    :param green_pin: The physical pin connected to a green LED anode.
-    :type ~microcontroller.Pin: Microcontroller's green_pin.
-    :type pwmio.PWMOut: PWMOut object associated with green_pin.
-    :type PWMChannel: PCA9685 PWM channel associated with green_pin.
-    :param blue_pin: The physical pin connected to a blue LED anode.
-    :type ~microcontroller.Pin: Microcontroller's blue_pin.
-    :type pwmio.PWMOut: PWMOut object associated with blue_pin.
-    :type PWMChannel: PCA9685 PWM channel associated with blue_pin.
-    :param bool invert_pwm: False if the RGB LED is common cathode,
-        true if the RGB LED is common anode.
+    Create an RGBLED object given three physical pins or PWMOut objects.
 
-    Example for setting a RGB LED using a RGB Tuple (Red, Green, Blue):
+    Example for setting an RGB LED using an RGB Tuple (Red, Green, Blue):
 
     .. code-block:: python
 
@@ -58,7 +52,7 @@ class RGBLED:
         led = adafruit_rgbled.RGBLED(RED_LED, BLUE_LED, GREEN_LED)
         led.color = (255, 0, 0)
 
-    Example for setting a RGB LED using a 24-bit integer (hex syntax):
+    Example for setting an RGB LED using a 24-bit integer (hex syntax):
 
     .. code-block:: python
 
@@ -69,11 +63,11 @@ class RGBLED:
         GREEN_LED = board.D6
         BLUE_LED = board.D7
 
-        # Create a RGB LED object
+        # Create an RGB LED object
         led = adafruit_rgbled.RGBLED(RED_LED, BLUE_LED, GREEN_LED)
         led.color = 0x100000
 
-    Example for setting a RGB LED using a ContextManager:
+    Example for setting an RGB LED using a ContextManager:
 
     .. code-block:: python
 
@@ -91,9 +85,23 @@ class RGBLED:
         with adafruit_rgbled.RGBLED(board.D5, board.D6, board.D7, invert_pwm=True) as rgb_led:
             rgb_led.color = (0, 255, 0)
 
+    :param Union[Pin, PWMOut, "PWMChannel"] red_pin:
+        The connection to the red LED.
+    :param Union[Pin, PWMOut, "PWMChannel"] green_pin:
+        The connection to the green LED.
+    :param Union[Pin, PWMOut, "PWMChannel"] blue_pin:
+        The connection to the blue LED.
+    :param bool invert_pwm: False if the RGB LED is common cathode,
+        True if the RGB LED is common anode. Defaults to False.
     """
 
-    def __init__(self, red_pin, green_pin, blue_pin, invert_pwm=False):
+    def __init__(
+        self,
+        red_pin: Union[Pin, PWMOut, PWMChannel],
+        green_pin: Union[Pin, PWMOut, PWMChannel],
+        blue_pin: Union[Pin, PWMOut, PWMChannel],
+        invert_pwm: bool = False,
+    ) -> None:
         self._rgb_led_pins = [red_pin, green_pin, blue_pin]
         for i in range(  # pylint: disable=consider-using-enumerate
             len(self._rgb_led_pins)
@@ -109,28 +117,41 @@ def __init__(self, red_pin, green_pin, blue_pin, invert_pwm=False):
         self._current_color = (0, 0, 0)
         self.color = self._current_color
 
-    def __enter__(self):
+    def __enter__(self) -> "RGBLED":
         return self
 
-    def __exit__(self, exception_type, exception_value, traceback):
+    def __exit__(
+        self,
+        exception_type: Optional[Type[type]],
+        exception_value: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> None:
         self.deinit()
 
-    def deinit(self):
+    def deinit(self) -> None:
         """Turn the LEDs off, deinit pwmout and release hardware resources."""
         for pin in self._rgb_led_pins:
             pin.deinit()  # pylint: disable=no-member
         self._current_color = (0, 0, 0)
 
     @property
-    def color(self):
-        """Returns the RGB LED's current color."""
+    def color(self) -> ColorBasedColorUnion:
+        """
+        Sets the RGB LED to a desired color.
+
+        :param ColorBasedColorUnion value: RGB LED desired value - can be a RGB
+            tuple of values 0 - 255 or a 24-bit integer. e.g. (255, 64, 35) and 0xff4023
+            are equivalent.
+
+        :returns Union[int, Tuple[int, int, int]]: The current LED color setting.
+
+        :raises ValueError: If the input is an int > 0xffffff.
+        :raises TypeError: If the input is not an integer or a tuple.
+        """
         return self._current_color
 
     @color.setter
-    def color(self, value):
-        """Sets the RGB LED to a desired color.
-        :param type value: RGB LED desired value - can be a RGB tuple or a 24-bit integer.
-        """
+    def color(self, value: ColorBasedColorUnion):
         self._current_color = value
         if isinstance(value, tuple):
             for i in range(0, 3):
@@ -151,4 +172,4 @@ def color(self, value):
                     rgb[color] -= 65535
                 self._rgb_led_pins[color].duty_cycle = abs(rgb[color])
         else:
-            raise ValueError("Color must be a tuple or 24-bit integer value.")
+            raise TypeError("Color must be a tuple or 24-bit integer value.")

requirements.txt

@@ -3,3 +3,5 @@
 # SPDX-License-Identifier: Unlicense
 
 Adafruit-Blinka
+adafruit-circuitpython-typing~=1.4
+adafruit-circuitpython-pca9685