api/common/LightArray: add blink and animate

pybricks/_common.py

@@ -495,14 +495,14 @@ class LightArray:
         """
         pass
 
-    def on(self, *brightness):
+    def on(self, brightness):
         """Turns on the lights at the specified brightness.
 
         Arguments:
-            *brightness (:ref:`brightness`, ...):
-                Brightness of each light, in the order shown above. If you
-                give only one value, all lights will get that same brightness.
-
+            brightness (tuple of :ref:`brightness`):
+                Brightness of each light, in the order shown above. If you give
+                one brightness value instead of a tuple, all lights get the
+                same brightness.
         """
         pass
 
@@ -510,6 +510,32 @@ class LightArray:
         """Turns off all the lights."""
         pass
 
+    def blink(self, durations):
+        """Blinks all lights by turning them on and off for given durations.
+
+        The lights keep blinking indefinitely while the rest of your
+        program keeps running.
+
+        This method provides a simple way to make basic but useful patterns.
+        For more generic and smooth patterns, use :meth:`.animate` instead.
+
+        Arguments:
+            (list): List of (:ref:`time`) values of the
+                form ``[on_1, off_1, on_2, off_2, ...]``.
+        """
+
+    def animate(self, brightness_values, interval):
+        """Animates the lights with a list of brightness tuples. The next
+        brightness tuple from the list is activated after the given interval.
+
+        The animation runs in the background while the rest of your program
+        keeps running. When the animation completes, it repeats.
+
+        Arguments:
+            brightness_values (list): List of :ref:`brightness` tuples.
+            interval (:ref:`time`): Time between brightness updates.
+        """
+
 
 class LightGrid:
     """Control a rectangular grid of single-color lights."""