scirodev 0.5.4__tar.gz → 0.5.6__tar.gz

{scirodev-0.5.4/scirodev.egg-info → scirodev-0.5.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scirodev
-Version: 0.5.4
+Version: 0.5.6
 Summary: PeakHub / sciro extensions to Pybricks: typed API stubs (sciro.*) and hub tooling on top of pybricksdev
 Author: Thomas Schank
 License: MIT

{scirodev-0.5.4 → scirodev-0.5.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scirodev"
-version = "0.5.4"
+version = "0.5.6"
 description = "PeakHub / sciro extensions to Pybricks: typed API stubs (sciro.*) and hub tooling on top of pybricksdev"
 readme = "README.md"
 requires-python = ">=3.10"

{scirodev-0.5.4 → scirodev-0.5.6}/sciro/hubs.py

@@ -1,7 +1,8 @@
 """sciro.hubs -- the PeakHub.
 
 On the hub this module re-exports ``pybricks.hubs`` unchanged; the stub adds what
-the upstream stubs lack: the ``PeakHub`` class and its ``display.device()``.
+the upstream stubs lack: the ``PeakHub`` class, its ``display.device()``, and the
+``ThisHub`` alias.
 """
 
 from __future__ import annotations
@@ -150,3 +151,32 @@ class PeakHub:
             broadcast_channel: Channel for broadcasting data (0 .. 255).
             observe_channels: Channels to observe.
         """
+
+
+#: The hub this program is running on.
+#:
+#: Every Pybricks firmware compiles in exactly one hub class and exports it
+#: under several names: the generic ``ThisHub``, the hub's own name, and any
+#: aliases. On PeakHub firmware ``ThisHub``, :class:`PeakHub`, ``PrimeHub`` and
+#: ``InventorHub`` are therefore all the *same* class object -- this is resolved
+#: when the firmware is built, not by detecting anything at run time.
+#:
+#: Use it for code that should run unchanged on whichever hub is in front of
+#: you, which is mostly bench and test scripts::
+#:
+#:     from sciro.hubs import ThisHub
+#:
+#:     hub = ThisHub()
+#:     print(hub.imu.heading(), hub.imu.tilt())
+#:
+#: Prefer :class:`PeakHub` when a program is specific to this hub anyway: it
+#: says so, and it reads better than a generic name.
+#:
+#: Note the difference between the REPL and a downloaded program. The REPL is
+#: started with everything auto-imported and with a ready-made ``hub`` instance
+#: already created, so there ``hub.imu.heading()`` just works. A downloaded
+#: program gets neither: it must import what it uses and construct the hub, as
+#: above, and ``print(hub)`` there raises ``NameError``. (In the firmware this
+#: is ``pb_package_pybricks_init(true)`` for the REPL versus ``false`` for
+#: everything else.)
+ThisHub = PeakHub

{scirodev-0.5.4 → scirodev-0.5.6}/sciro/robotics.py

@@ -73,19 +73,74 @@ class DriveBase(_DriveBase):
         upstream meaning: continue at the drive speed.
         """
 
+    def turn(  # type: ignore[override]
+        self,
+        angle: Number,
+        then: Stop = Stop.HOLD,
+        wait: bool = True,
+        absolute: bool = False,
+        turn_rate: Optional[Number] = None,
+    ) -> MaybeAwaitable:
+        """turn(angle, then=Stop.HOLD, wait=True, absolute=False, turn_rate=None)
+
+        Turns in place, as in Pybricks, with one PeakHub extension:
+
+        ``turn_rate``: turn rate in deg/s for this move only; ``None`` uses the
+        ``turn_rate`` setting, which is left untouched either way.
+
+        ``absolute=True`` turns *to* the given heading rather than *by* it,
+        taking the nearest whole-turn equivalent, so the correction is always
+        within +/-180 degrees (the same rule as ``straight(heading=)``).
+        """
+
     def curve(
         self,
         radius: Number,
         angle: Number,
         then: Stop = Stop.HOLD,
         wait: bool = True,
+        speed: Optional[Number] = None,
+        exit_speed: Number = 0,
     ) -> MaybeAwaitable:
-        """curve(radius, angle, then=Stop.HOLD, wait=True)
+        """curve(radius, angle, then=Stop.HOLD, wait=True, speed=None, exit_speed=0)
 
         Drives an arc of ``angle`` degrees along a circle of ``radius`` mm.
-        The firmware still has this method, but the ``pybricks`` stubs dropped
-        it in favor of :meth:`arc`, so it is declared here to keep it usable
-        without a type error. Prefer ``arc()`` in new code.
+        Upstream dropped this method in favour of :meth:`arc`, but the firmware
+        still has it, so it is declared here to keep it usable without a type
+        error. ``arc()`` takes the same extensions and is preferred in new code.
+
+        ``speed``: drive speed in mm/s along the arc for this move only. The
+        matching turn rate is derived from it, so the linear speed is what
+        governs the duration; ``None`` uses the ``straight_speed`` and
+        ``turn_rate`` settings.
+
+        ``exit_speed``: speed in mm/s the robot has when it reaches the end of
+        the arc. The *turn rate is brought to zero* at that point, so the robot
+        leaves on the tangent and keeps driving straight at ``exit_speed``
+        until the next command. This makes a curve-to-straight handover smooth;
+        without it a continuing move keeps rotating at the arc's turn rate and
+        the next command has to cancel that rotation. The price is that the
+        last fraction of the path is slightly flatter than a true arc. Implies
+        ``then=Stop.NONE``; any other explicit ``then`` raises ``ValueError``.
+        """
+
+    def arc(  # type: ignore[override]
+        self,
+        radius: Number,
+        angle: Optional[Number] = None,
+        distance: Optional[Number] = None,
+        then: Stop = Stop.HOLD,
+        wait: bool = True,
+        speed: Optional[Number] = None,
+        exit_speed: Number = 0,
+    ) -> MaybeAwaitable:
+        """arc(radius, angle=None, distance=None, then=Stop.HOLD, wait=True, speed=None, exit_speed=0)
+
+        Drives an arc, as in Pybricks, with the same two PeakHub extensions as
+        :meth:`curve`: ``speed`` in mm/s for this move only (the turn rate is
+        derived from it), and ``exit_speed``, which ends the arc at that speed
+        with the turn rate at zero so the robot exits on the tangent and keeps
+        driving straight. ``exit_speed`` implies ``then=Stop.NONE``.
         """
 
     def heading_target(self, angle: Optional[Number] = None) -> Optional[float]:

{scirodev-0.5.4 → scirodev-0.5.6/scirodev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scirodev
-Version: 0.5.4
+Version: 0.5.6
 Summary: PeakHub / sciro extensions to Pybricks: typed API stubs (sciro.*) and hub tooling on top of pybricksdev
 Author: Thomas Schank
 License: MIT