From 2167b9d52dbbe97020acbd59d68c7907cd0fb39b Mon Sep 17 00:00:00 2001 From: Laurens Valk Date: Fri, 27 May 2022 20:00:11 +0200 Subject: [PATCH] pybricks.common.ColorLight: Add typing. Also remove pybricks.common.Light which isn't used anywhere. pupdevices.Light is a standalone light that does not support animations or blinks, so don't inherit from this nonexistent class. Also remove the ColorLight.reset() method which was never implemented. --- doc/common/conf.py | 1 + src/pybricks/_common.py | 83 ++++++++++---------------------------- src/pybricks/_common.pyi | 10 ----- src/pybricks/pupdevices.py | 19 ++++++++- 4 files changed, 39 insertions(+), 74 deletions(-) diff --git a/doc/common/conf.py b/doc/common/conf.py index b292a14..f121b60 100644 --- a/doc/common/conf.py +++ b/doc/common/conf.py @@ -323,6 +323,7 @@ def on_missing_reference(app, env, node, contnode): "mA", "ms", "mNm", + "Hz", ]: # If they match on raw source, we are dealing with argument types. diff --git a/src/pybricks/_common.py b/src/pybricks/_common.py index 4911874..6a84018 100644 --- a/src/pybricks/_common.py +++ b/src/pybricks/_common.py @@ -4,7 +4,7 @@ """Generic cross-platform module for typical devices like lights, displays, speakers, and batteries.""" -from .parameters import Direction, Stop, Button, Port +from .parameters import Direction, Stop, Button, Port, Color from typing import Union, Iterable, overload, Optional, Tuple, Collection @@ -566,69 +566,29 @@ class Speaker: pass -class Light: - """Control a single-color light.""" - - def on(self, brightness=100): - """Turns on the light at the specified brightness. - - Arguments: - brightness (:ref:`brightness`): - Brightness of the light. - """ - - def off(self): - """Turns off the light.""" - pass - - def blink(self, durations): - """Blinks the light by turning it on and off for given durations. - - The light keeps 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 time values of the - form ``[on_1, off_1, on_2, off_2, ...]``. - """ - - def animate(self, brightness_values, interval): - """Animates the light with a list of brightness values. The next - brightness value in the list is shown 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` values. - interval (Number, ms): Time between brightness updates. - """ - - def reset(self): - """Resets the light to the default system behavior or animation.""" - pass - - class ColorLight: """Control a multi-color light.""" - def on(self, color): - """Turns on the light at the specified color. + def on(self, color: Color) -> None: + """on(color) + + Turns on the light at the specified color. Arguments: color (Color): Color of the light. """ pass - def off(self): - """Turns off the light.""" + def off(self) -> None: + """off() + + Turns off the light.""" pass - def blink(self, color, durations): - """Blinks the light at a given color by turning it on and off for given + def blink(self, color: Color, durations: Collection[int]) -> None: + """blink(color, durations) + + Blinks the light at a given color by turning it on and off for given durations. The light keeps blinking indefinitely while the rest of your @@ -640,26 +600,25 @@ class ColorLight: Arguments: color (Color): Color of the light. - durations (list): List of time values of the + durations (list): Sequence of time values of the form ``[on_1, off_1, on_2, off_2, ...]``. """ - def animate(self, colors, interval): - """Animates the light with a list of colors. The next - color in the list is shown after the given interval. + def animate(self, colors: Collection[Color], interval: int) -> None: + """animate(colors, interval) + + Animates the light with a sequence of colors, shown one by + one for the given interval. The animation runs in the background while the rest of your program keeps running. When the animation completes, it repeats. Arguments: - colors (list): List of :class:`Color <.parameters.Color>` values. + colors (iter): Sequence of :class:`Color <.parameters.Color>` + values. interval (Number, ms): Time between color updates. """ - def reset(self): - """Resets the light to the default system behavior or animation.""" - pass - class LightArray: """Control an array of single-color lights.""" diff --git a/src/pybricks/_common.pyi b/src/pybricks/_common.pyi index fd6f82a..dd24666 100644 --- a/src/pybricks/_common.pyi +++ b/src/pybricks/_common.pyi @@ -6,17 +6,7 @@ from typing import Collection, Iterable, Optional, Tuple, Union, overload from .geometry import Axis, Matrix, vector from .parameters import Button, Color, Direction, Side, Stop, Port -class Light: - def on(self, brightness: int = 100) -> None: ... - def off(self) -> None: ... - def blink(self, durations: Collection[int]) -> None: ... - def animate(self, brightness_values: Collection[int], interval: int) -> None: ... - def reset(self) -> None: ... - class ColorLight: - def on(self, color: Optional[Color]) -> None: ... - def off(self) -> None: ... - def blink(self, color: Color, durations: Collection[int]) -> None: ... def animate(self, colors: Collection[Color], interval: int) -> None: ... def reset(self) -> None: ... diff --git a/src/pybricks/pupdevices.py b/src/pybricks/pupdevices.py index 84d7626..f82225f 100644 --- a/src/pybricks/pupdevices.py +++ b/src/pybricks/pupdevices.py @@ -11,7 +11,6 @@ from ._common import ( ColorLight as _ColorLight, Motor as _Motor, LightArray as _LightArray, - Light as _Light, ) from .parameters import Direction as _Direction, Button as _Button @@ -460,7 +459,7 @@ class InfraredSensor: pass -class Light(_Light): +class Light: """LEGO® Powered Up Light.""" def __init__(self, port): @@ -471,3 +470,19 @@ class Light(_Light): """ pass + + def on(self, brightness: int = 100) -> None: + """on(brightness=100) + + Turns on the light at the specified brightness. + + Arguments: + brightness (Number, %): + Brightness of the light. + """ + + def off(self) -> None: + """off() + + Turns off the light.""" + pass