pybricks 3.3.0a4__tar.gz → 3.3.0b9__tar.gz

{pybricks-3.3.0a4 → pybricks-3.3.0b9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pybricks
-Version: 3.3.0a4
+Version: 3.3.0b9
 Summary: Documentation and user-API stubs for Pybricks MicroPython
 Home-page: https://pybricks.com
 License: MIT
@@ -9,7 +9,6 @@ Author-email: dev@pybricks.com
 Maintainer: Laurens Valk
 Maintainer-email: laurens@pybricks.com
 Requires-Python: >=3.8,<4.0
-Classifier: Development Status :: 3 - Alpha
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8

{pybricks-3.3.0a4 → pybricks-3.3.0b9}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pybricks"
-version = "3.3.0a4"
+version = "3.3.0b9"
 description = "Documentation and user-API stubs for Pybricks MicroPython"
 authors = ["The Pybricks Authors <dev@pybricks.com>"]
 maintainers = ["Laurens Valk <laurens@pybricks.com>", "David Lechner <david@pybricks.com>" ]
@@ -10,7 +10,6 @@ homepage = "https://pybricks.com"
 repository = "https://github.com/pybricks/pybricks-api"
 documentation = "https://docs.pybricks.com"
 classifiers = [
-    "Development Status :: 3 - Alpha",
     "Programming Language :: Python :: Implementation :: MicroPython",
 ]
 packages = [
@@ -29,11 +28,13 @@ packages = [
 [tool.poetry.dependencies]
 python = "^3.8"
 
-[tool.poetry.dev-dependencies]
+[tool.poetry.group.lint.dependencies]
 black = "^22.3.0"
 doc8 = "^0.8.1"
 flake8 = "^4.0"
-Sphinx = { git = "https://github.com/pybricks/sphinx.git", rev = "b00124cb" }
+
+[tool.poetry.group.doc.dependencies]
+Sphinx = { git = "https://github.com/pybricks/sphinx.git", rev = "cd277d09" }
 sphinx-rtd-theme = "^1.0.0"
 toml = "^0.10.0"
 

{pybricks-3.3.0a4 → pybricks-3.3.0b9}/src/pybricks/_common.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: MIT
-# Copyright (c) 2018-2021 The Pybricks Authors
+# Copyright (c) 2018-2023 The Pybricks Authors
 
 """Generic cross-platform module for typical devices like lights, displays,
 speakers, and batteries."""
@@ -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."""
@@ -78,8 +101,8 @@ class System:
 
     def storage(self, offset, read=None, write=None):
         """
-        storage(self, offset, write=)
-        storage(self, offset, read=) -> bytes
+        storage(offset, write=)
+        storage(offset, read=) -> bytes
 
         Reads or writes binary data to persistent storage.
 
@@ -393,10 +416,12 @@ class Motor(DCMotor):
                 Choose ``False`` to keep the
                 current value, so your program knows where it left off last
                 time.
-            profile (Number, deg): Precision profile. A lower value
-                means more precise movement; a larger value means
-                smoother movement. If no value is given, a suitable profile for
-                this motor type will be selected automatically.
+            profile (Number, deg): Precision profile. This is the approximate
+                position tolerance in degrees that is acceptable in your
+                application. A lower value gives more precise but more erratic
+                movement; a higher value gives less precise but smoother
+                movement. If no value is given, a suitable profile for this
+                motor type will be selected automatically (about 11 degrees).
         """
 
     def angle(self) -> int:
@@ -476,7 +501,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 +524,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 +544,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 +565,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 +629,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 +643,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 +730,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 +766,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 +778,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 +1211,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 +1225,7 @@ class CommonColorSensor:
             Detected color.
         """
 
-    def hsv(self) -> Color:
+    def hsv(self) -> MaybeAwaitableColor:
         """hsv() -> Color
 
         Scans the color of a surface.
@@ -1192,7 +1239,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 +1249,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 +1295,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 +1314,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.
@@ -1285,3 +1332,77 @@ class AmbientColorSensor(CommonColorSensor):
             Measured color. The color is described by a hue (0--359), a
             saturation (0--100), and a brightness value (0--100).
         """
+
+
+class BLE:
+    """
+    Bluetooth Low Energy.
+
+    .. versionadded:: 3.3
+    """
+
+    def broadcast(self, data: Union[bool, int, float, str, bytes]) -> None:
+        """broadcast(data)
+
+        Starts broadcasting the given data on
+        the *broadcast_channel* you selected when initializing the hub.
+
+        Data may be of type ``int``, ``float``, ``str``, ``bytes``,
+        ``True``, or ``False``, or a tuple thereof.
+
+        The total data size is quite limited (26 bytes). ``True`` and
+        ``False`` take 1 byte each. ``float`` takes 5 bytes. ``int`` takes 2 to
+        5 bytes depending on how big the number is. ``str`` and ``bytes`` take
+        the number of bytes in the object plus one extra byte.
+
+        Args:
+            data: The value or values to be broadcast.
+
+        .. versionadded:: 3.3
+        """
+
+    def observe(
+        self, channel: int
+    ) -> Optional[Tuple[Union[bool, int, float, str, bytes], ...]]:
+        """observe(channel) -> bool | int | float | str | bytes | tuple | None
+
+        Retrieves the last observed data for a given channel.
+
+        Receiving data is more reliable when the hub is not connected
+        to a computer or other devices at the same time.
+
+        Args:
+            channel (int): The channel to observe (0 to 255).
+
+        Returns:
+            The received data in the same format as it was sent, or ``None``
+            if no recent data is available.
+
+        .. versionadded:: 3.3
+        """
+
+    def signal_strength(self, channel: int) -> int:
+        """signal_strength(channel) -> int: dBm
+
+        Gets the average signal strength in dBm for the given channel.
+
+        This indicates how near the broadcasting device is. Nearby devices
+        may have a signal strength around -40 dBm, while far away devices
+        might have a signal strength around -70 dBm.
+
+        Args:
+            channel (int): The channel number (0 to 255).
+
+        Returns:
+            The signal strength or ``-128`` if there is no recent observed data.
+
+        .. versionadded:: 3.3
+        """
+
+    def version(self) -> str:
+        """version() -> str
+
+        Gets the firmware version from the Bluetooth chip.
+
+        .. versionadded:: 3.3
+        """

{pybricks-3.3.0a4 → pybricks-3.3.0b9}/src/pybricks/hubs.py

@@ -1,7 +1,10 @@
 # SPDX-License-Identifier: MIT
-# Copyright (c) 2018-2022 The Pybricks Authors
+# Copyright (c) 2018-2023 The Pybricks Authors
 
 """LEGO® Programmable Hubs."""
+
+from typing import Sequence
+
 from . import _common
 from .ev3dev import _speaker
 from .media.ev3dev import Image as _Image
@@ -38,6 +41,25 @@ class MoveHub:
     imu = _common.SimpleAccelerometer()
     system = _common.System()
     button = _common.Keypad([_Button.CENTER])
+    ble = _common.BLE()
+
+    def __init__(
+        self, broadcast_channel: int = 0, observe_channels: Sequence[int] = []
+    ):
+        """MoveHub(broadcast_channel=0, observe_channels=[])
+
+        Arguments:
+            broadcast_channel:
+                A value from 0 to 255 indicating which channel ``hub.ble.broadcast()``
+                will use. Default is channel 0.
+            observe_channels:
+                A list of channels to listen to when ``hub.ble.observe()`` is
+                called. Listening to more channels requires more memory.
+                Default is an empty list (no channels).
+
+        .. versionchanged:: 3.3
+            Added *broadcast_channel* and *observe_channels* arguments.
+        """
 
 
 class CityHub:
@@ -49,6 +71,25 @@ class CityHub:
     light = _common.ColorLight()
     system = _common.System()
     button = _common.Keypad([_Button.CENTER])
+    ble = _common.BLE()
+
+    def __init__(
+        self, broadcast_channel: int = 0, observe_channels: Sequence[int] = []
+    ):
+        """CityHub(broadcast_channel=0, observe_channels=[])
+
+        Arguments:
+            broadcast_channel:
+                A value from 0 to 255 indicating which channel ``hub.ble.broadcast()``
+                will use. Default is channel 0.
+            observe_channels:
+                A list of channels to listen to when ``hub.ble.observe()`` is
+                called. Listening to more channels requires more memory.
+                Default is an empty list (no channels).
+
+        .. versionchanged:: 3.3
+            Added *broadcast_channel* and *observe_channels* arguments.
+        """
 
 
 class TechnicHub:
@@ -61,9 +102,16 @@ class TechnicHub:
     imu = _common.IMU()
     system = _common.System()
     button = _common.Keypad([_Button.CENTER])
+    ble = _common.BLE()
 
-    def __init__(self, top_side: Axis = Axis.Z, front_side: Axis = Axis.X):
-        """TechnicHub(top_side=Axis.Z, front_side=Axis.X)
+    def __init__(
+        self,
+        top_side: Axis = Axis.Z,
+        front_side: Axis = Axis.X,
+        broadcast_channel: int = 0,
+        observe_channels: Sequence[int] = [],
+    ):
+        """TechnicHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=0, observe_channels=[])
 
         Initializes the hub. Optionally, specify how the hub is
         :ref:`placed in your design <robotframe>` by saying in which
@@ -75,6 +123,16 @@ class TechnicHub:
                 the hub.
             front_side (Axis): The axis that passes through the *front side* of
                 the hub.
+            broadcast_channel:
+                A value from 0 to 255 indicating which channel ``hub.ble.broadcast()``
+                will use. Default is channel 0.
+            observe_channels:
+                A list of channels to listen to when ``hub.ble.observe()`` is
+                called. Listening to more channels requires more memory.
+                Default is an empty list (no channels).
+
+        .. versionchanged:: 3.3
+            Added *broadcast_channel* and *observe_channels* arguments.
         """
 
 
@@ -89,9 +147,16 @@ class EssentialHub:
     light = _common.ColorLight()
     imu = _common.IMU()
     system = _common.System()
+    ble = _common.BLE()
 
-    def __init__(self, top_side=Axis.Z, front_side=Axis.X):
-        """__init__(top_side=Axis.Z, front_side=Axis.X)
+    def __init__(
+        self,
+        top_side: Axis = Axis.Z,
+        front_side: Axis = Axis.X,
+        broadcast_channel: int = 0,
+        observe_channels: Sequence[int] = [],
+    ):
+        """EssentialHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=0, observe_channels=[])
 
         Initializes the hub. Optionally, specify how the hub is
         :ref:`placed in your design <robotframe>` by saying in which
@@ -103,6 +168,16 @@ class EssentialHub:
                 the hub.
             front_side (Axis): The axis that passes through the *front side* of
                 the hub.
+            broadcast_channel:
+                A value from 0 to 255 indicating which channel ``hub.ble.broadcast()``
+                will use. Default is channel 0.
+            observe_channels:
+                A list of channels to listen to when ``hub.ble.observe()`` is
+                called. Listening to more channels requires more memory.
+                Default is an empty list (no channels).
+
+        .. versionchanged:: 3.3
+            Added *broadcast_channel* and *observe_channels* arguments.
         """
         pass
 
@@ -127,9 +202,16 @@ class PrimeHub:
     speaker = _common.Speaker()
     imu = _common.IMU()
     system = _common.System()
+    ble = _common.BLE()
 
-    def __init__(self, top_side: Axis = Axis.Z, front_side: Axis = Axis.X):
-        """PrimeHub(top_side=Axis.Z, front_side=Axis.X)
+    def __init__(
+        self,
+        top_side: Axis = Axis.Z,
+        front_side: Axis = Axis.X,
+        broadcast_channel: int = 0,
+        observe_channels: Sequence[int] = [],
+    ):
+        """PrimeHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=0, observe_channels=[])
 
         Initializes the hub. Optionally, specify how the hub is
         :ref:`placed in your design <robotframe>` by saying in which
@@ -141,6 +223,16 @@ class PrimeHub:
                 the hub.
             front_side (Axis): The axis that passes through the *front side* of
                 the hub.
+            broadcast_channel:
+                A value from 0 to 255 indicating which channel ``hub.ble.broadcast()``
+                will use. Default is channel 0.
+            observe_channels:
+                A list of channels to listen to when ``hub.ble.observe()`` is
+                called. Listening to more channels requires more memory.
+                Default is an empty list (no channels).
+
+        .. versionchanged:: 3.3
+            Added *broadcast_channel* and *observe_channels* arguments.
         """
 
 

{pybricks-3.3.0a4 → pybricks-3.3.0b9}/src/pybricks/iodevices.py

@@ -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

{pybricks-3.3.0a4 → pybricks-3.3.0b9}/src/pybricks/pupdevices.py

@@ -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
 
 
@@ -63,10 +70,12 @@ class Motor(_common.Motor):
                 Choose ``False`` to keep the
                 current value, so your program knows where it left off last
                 time.
-            profile (Number, deg): Precision profile. A lower value
-                means more precise movement; a larger value means
-                smoother movement. If no value is given, a suitable profile for
-                this motor type will be selected automatically.
+            profile (Number, deg): Precision profile. This is the approximate
+                position tolerance in degrees that is acceptable in your
+                application. A lower value gives more precise but more erratic
+                movement; a higher value gives less precise but smoother
+                movement. If no value is given, a suitable profile for this
+                motor type will be selected automatically (about 11 degrees).
         """
 
     def reset_angle(self, angle: Optional[Number] = None) -> None:
@@ -97,7 +106,7 @@ class Remote:
             Button.RIGHT_PLUS,
         )
     )
