pybricks 3.4.1__tar.gz → 3.5.0b2__tar.gz

{pybricks-3.4.1 → pybricks-3.5.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pybricks
-Version: 3.4.1
+Version: 3.5.0b2
 Summary: Documentation and user-API stubs for Pybricks MicroPython
 Home-page: https://pybricks.com
 License: MIT

{pybricks-3.4.1 → pybricks-3.5.0b2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pybricks"
-version = "3.4.1"
+version = "3.5.0b2"
 description = "Documentation and user-API stubs for Pybricks MicroPython"
 authors = ["The Pybricks Authors <team@pybricks.com>"]
 maintainers = ["Laurens Valk <laurens@pybricks.com>", "David Lechner <david@pybricks.com>" ]

{pybricks-3.4.1 → pybricks-3.5.0b2}/src/pybricks/_common.py

@@ -60,7 +60,8 @@ class System:
             button (Button): A button such
                 as :attr:`Button.CENTER <pybricks.parameters.Button.CENTER>`,
                 or a tuple of multiple buttons. Choose ``None`` to disable the
-                stop button altogether.
+                stop button altogether. If you do, you can still turn the hub
+                off by holding the center button for three seconds.
         """
 
     def shutdown(self) -> None:

{pybricks-3.4.1 → pybricks-3.5.0b2}/src/pybricks/iodevices.py

@@ -12,6 +12,7 @@ from .parameters import Port as _Port
 
 if TYPE_CHECKING:
     from ._common import MaybeAwaitable, MaybeAwaitableTuple
+    from .parameters import Number
 
 
 class PUPDevice:
@@ -298,7 +299,7 @@ class LWP3Device:
         """
 
     @overload
-    def name(self, name: str) -> None: ...
+    def name(self, name: str) -> MaybeAwaitable: ...
 
     @overload
     def name(self) -> str: ...
@@ -335,6 +336,12 @@ class LWP3Device:
             The raw binary message.
         """
 
+    def disconnect(self) -> MaybeAwaitable:
+        """disconnect()
+
+        Disconnects the remote LWP3Device from the hub.
+        """
+
 
 class XboxController:
     """Use the Microsoft® Xbox® controller as a sensor in your projects to
@@ -384,12 +391,17 @@ class XboxController:
     def dpad(self) -> int:
         """dpad() -> int
 
-        Gets the direction-pad position. ``1`` is up, ``2`` is up-right,
-        ``3`` is right, ``4`` is down-right, ``5`` is down, ``6`` is
-        down-left, ``7`` is left, ``8`` is up-left, and ``0`` is not pressed.
+        Gets the direction-pad value. ``1`` is up, ``2`` is up-right, ``3``
+        is right, ``4`` is down-right, ``5`` is down, ``6`` is down-left,
+        ``7`` is left, ``8`` is up-left, and ``0`` is not pressed.
+
+        This is essentially the same as reading the state of the
+        ``Button.UP``, ``Button.RIGHT``, ``Button.DOWN``, and ``Button.LEFT``
+        buttons, but this method conveniently returns a number that indicates
+        a direction.
 
         Returns:
-            Direction-pad position.
+            Direction-pad position, indicating a direction.
         """
 
     def profile(self) -> int:
@@ -402,8 +414,39 @@ class XboxController:
             Profile number.
         """
 
+    def rumble(
+        self,
+        power: Number | Tuple[Number, Number, Number, Number] = 100,
+        duration: int = 200,
+        count: int = 1,
+        delay: int = 100,
+    ) -> MaybeAwaitable:
+        """rumble(power=100, duration=200, count=1, delay=100)
+
+        Makes the builtin actuators rumble, creating force feedback.
+
+        If you give a single ``power`` value, the left and right main actuators
+        will both rumble with that power. For more fine-grained control, set
+        ``power`` as a tuple of four values, which control the left main
+        actuator, right main actuator, left trigger actuator, and the right
+        trigger actuator, respectively. For example, ``power=(0, 0, 100, 0)``
+        makes the left trigger rumble at full power.
+
+        The rumble runs in the background while your program continues. To
+        make your program wait, just pause the program for a matching duration.
+        For one rumble, this equals ``duration``. For multiple rumbles, this
+        equals ``count * (duration + delay)``.
+
+        Arguments:
+            power (Number, % or tuple): Rumble power.
+            duration (Number, ms): Rumble duration.
+            count (int): Rumble count.
+            delay (Number, ms): Delay before each rumble. Only if ``count > 1``.
+        """
+
 
 # hide from jedi
 if TYPE_CHECKING:
     del MaybeAwaitable
     del MaybeAwaitableTuple
+    del Number

{pybricks-3.4.1 → pybricks-3.5.0b2}/src/pybricks/pupdevices.py

@@ -143,6 +143,12 @@ class Remote:
                 this method returns the current name.
         """
 
+    def disconnect(self) -> MaybeAwaitable:
+        """disconnect()
+
+        Disconnects the remote from the hub.
+        """
+
 
 class TiltSensor:
     """LEGO® Powered Up Tilt Sensor."""

{pybricks-3.4.1 → pybricks-3.5.0b2}/src/pybricks/tools.py

@@ -211,14 +211,23 @@ def cross(a: Matrix, b: Matrix) -> Matrix:
     """
 
 
-def read_input_byte() -> Optional[int]:
+def read_input_byte(last: bool = False, chr: bool = False) -> Optional[int | str]:
     """
-    read_input_byte() -> int | None
+    read_input_byte() -> int | str | None
 
-    Reads one byte from standard input without blocking.
+    Reads one byte from standard input without blocking and removes it from the
+    input buffer.
+
+    Arguments:
+        last (bool): Choose ``True`` to read the last (most recent) byte in the buffer and discard the rest.
+                     Choose ``False`` to read only the first (oldest) byte.
+        chr (bool): Choose ``True`` to convert the result to a one-character string.
 
     Returns:
-        The numeric value of the byte read or ``None`` if no data is available.
+        The byte that was read, as a numeric value (``0`` to ``255``) or
+        string (e.g. ``"B"``). Returns ``None`` if no data is available. If
+        ``chr=True``, it also return ``None`` if the byte that was read is not
+        printable as a character.
     """