pybricks.parameters: Add typing.

src/pybricks/parameters.py

@@ -1,10 +1,17 @@
 # SPDX-License-Identifier: MIT
-# Copyright (c) 2018-2020 The Pybricks Authors
+# Copyright (c) 2018-2022 The Pybricks Authors
 
 """Constant parameters/arguments for the Pybricks API."""
 
+from __future__ import annotations
+
+from typing import Union
 from enum import Enum as _Enum
 
+from .geometry import Matrix
+
+Number = Union[int, float]
+
 
 class _PybricksEnumMeta(type(_Enum)):
     def __dir__(cls):
@@ -30,7 +37,18 @@ class _PybricksEnum(_Enum, metaclass=_PybricksEnumMeta):
 class Color:
     """Light or surface color."""
 
-    def __init__(self, h, s=100, v=100):
+    h: int
+    s: int
+    v: int
+
+    def __init__(self, h: Number, s: Number = 100, v: Number = 100):
+        """Color(h, s=100, v=100)
+
+        Arguments:
+            h (Number, deg): Hue (0--360)
+            s (Number, %): Saturation.
+            v (Number, %): Brightness value.
+        """
         self.h = h % 360
         self.s = max(0, min(s, 100))
         self.v = max(0, min(v, 100))
@@ -38,25 +56,20 @@ class Color:
     def __repr__(self):
         return "Color(h={}, s={}, v={})".format(self.h, self.s, self.v)
 
-    def __eq__(self, other):
-        return (
-            isinstance(other, Color)
-            and self.h == other.h
-            and self.s == other.s
-            and self.v == other.v
-        )
+    def __eq__(self, other: Color) -> bool:
+        ...
 
-    def __mul__(self, scale):
+    def __mul__(self, scale: float) -> Color:
         v = max(0, min(self.v * scale, 100))
         return Color(self.h, self.s, int(v), self.name)
 
-    def __rmul__(self, scale):
+    def __rmul__(self, scale: float) -> Color:
         return self.__mul__(scale)
 
-    def __truediv__(self, scale):
+    def __truediv__(self, scale: float) -> Color:
         return self.__mul__(1 / scale)
 
-    def __floordiv__(self, scale):
+    def __floordiv__(self, scale: int) -> Color:
         return self.__mul__(1 / scale)
 
 
@@ -79,30 +92,30 @@ class Port(_PybricksEnum):
     """Port on the programmable brick or hub."""
 
     # Generic motor/sensor ports
-    A = ord("A")
-    B = ord("B")
-    C = ord("C")
-    D = ord("D")
-    E = ord("E")
-    F = ord("F")
+    A: Port = ord("A")
+    B: Port = ord("B")
+    C: Port = ord("C")
+    D: Port = ord("D")
+    E: Port = ord("E")
+    F: Port = ord("F")
 
     # NXT/EV3 sensor ports
-    S1 = ord("1")
-    S2 = ord("2")
-    S3 = ord("3")
-    S4 = ord("4")
+    S1: Port = ord("1")
+    S2: Port = ord("2")
+    S3: Port = ord("3")
+    S4: Port = ord("4")
 
 
 class Stop(_PybricksEnum):
     """Action after the motor stops."""
 
-    COAST = 0
+    COAST: Port = 0
     """Let the motor move freely."""
 
-    BRAKE = 1
+    BRAKE: Port = 1
     """Passively resist small external forces."""
 
-    HOLD = 2
+    HOLD: Port = 2
     """Keep controlling the motor to hold it at the commanded angle. This is
     only available on motors with encoders."""
 
@@ -110,39 +123,78 @@ class Stop(_PybricksEnum):
 class Direction(_PybricksEnum):
     """Rotational direction for positive speed or angle values."""
 
-    CLOCKWISE = 0
+    CLOCKWISE: Direction = 0
     """A positive speed value should make the motor move clockwise."""
 
-    COUNTERCLOCKWISE = 1
+    COUNTERCLOCKWISE: Direction = 1
     """A positive speed value should make the motor move counterclockwise."""
 
 
 class Button(_PybricksEnum):
     """Buttons on a hub or remote."""
 
-    LEFT_DOWN = 1
-    LEFT_MINUS = 1
-    DOWN = 2
-    RIGHT_DOWN = 3
-    RIGHT_MINUS = 3
-    LEFT = 4
-    CENTER = 5
-    RIGHT = 6
-    LEFT_UP = 7
-    LEFT_PLUS = 7
-    UP = 8
-    BEACON = 8
-    RIGHT_UP = 9
-    RIGHT_PLUS = 9
-    BLUETOOTH = 9
+    LEFT_DOWN: Button = 1
+    LEFT_MINUS: Button = 1
+    DOWN: Button = 2
+    RIGHT_DOWN: Button = 3
+    RIGHT_MINUS: Button = 3
+    LEFT: Button = 4
+    CENTER: Button = 5
+    RIGHT: Button = 6
+    LEFT_UP: Button = 7
+    LEFT_PLUS: Button = 7
+    UP: Button = 8
+    BEACON: Button = 8
+    RIGHT_UP: Button = 9
+    RIGHT_PLUS: Button = 9
+    BLUETOOTH: Button = 9
 
 
 class Side(_PybricksEnum):
     """Side of a hub or a sensor."""
 
-    RIGHT = 6
-    FRONT = 0
-    TOP = 8
-    LEFT = 4
-    BACK = 5
-    BOTTOM = 2
+    RIGHT: Side = 6
+    FRONT: Side = 0
+    TOP: Side = 8
+    LEFT: Side = 4
+    BACK: Side = 5
+    BOTTOM: Side = 2
+
+
+class Icon:
+    UP: Matrix
+    DOWN: Matrix
+    LEFT: Matrix
+    RIGHT: Matrix
+    ARROW_RIGHT_UP: Matrix
+    ARROW_RIGHT_DOWN: Matrix
+    ARROW_LEFT_UP: Matrix
+    ARROW_LEFT_DOWN: Matrix
+    ARROW_UP: Matrix
+    ARROW_DOWN: Matrix
+    ARROW_LEFT: Matrix
+    ARROW_RIGHT: Matrix
+    HAPPY: Matrix
+    SAD: Matrix
+    EYE_LEFT: Matrix
+    EYE_RIGHT: Matrix
+    EYE_LEFT_BLINK: Matrix
+    EYE_RIGHT_BLINK: Matrix
+    EYE_RIGHT_BROW: Matrix
+    EYE_LEFT_BROW: Matrix
+    EYE_LEFT_BROW_UP: Matrix
+    EYE_RIGHT_BROW_UP: Matrix
+    HEART: Matrix
+    PAUSE: Matrix
+    EMPTY: Matrix
+    FULL: Matrix
+    SQUARE: Matrix
+    TRIANGLE_RIGHT: Matrix
+    TRIANGLE_LEFT: Matrix
+    TRIANGLE_UP: Matrix
+    TRIANGLE_DOWN: Matrix
+    CIRCLE: Matrix
+    CLOCKWISE: Matrix
+    COUNTERCLOCKWISE: Matrix
+    TRUE: Matrix
+    FALSE: Matrix