-    addresss: Union[str, None]
+    address: Union[str, None]
 
     def __init__(self, name: Optional[str] = None, timeout: int = 10000):
         """Remote(name=None, timeout=10000)
@@ -144,7 +153,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 +166,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 +176,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 +187,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 +213,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 +267,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 +279,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 +300,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 +309,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 +318,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 +330,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 +358,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 +371,7 @@ class ColorLightMatrix:
         """
         ...
 
-    def off(self) -> None:
+    def off(self) -> MaybeAwaitable:
         """off()
 
         Turns all lights off.
@@ -354,7 +389,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 +399,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 +409,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 +450,10 @@ if TYPE_CHECKING:
     del Button
     del Color
     del Direction
+    del MaybeAwaitable
+    del MaybeAwaitableBool
+    del MaybeAwaitableFloat
+    del MaybeAwaitableInt
+    del MaybeAwaitableTuple
     del Number
     del Port

{pybricks-3.3.0a4 → pybricks-3.3.0b9}/src/pybricks/robotics.py

@@ -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
 
 
@@ -86,6 +86,12 @@ class DriveBase:
 
         Stops the robot by letting the motors spin freely."""
 
+    def brake(self) -> None:
+        """brake()
+
+        Stops the robot by passively braking the motors.
+        """
+
     def distance(self) -> int:
         """distance() -> int: mm
 
@@ -161,7 +167,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 +179,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 +195,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.
@@ -221,15 +229,21 @@ class DriveBase:
             ``True`` if the drivebase is stalled, ``False`` if not.
         """
 
