mirror of
https://github.com/pybricks/pybricks-api.git
synced 2026-07-27 19:57:02 +00:00
pybricks.*: add MaybeAwaitable types
Many blocking functions now return Awaitable[T] when the async run loop is running. The static analysis tools don't have a way of knowing this, so the best we can do is return both types so that x = method() and x = await method() both work mostly as expected.
This commit is contained in:
David Lechner
@@ -1,5 +1,5 @@
|
||||
# SPDX-License-Identifier: MIT
|
||||
# Copyright (c) 2022 The Pybricks Authors
|
||||
# Copyright (c) 2022-2023 The Pybricks Authors
|
||||
|
||||
"""
|
||||
Tests for correct signatures of the pupdevices.Motor class.
|
||||
@@ -29,7 +29,8 @@ def _get_function_signature(module: str, function: str) -> SignatureHelp:
|
||||
|
||||
|
||||
FUNCTION_PARAMS = [
|
||||
pytest.param("pybricks.tools", "wait", [(["time: Number"], "None")]),
|
||||
pytest.param("pybricks.tools", "read_input_byte", [([], "Optional[int]")]),
|
||||
pytest.param("pybricks.tools", "wait", [(["time: Number"], "MaybeAwaitable")]),
|
||||
pytest.param(
|
||||
"pybricks.tools",
|
||||
"vector",
|
||||
@@ -463,13 +464,13 @@ METHOD_PARAMS = [
|
||||
"pybricks.hubs",
|
||||
"PrimeHub",
|
||||
"speaker.beep",
|
||||
[(["frequency: Number=500", "duration: Number=100"], "None")],
|
||||
[(["frequency: Number=500", "duration: Number=100"], "MaybeAwaitable")],
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.hubs",
|
||||
"PrimeHub",
|
||||
"speaker.play_notes",
|
||||
[(["notes: Iterable[str]", "tempo: Number=120"], "None")],
|
||||
[(["notes: Iterable[str]", "tempo: Number=120"], "MaybeAwaitable")],
|
||||
),
|
||||
pytest.param("pybricks.hubs", "PrimeHub", "battery.voltage", [([], "int")]),
|
||||
pytest.param("pybricks.hubs", "PrimeHub", "battery.current", [([], "int")]),
|
||||
@@ -605,7 +606,7 @@ METHOD_PARAMS = [
|
||||
"then: Stop=Stop.HOLD",
|
||||
"wait: bool=True",
|
||||
],
|
||||
"None",
|
||||
"MaybeAwaitable",
|
||||
)
|
||||
],
|
||||
),
|
||||
@@ -621,7 +622,7 @@ METHOD_PARAMS = [
|
||||
"then: Stop=Stop.HOLD",
|
||||
"wait: bool=True",
|
||||
],
|
||||
"None",
|
||||
"MaybeAwaitable",
|
||||
)
|
||||
],
|
||||
),
|
||||
@@ -637,7 +638,7 @@ METHOD_PARAMS = [
|
||||
"then: Stop=Stop.HOLD",
|
||||
"wait: bool=True",
|
||||
],
|
||||
"None",
|
||||
"MaybeAwaitable",
|
||||
)
|
||||
],
|
||||
),
|
||||
@@ -658,7 +659,7 @@ METHOD_PARAMS = [
|
||||
"then: Stop=Stop.COAST",
|
||||
"duty_limit: Optional[Number]=None",
|
||||
],
|
||||
"int",
|
||||
"MaybeAwaitableInt",
|
||||
)
|
||||
],
|
||||
),
|
||||
@@ -737,24 +738,53 @@ METHOD_PARAMS = [
|
||||
],
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices", "TiltSensor", "tilt", [([], "Tuple[int, int]")]
|
||||
),
|
||||
pytest.param("pybricks.pupdevices", "InfraredSensor", "distance", [([], "int")]),
|
||||
pytest.param("pybricks.pupdevices", "InfraredSensor", "reflection", [([], "int")]),
|
||||
pytest.param("pybricks.pupdevices", "InfraredSensor", "count", [([], "int")]),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices", "ColorDistanceSensor", "color", [([], "Color")]
|
||||
"pybricks.pupdevices",
|
||||
"TiltSensor",
|
||||
"tilt",
|
||||
[([], "MaybeAwaitableTuple[int, int]")],
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices", "ColorDistanceSensor", "reflection", [([], "int")]
|
||||
"pybricks.pupdevices", "InfraredSensor", "distance", [([], "MaybeAwaitableInt")]
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices", "ColorDistanceSensor", "ambient", [([], "int")]
|
||||
"pybricks.pupdevices",
|
||||
"InfraredSensor",
|
||||
"reflection",
|
||||
[([], "MaybeAwaitableInt")],
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices", "ColorDistanceSensor", "distance", [([], "int")]
|
||||
"pybricks.pupdevices", "InfraredSensor", "count", [([], "MaybeAwaitableInt")]
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices",
|
||||
"ColorDistanceSensor",
|
||||
"color",
|
||||
[([], "MaybeAwaitableColor")],
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices",
|
||||
"ColorDistanceSensor",
|
||||
"reflection",
|
||||
[([], "MaybeAwaitableInt")],
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices",
|
||||
"ColorDistanceSensor",
|
||||
"ambient",
|
||||
[([], "MaybeAwaitableInt")],
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices",
|
||||
"ColorDistanceSensor",
|
||||
"distance",
|
||||
[([], "MaybeAwaitableInt")],
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices",
|
||||
"ColorDistanceSensor",
|
||||
"hsv",
|
||||
[([], "MaybeAwaitableColor")],
|
||||
),
|
||||
pytest.param("pybricks.pupdevices", "ColorDistanceSensor", "hsv", [([], "Color")]),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices",
|
||||
"ColorDistanceSensor",
|
||||
@@ -765,27 +795,36 @@ METHOD_PARAMS = [
|
||||
"pybricks.pupdevices",
|
||||
"ColorDistanceSensor",
|
||||
"light.on",
|
||||
[(["color: Color"], "None")],
|
||||
[(["color: Color"], "MaybeAwaitable")],
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices", "ColorDistanceSensor", "light.off", [([], "None")]
|
||||
"pybricks.pupdevices",
|
||||
"ColorDistanceSensor",
|
||||
"light.off",
|
||||
[([], "MaybeAwaitable")],
|
||||
),
|
||||
pytest.param("pybricks.pupdevices", "PFMotor", "dc", [(["duty: Number"], "None")]),
|
||||
pytest.param("pybricks.pupdevices", "PFMotor", "stop", [([], "None")]),
|
||||
pytest.param("pybricks.pupdevices", "PFMotor", "brake", [([], "None")]),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices", "PFMotor", "dc", [(["duty: Number"], "MaybeAwaitable")]
|
||||
),
|
||||
pytest.param("pybricks.pupdevices", "PFMotor", "stop", [([], "MaybeAwaitable")]),
|
||||
pytest.param("pybricks.pupdevices", "PFMotor", "brake", [([], "MaybeAwaitable")]),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices",
|
||||
"ColorSensor",
|
||||
"color",
|
||||
[(["surface: bool=True"], "Optional[Color]")],
|
||||
[(["surface: bool=True"], "MaybeAwaitableColor")],
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices", "ColorSensor", "reflection", [([], "MaybeAwaitableInt")]
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices", "ColorSensor", "ambient", [([], "MaybeAwaitableInt")]
|
||||
),
|
||||
pytest.param("pybricks.pupdevices", "ColorSensor", "reflection", [([], "int")]),
|
||||
pytest.param("pybricks.pupdevices", "ColorSensor", "ambient", [([], "int")]),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices",
|
||||
"ColorSensor",
|
||||
"hsv",
|
||||
[(["surface: bool=True"], "Color")],
|
||||
[(["surface: bool=True"], "MaybeAwaitableColor")],
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices",
|
||||
@@ -797,11 +836,28 @@ METHOD_PARAMS = [
|
||||
"pybricks.pupdevices",
|
||||
"ColorSensor",
|
||||
"lights.on",
|
||||
[(["brightness: Union[Number, Tuple[Number, Number, Number]]"], "None")],
|
||||
[
|
||||
(
|
||||
["brightness: Union[Number, Tuple[Number, Number, Number]]"],
|
||||
"MaybeAwaitable",
|
||||
)
|
||||
],
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices", "ColorSensor", "lights.off", [([], "MaybeAwaitable")]
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices",
|
||||
"UltrasonicSensor",
|
||||
"distance",
|
||||
[([], "MaybeAwaitableInt")],
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices",
|
||||
"UltrasonicSensor",
|
||||
"presence",
|
||||
[([], "MaybeAwaitableBool")],
|
||||
),
|
||||
pytest.param("pybricks.pupdevices", "ColorSensor", "lights.off", [([], "None")]),
|
||||
pytest.param("pybricks.pupdevices", "UltrasonicSensor", "distance", [([], "int")]),
|
||||
pytest.param("pybricks.pupdevices", "UltrasonicSensor", "presence", [([], "bool")]),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices",
|
||||
"UltrasonicSensor",
|
||||
@@ -809,29 +865,40 @@ METHOD_PARAMS = [
|
||||
[
|
||||
(
|
||||
["brightness: Union[Number, Tuple[Number, Number, Number, Number]]"],
|
||||
"None",
|
||||
"MaybeAwaitable",
|
||||
)
|
||||
],
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices", "UltrasonicSensor", "lights.off", [([], "None")]
|
||||
"pybricks.pupdevices",
|
||||
"UltrasonicSensor",
|
||||
"lights.off",
|
||||
[([], "MaybeAwaitable")],
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices", "ForceSensor", "force", [([], "MaybeAwaitableFloat")]
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices", "ForceSensor", "distance", [([], "MaybeAwaitableFloat")]
|
||||
),
|
||||
pytest.param("pybricks.pupdevices", "ForceSensor", "force", [([], "float")]),
|
||||
pytest.param("pybricks.pupdevices", "ForceSensor", "distance", [([], "float")]),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices",
|
||||
"ForceSensor",
|
||||
"pressed",
|
||||
[(["force: Number=3"], "bool")],
|
||||
[(["force: Number=3"], "MaybeAwaitableBool")],
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices", "ForceSensor", "touched", [([], "MaybeAwaitableBool")]
|
||||
),
|
||||
pytest.param("pybricks.pupdevices", "ForceSensor", "touched", [([], "bool")]),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices",
|
||||
"ColorLightMatrix",
|
||||
"on",
|
||||
[(["color: Union[Color, Collection[Color]]"], "None")],
|
||||
[(["color: Union[Color, Collection[Color]]"], "MaybeAwaitable")],
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices", "ColorLightMatrix", "off", [([], "MaybeAwaitable")]
|
||||
),
|
||||
pytest.param("pybricks.pupdevices", "ColorLightMatrix", "off", [([], "None")]),
|
||||
pytest.param(
|
||||
"pybricks.pupdevices", "Light", "on", [(["brightness: Number=100"], "None")]
|
||||
),
|
||||
@@ -860,13 +927,23 @@ METHOD_PARAMS = [
|
||||
"pybricks.robotics",
|
||||
"DriveBase",
|
||||
"straight",
|
||||
[(["distance: Number", "then: Stop=Stop.HOLD", "wait: bool=True"], "None")],
|
||||
[
|
||||
(
|
||||
["distance: Number", "then: Stop=Stop.HOLD", "wait: bool=True"],
|
||||
"MaybeAwaitable",
|
||||
)
|
||||
],
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.robotics",
|
||||
"DriveBase",
|
||||
"turn",
|
||||
[(["angle: Number", "then: Stop=Stop.HOLD", "wait: bool=True"], "None")],
|
||||
[
|
||||
(
|
||||
["angle: Number", "then: Stop=Stop.HOLD", "wait: bool=True"],
|
||||
"MaybeAwaitable",
|
||||
)
|
||||
],
|
||||
),
|
||||
pytest.param(
|
||||
"pybricks.robotics",
|
||||
@@ -880,7 +957,7 @@ METHOD_PARAMS = [
|
||||
"then: Stop=Stop.HOLD",
|
||||
"wait: bool=True",
|
||||
],
|
||||
"None",
|
||||
"MaybeAwaitable",
|
||||
)
|
||||
],
|
||||
),
|
||||
|
||||
+61
-16
@@ -12,8 +12,31 @@ from .tools import Matrix
|
||||
from .parameters import Axis, Direction, Stop, Button, Port, Color, Side
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from typing import Any, Awaitable, TypeVar
|
||||
|
||||
from .parameters import Number
|
||||
|
||||
_T_co = TypeVar("_T_co", covariant=True)
|
||||
|
||||
class MaybeAwaitable(None, Awaitable[None]):
|
||||
...
|
||||
|
||||
# HACK: Cannot subclass bool, so using Any instead.
|
||||
class MaybeAwaitableBool(Any, Awaitable[bool]):
|
||||
...
|
||||
|
||||
class MaybeAwaitableFloat(float, Awaitable[float]):
|
||||
...
|
||||
|
||||
class MaybeAwaitableInt(int, Awaitable[int]):
|
||||
...
|
||||
|
||||
class MaybeAwaitableTuple(Tuple[_T_co], Awaitable[Tuple[_T_co]]):
|
||||
...
|
||||
|
||||
class MaybeAwaitableColor(Color, Awaitable[Color]):
|
||||
...
|
||||
|
||||
|
||||
class System:
|
||||
"""System control actions for a hub."""
|
||||
@@ -476,7 +499,7 @@ class Motor(DCMotor):
|
||||
|
||||
def run_time(
|
||||
self, speed: Number, time: Number, then: Stop = Stop.HOLD, wait: bool = True
|
||||
) -> None:
|
||||
) -> MaybeAwaitable:
|
||||
"""run_time(speed, time, then=Stop.HOLD, wait=True)
|
||||
|
||||
Runs the motor at a constant speed for a given amount of time.
|
||||
@@ -499,7 +522,7 @@ class Motor(DCMotor):
|
||||
rotation_angle: Number,
|
||||
then: Stop = Stop.HOLD,
|
||||
wait: bool = True,
|
||||
) -> None:
|
||||
) -> MaybeAwaitable:
|
||||
"""run_angle(speed, rotation_angle, then=Stop.HOLD, wait=True)
|
||||
|
||||
Runs the motor at a constant speed by a given angle.
|
||||
@@ -519,7 +542,7 @@ class Motor(DCMotor):
|
||||
target_angle: Number,
|
||||
then: Stop = Stop.HOLD,
|
||||
wait: bool = True,
|
||||
) -> None:
|
||||
) -> MaybeAwaitable:
|
||||
"""run_target(speed, target_angle, then=Stop.HOLD, wait=True)
|
||||
|
||||
Runs the motor at a constant speed towards a given target angle.
|
||||
@@ -540,7 +563,7 @@ class Motor(DCMotor):
|
||||
speed: Number,
|
||||
then: Stop = Stop.COAST,
|
||||
duty_limit: Optional[Number] = None,
|
||||
) -> int:
|
||||
) -> MaybeAwaitableInt:
|
||||
"""
|
||||
run_until_stalled(speed, then=Stop.COAST, duty_limit=None) -> int: deg
|
||||
|
||||
@@ -604,7 +627,7 @@ class Speaker:
|
||||
volume (Number, %): Volume of the speaker in the 0-100 range.
|
||||
"""
|
||||
|
||||
def beep(self, frequency: Number = 500, duration: Number = 100) -> None:
|
||||
def beep(self, frequency: Number = 500, duration: Number = 100) -> MaybeAwaitable:
|
||||
"""beep(frequency=500, duration=100)
|
||||
|
||||
Play a beep/tone.
|
||||
@@ -618,7 +641,7 @@ class Speaker:
|
||||
play continues to play indefinitely.
|
||||
"""
|
||||
|
||||
def play_notes(self, notes: Iterable[str], tempo: Number = 120) -> None:
|
||||
def play_notes(self, notes: Iterable[str], tempo: Number = 120) -> MaybeAwaitable:
|
||||
"""play_notes(notes, tempo=120)
|
||||
|
||||
Plays a sequence of musical notes. For example:
|
||||
@@ -705,10 +728,31 @@ class ColorLight:
|
||||
"""
|
||||
|
||||
|
||||
class ExternalColorLight:
|
||||
"""Control a multi-color light."""
|
||||
|
||||
def on(self, color: Color) -> MaybeAwaitable:
|
||||
"""on(color)
|
||||
|
||||
Turns on the light at the specified color.
|
||||
|
||||
Arguments:
|
||||
color (Color): Color of the light.
|
||||
"""
|
||||
|
||||
def off(self) -> MaybeAwaitable:
|
||||
"""off()
|
||||
|
||||
Turns off the light.
|
||||
"""
|
||||
|
||||
|
||||
class LightArray3:
|
||||
"""Control an array of three single-color lights."""
|
||||
|
||||
def on(self, brightness: Union[Number, Tuple[Number, Number, Number]]) -> None:
|
||||
def on(
|
||||
self, brightness: Union[Number, Tuple[Number, Number, Number]]
|
||||
) -> MaybeAwaitable:
|
||||
"""on(brightness)
|
||||
|
||||
Turns on the lights at the specified brightness.
|
||||
@@ -720,10 +764,11 @@ class LightArray3:
|
||||
of each light individually.
|
||||
"""
|
||||
|
||||
def off(self) -> None:
|
||||
def off(self) -> MaybeAwaitable:
|
||||
"""off()
|
||||
|
||||
Turns off all the lights."""
|
||||
Turns off all the lights.
|
||||
"""
|
||||
|
||||
|
||||
class LightArray4(LightArray3):
|
||||
@@ -731,7 +776,7 @@ class LightArray4(LightArray3):
|
||||
|
||||
def on(
|
||||
self, brightness: Union[Number, Tuple[Number, Number, Number, Number]]
|
||||
) -> None:
|
||||
) -> MaybeAwaitable:
|
||||
"""on(brightness)
|
||||
|
||||
Turns on the lights at the specified brightness.
|
||||
@@ -1164,7 +1209,7 @@ class CommonColorSensor:
|
||||
port (Port): Port to which the sensor is connected.
|
||||
"""
|
||||
|
||||
def color(self) -> Color:
|
||||
def color(self) -> MaybeAwaitableColor:
|
||||
"""color() -> Color
|
||||
|
||||
Scans the color of a surface.
|
||||
@@ -1178,7 +1223,7 @@ class CommonColorSensor:
|
||||
Detected color.
|
||||
"""
|
||||
|
||||
def hsv(self) -> Color:
|
||||
def hsv(self) -> MaybeAwaitableColor:
|
||||
"""hsv() -> Color
|
||||
|
||||
Scans the color of a surface.
|
||||
@@ -1192,7 +1237,7 @@ class CommonColorSensor:
|
||||
saturation (0--100), and a brightness value (0--100).
|
||||
"""
|
||||
|
||||
def ambient(self) -> int:
|
||||
def ambient(self) -> MaybeAwaitableInt:
|
||||
"""ambient() -> int: %
|
||||
|
||||
Measures the ambient light intensity.
|
||||
@@ -1202,7 +1247,7 @@ class CommonColorSensor:
|
||||
to 100% (bright).
|
||||
"""
|
||||
|
||||
def reflection(self) -> int:
|
||||
def reflection(self) -> MaybeAwaitableInt:
|
||||
"""reflection() -> int: %
|
||||
|
||||
Measures how much a surface reflects the light emitted by the
|
||||
@@ -1248,7 +1293,7 @@ class AmbientColorSensor(CommonColorSensor):
|
||||
"""Like CommonColorSensor, but also detects ambient colors when the sensor
|
||||
light is turned off"""
|
||||
|
||||
def color(self, surface: bool = True) -> Optional[Color]:
|
||||
def color(self, surface: bool = True) -> MaybeAwaitableColor:
|
||||
"""color(surface=True) -> Color
|
||||
|
||||
Scans the color of a surface or an external light source.
|
||||
@@ -1267,7 +1312,7 @@ class AmbientColorSensor(CommonColorSensor):
|
||||
Detected color.`
|
||||
"""
|
||||
|
||||
def hsv(self, surface: bool = True) -> Color:
|
||||
def hsv(self, surface: bool = True) -> MaybeAwaitableColor:
|
||||
"""hsv(surface=True) -> Color
|
||||
|
||||
Scans the color of a surface or an external light source.
|
||||
|
||||
@@ -1,13 +1,18 @@
|
||||
# SPDX-License-Identifier: MIT
|
||||
# Copyright (c) 2018-2020 The Pybricks Authors
|
||||
# Copyright (c) 2018-2023 The Pybricks Authors
|
||||
|
||||
"""Generic input/output devices."""
|
||||
|
||||
from typing import Dict, Tuple, Optional, overload
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Dict, Tuple, Optional, overload, TYPE_CHECKING
|
||||
|
||||
from . import _common
|
||||
from .parameters import Port as _Port
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from ._common import MaybeAwaitable, MaybeAwaitableTuple
|
||||
|
||||
|
||||
class PUPDevice:
|
||||
"""Powered Up motor or sensor."""
|
||||
@@ -28,7 +33,7 @@ class PUPDevice:
|
||||
Dictionary with information, such as the device ``id``.
|
||||
"""
|
||||
|
||||
def read(self, mode: int) -> Tuple:
|
||||
def read(self, mode: int) -> MaybeAwaitableTuple:
|
||||
"""read(mode) -> Tuple
|
||||
|
||||
Reads values from a given mode.
|
||||
@@ -40,7 +45,7 @@ class PUPDevice:
|
||||
Values read from the sensor.
|
||||
"""
|
||||
|
||||
def write(self, mode: int, data: Tuple) -> None:
|
||||
def write(self, mode: int, data: Tuple) -> MaybeAwaitable:
|
||||
"""write(mode, data)
|
||||
|
||||
Writes values to the sensor. Only selected sensors and modes support
|
||||
@@ -62,7 +67,7 @@ class LUMPDevice:
|
||||
port (Port): Port to which the device is connected.
|
||||
"""
|
||||
|
||||
def read(self, mode: int) -> Tuple:
|
||||
def read(self, mode: int) -> MaybeAwaitableTuple:
|
||||
"""read(mode) -> Tuple
|
||||
|
||||
Reads values from a given mode.
|
||||
@@ -95,7 +100,7 @@ class Ev3devSensor:
|
||||
port (Port): Port to which the device is connected.
|
||||
"""
|
||||
|
||||
def read(self, mode: str) -> Tuple:
|
||||
def read(self, mode: str) -> MaybeAwaitableTuple:
|
||||
"""read(mode) -> Tuple
|
||||
|
||||
Reads values at a given mode.
|
||||
@@ -331,3 +336,9 @@ class LWP3Device:
|
||||
Returns:
|
||||
The raw binary message.
|
||||
"""
|
||||
|
||||
|
||||
# hide from jedi
|
||||
if TYPE_CHECKING:
|
||||
del MaybeAwaitable
|
||||
del MaybeAwaitableTuple
|
||||
|
||||
+55
-17
@@ -1,16 +1,23 @@
|
||||
# SPDX-License-Identifier: MIT
|
||||
# Copyright (c) 2018-2022 The Pybricks Authors
|
||||
# Copyright (c) 2018-2023 The Pybricks Authors
|
||||
|
||||
"""LEGO® Powered Up motor, sensors, and lights."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import TYPE_CHECKING, Collection, Optional, Union, overload, Tuple
|
||||
from typing import TYPE_CHECKING, Collection, Optional, Union, overload
|
||||
|
||||
from . import _common
|
||||
from .parameters import Button, Color, Direction
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from ._common import (
|
||||
MaybeAwaitable,
|
||||
MaybeAwaitableBool,
|
||||
MaybeAwaitableFloat,
|
||||
MaybeAwaitableInt,
|
||||
MaybeAwaitableTuple,
|
||||
)
|
||||
from .parameters import Number, Port
|
||||
|
||||
|
||||
@@ -144,7 +151,7 @@ class TiltSensor:
|
||||
port (Port): Port to which the sensor is connected.
|
||||
"""
|
||||
|
||||
def tilt(self) -> Tuple[int, int]:
|
||||
def tilt(self) -> MaybeAwaitableTuple[int, int]:
|
||||
"""tilt() -> Tuple[int, int]: deg
|
||||
|
||||
Measures the tilt relative to the horizontal plane.
|
||||
@@ -157,7 +164,7 @@ class TiltSensor:
|
||||
class ColorDistanceSensor(_common.CommonColorSensor):
|
||||
"""LEGO® Powered Up Color and Distance Sensor."""
|
||||
|
||||
light = _common.ColorLight()
|
||||
light = _common.ExternalColorLight()
|
||||
|
||||
# HACK: jedi can't find inherited __init__ so docs have to be duplicated
|
||||
def __init__(self, port: Port):
|
||||
@@ -167,7 +174,7 @@ class ColorDistanceSensor(_common.CommonColorSensor):
|
||||
port (Port): Port to which the sensor is connected.
|
||||
"""
|
||||
|
||||
def distance(self) -> int:
|
||||
def distance(self) -> MaybeAwaitableInt:
|
||||
"""distance() -> int: %
|
||||
|
||||
Measures the relative distance between the sensor and an object
|
||||
@@ -178,7 +185,7 @@ class ColorDistanceSensor(_common.CommonColorSensor):
|
||||
"""
|
||||
|
||||
|
||||
class PFMotor(DCMotor):
|
||||
class PFMotor:
|
||||
"""Control Power Functions motors with the infrared functionality of the
|
||||
:class:`ColorDistanceSensor <pybricks.pupdevices.ColorDistanceSensor>`."""
|
||||
|
||||
@@ -204,6 +211,32 @@ class PFMotor(DCMotor):
|
||||
turn when you give a positive duty cycle value.
|
||||
"""
|
||||
|
||||
def dc(self, duty: Number) -> MaybeAwaitable:
|
||||
"""dc(duty)
|
||||
|
||||
Rotates the motor at a given duty cycle (also known as "power").
|
||||
|
||||
Arguments:
|
||||
duty (Number, %): The duty cycle (-100.0 to 100).
|
||||
"""
|
||||
|
||||
def stop(self) -> MaybeAwaitable:
|
||||
"""stop()
|
||||
|
||||
Stops the motor and lets it spin freely.
|
||||
|
||||
The motor gradually stops due to friction.
|
||||
"""
|
||||
|
||||
def brake(self) -> MaybeAwaitable:
|
||||
"""brake()
|
||||
|
||||
Passively brakes the motor.
|
||||
|
||||
The motor stops due to friction, plus the voltage that
|
||||
is generated while the motor is still moving.
|
||||
"""
|
||||
|
||||
|
||||
class ColorSensor(_common.AmbientColorSensor):
|
||||
"""LEGO® SPIKE Color Sensor."""
|
||||
@@ -232,7 +265,7 @@ class UltrasonicSensor:
|
||||
|
||||
"""
|
||||
|
||||
def distance(self) -> int:
|
||||
def distance(self) -> MaybeAwaitableInt:
|
||||
"""distance() -> int: mm
|
||||
|
||||
Measures the distance between the sensor and an object using
|
||||
@@ -244,7 +277,7 @@ class UltrasonicSensor:
|
||||
|
||||
"""
|
||||
|
||||
def presence(self) -> bool:
|
||||
def presence(self) -> MaybeAwaitableBool:
|
||||
"""presence() -> bool
|
||||
|
||||
Checks for the presence of other ultrasonic sensors by detecting
|
||||
@@ -265,7 +298,7 @@ class ForceSensor:
|
||||
port (Port): Port to which the sensor is connected.
|
||||
"""
|
||||
|
||||
def force(self) -> float:
|
||||
def force(self) -> MaybeAwaitableFloat:
|
||||
"""force() -> float: N
|
||||
|
||||
Measures the force exerted on the sensor.
|
||||
@@ -274,7 +307,7 @@ class ForceSensor:
|
||||
Measured force (up to approximately 10.00 N).
|
||||
"""
|
||||
|
||||
def distance(self) -> float:
|
||||
def distance(self) -> MaybeAwaitableFloat:
|
||||
"""distance() -> float: mm
|
||||
|
||||
Measures by how much the sensor button has moved.
|
||||
@@ -283,7 +316,7 @@ class ForceSensor:
|
||||
Movement up to approximately 8.00 mm.
|
||||
"""
|
||||
|
||||
def pressed(self, force: Number = 3) -> bool:
|
||||
def pressed(self, force: Number = 3) -> MaybeAwaitableBool:
|
||||
"""pressed(force=3) -> bool
|
||||
|
||||
Checks if the sensor button is pressed.
|
||||
@@ -295,7 +328,7 @@ class ForceSensor:
|
||||
``True`` if the sensor is pressed, ``False`` if it is not.
|
||||
"""
|
||||
|
||||
def touched(self) -> bool:
|
||||
def touched(self) -> MaybeAwaitableBool:
|
||||
"""touched() -> bool
|
||||
|
||||
Checks if the sensor is touched.
|
||||
@@ -323,7 +356,7 @@ class ColorLightMatrix:
|
||||
"""
|
||||
...
|
||||
|
||||
def on(self, color: Union[Color, Collection[Color]]) -> None:
|
||||
def on(self, color: Union[Color, Collection[Color]]) -> MaybeAwaitable:
|
||||
"""on(colors)
|
||||
|
||||
Turns the lights on.
|
||||
@@ -336,7 +369,7 @@ class ColorLightMatrix:
|
||||
"""
|
||||
...
|
||||
|
||||
def off(self) -> None:
|
||||
def off(self) -> MaybeAwaitable:
|
||||
"""off()
|
||||
|
||||
Turns all lights off.
|
||||
@@ -354,7 +387,7 @@ class InfraredSensor:
|
||||
port (Port): Port to which the sensor is connected.
|
||||
"""
|
||||
|
||||
def reflection(self) -> int:
|
||||
def reflection(self) -> MaybeAwaitableInt:
|
||||
"""reflection() -> int: %
|
||||
|
||||
Measures the reflection of a surface using an infrared light.
|
||||
@@ -364,7 +397,7 @@ class InfraredSensor:
|
||||
100% (high reflection).
|
||||
"""
|
||||
|
||||
def distance(self) -> int:
|
||||
def distance(self) -> MaybeAwaitableInt:
|
||||
"""distance() -> int: %
|
||||
|
||||
Measures the relative distance between the sensor and an object
|
||||
@@ -374,7 +407,7 @@ class InfraredSensor:
|
||||
Distance ranging from 0% (closest) to 100% (farthest).
|
||||
"""
|
||||
|
||||
def count(self) -> int:
|
||||
def count(self) -> MaybeAwaitableInt:
|
||||
"""count() -> int
|
||||
|
||||
Counts the number of objects that have passed by the sensor.
|
||||
@@ -415,5 +448,10 @@ if TYPE_CHECKING:
|
||||
del Button
|
||||
del Color
|
||||
del Direction
|
||||
del MaybeAwaitable
|
||||
del MaybeAwaitableBool
|
||||
del MaybeAwaitableFloat
|
||||
del MaybeAwaitableInt
|
||||
del MaybeAwaitableTuple
|
||||
del Number
|
||||
del Port
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
# SPDX-License-Identifier: MIT
|
||||
# Copyright (c) 2018-2022 The Pybricks Authors
|
||||
# Copyright (c) 2018-2023 The Pybricks Authors
|
||||
|
||||
"""Robotics module for the Pybricks API."""
|
||||
|
||||
@@ -11,7 +11,7 @@ from . import _common
|
||||
from .parameters import Stop
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from ._common import Motor
|
||||
from ._common import Motor, MaybeAwaitable
|
||||
from .parameters import Number
|
||||
|
||||
|
||||
@@ -161,7 +161,7 @@ class DriveBase:
|
||||
|
||||
def straight(
|
||||
self, distance: Number, then: Stop = Stop.HOLD, wait: bool = True
|
||||
) -> None:
|
||||
) -> MaybeAwaitable:
|
||||
"""straight(distance, then=Stop.HOLD, wait=True)
|
||||
|
||||
Drives straight for a given distance and then stops.
|
||||
@@ -173,7 +173,9 @@ class DriveBase:
|
||||
with the rest of the program.
|
||||
"""
|
||||
|
||||
def turn(self, angle: Number, then: Stop = Stop.HOLD, wait: bool = True) -> None:
|
||||
def turn(
|
||||
self, angle: Number, then: Stop = Stop.HOLD, wait: bool = True
|
||||
) -> MaybeAwaitable:
|
||||
"""turn(angle, then=Stop.HOLD, wait=True)
|
||||
|
||||
Turns in place by a given angle and then stops.
|
||||
@@ -187,7 +189,7 @@ class DriveBase:
|
||||
|
||||
def curve(
|
||||
self, radius: Number, angle: Number, then: Stop = Stop.HOLD, wait: bool = True
|
||||
) -> None:
|
||||
) -> MaybeAwaitable:
|
||||
"""curve(radius, angle, then=Stop.HOLD, wait=True)
|
||||
|
||||
Drives an arc along a circle of a given radius, by a given angle.
|
||||
@@ -232,4 +234,5 @@ class GyroDriveBase(DriveBase):
|
||||
if TYPE_CHECKING:
|
||||
del Motor
|
||||
del Number
|
||||
del MaybeAwaitable
|
||||
del Stop
|
||||
|
||||
@@ -8,10 +8,11 @@ from __future__ import annotations
|
||||
from typing import TYPE_CHECKING, Any, Optional, Sequence, Tuple, overload
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from ._common import MaybeAwaitable
|
||||
from .parameters import Number
|
||||
|
||||
|
||||
def wait(time: Number) -> None:
|
||||
def wait(time: Number) -> MaybeAwaitable:
|
||||
"""wait(time)
|
||||
|
||||
Pauses the user program for a specified amount of time.
|
||||
@@ -236,3 +237,4 @@ def read_input_byte() -> Optional[int]:
|
||||
# HACK: hide from jedi
|
||||
if TYPE_CHECKING:
|
||||
del Number
|
||||
del MaybeAwaitable
|
||||
|
||||
Reference in New Issue
Block a user