+    def use_gyro(self, use_gyro: bool) -> None:
+        """use_gyro(use_gyro)
 
-class GyroDriveBase(DriveBase):
-    """A robotic vehicle with two powered wheels and an optional support
-    wheel or caster. It measures the heading using the hub's built-in gyroscope,
-    which can make turning and driving straight more accurate."""
+        Choose ``True`` to use the gyro sensor for turning and driving
+        straight. Choose ``False`` to rely only on the motor's built-in
+        rotation sensors.
+
+        Arguments:
+            use_gyro (bool): ``True`` to enable, ``False`` to disable.
+        """
 
 
 # HACK: hide from jedi
 if TYPE_CHECKING:
     del Motor
     del Number
+    del MaybeAwaitable
     del Stop

{pybricks-3.3.0a4 → pybricks-3.3.0b9}/src/pybricks/tools.py

@@ -5,13 +5,14 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Sequence, Tuple, overload
+from typing import TYPE_CHECKING, Any, Optional, Sequence, Tuple, overload, Coroutine
 
 if TYPE_CHECKING:
+    from ._common import MaybeAwaitable, MaybeAwaitableTuple
     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.
@@ -222,6 +223,72 @@ def cross(a: Matrix, b: Matrix) -> Matrix:
     """
 
 
+def read_input_byte() -> Optional[int]:
+    """
+    read_input_byte() -> int | None
+
+    Reads one byte from standard input without blocking.
+
+    Returns:
+        The numeric value of the byte read or ``None`` if no data is available.
+    """
+
+
+def hub_menu(*symbols: int | str) -> int | str:
+    """
+    hub_menu(symbol1, symbol2, ...) -> int | str
+
+    Shows a menu on the hub display and waits for the user to select an item
+    using the buttons. Can be used in your own menu-program that lets you
+    choose which of your other programs to run.
+
+    Note that this is just a convenience function that combines the display,
+    buttons, and waits to make a simple menu. This means that it can be used
+    anywhere in a program, not just at the start.
+
+    Arguments:
+        symbol1 (int or str): The first symbol to show in the menu.
+        symbol2 (int or str): The second symbol, and so on...
+
+    Returns:
+        The selected symbol.
+    """
+
+
+def multitask(*coroutines: Coroutine, race=False) -> MaybeAwaitableTuple:
+    """
+    multitask(coroutine1, coroutine2, ...) -> Tuple
+
+    Runs multiple coroutines concurrently. This creates a new coroutine that
+    can be used like any other, including in another ``multitask`` statement.
+
+    Arguments:
+        coroutines (coroutine, coroutine, ...): One or more coroutines to run
+            in parallel.
+        race (bool): Choose ``False`` to wait for all coroutines to finish.
+            Choose ``True`` to wait for one coroutine to finish and then
+            cancel the others, as if it's a "race".
+
+    Returns:
+        Tuple of the return values of each coroutine. Unfinished coroutines
+        will have ``None`` as their return value.
+    """
+
+
+def run_task(coroutine: Coroutine):
+    """
+    run_task(coroutine)
+
+    Runs a coroutine from start to finish while blocking the rest of the
+    program. This is used primarily to run the main coroutine of a program.
+
+    Arguments:
+        coroutine (coroutine): The main coroutine to run.
+    """
+
+
 # HACK: hide from jedi
 if TYPE_CHECKING:
     del Number
+    del MaybeAwaitable
+    del MaybeAwaitableTuple