Merge pull request #46 from robotpy/review

Commands QA review

Author: virtuald

.gittrack

@@ -0,0 +1,5 @@
+[git-source-track]
+upstream_root = ../allwpilib/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command
+upstream_branch = main
+upstream_commit = 4595f84719759d71491e11e8df55d60ce2a6154c
+validation_root = commands2

commands2/__init__.py

@@ -1,40 +1,21 @@
-from .button import Trigger
 from .command import Command, InterruptionBehavior
 
+from . import button
 from . import cmd
 
-# from .cmd import (
-#     deadline,
-#     either,
-#     none,
-#     parallel,
-#     print_,
-#     race,
-#     repeatingSequence,
-#     run,
-#     runEnd,
-#     runOnce,
-#     select,
-#     sequence,
-#     startEnd,
-#     waitSeconds,
-#     waitUntil,
-# )
-from .commandgroup import CommandGroup, IllegalCommandUse
 from .commandscheduler import CommandScheduler
 from .conditionalcommand import ConditionalCommand
+from .exceptions import IllegalCommandUse
 from .functionalcommand import FunctionalCommand
 from .instantcommand import InstantCommand
 from .notifiercommand import NotifierCommand
 from .parallelcommandgroup import ParallelCommandGroup
 from .paralleldeadlinegroup import ParallelDeadlineGroup
 from .parallelracegroup import ParallelRaceGroup
-from .perpetualcommand import PerpetualCommand
 from .pidcommand import PIDCommand
 from .pidsubsystem import PIDSubsystem
 from .printcommand import PrintCommand
 from .proxycommand import ProxyCommand
-from .proxyschedulecommand import ProxyScheduleCommand
 from .repeatcommand import RepeatCommand
 from .runcommand import RunCommand
 from .schedulecommand import ScheduleCommand
@@ -52,9 +33,9 @@
 from typing import TYPE_CHECKING
 
 __all__ = [
+    "button",
     "cmd",
     "Command",
-    "CommandGroup",
     "CommandScheduler",
     "ConditionalCommand",
     "FunctionalCommand",
@@ -65,12 +46,10 @@
     "ParallelCommandGroup",
     "ParallelDeadlineGroup",
     "ParallelRaceGroup",
-    "PerpetualCommand",
     "PIDCommand",
     "PIDSubsystem",
     "PrintCommand",
     "ProxyCommand",
-    "ProxyScheduleCommand",
     "RepeatCommand",
     "RunCommand",
     "ScheduleCommand",
@@ -84,22 +63,6 @@
     "WaitCommand",
     "WaitUntilCommand",
     "WrapperCommand",
-    # "none",
-    # "runOnce",
-    # "run",
-    # "startEnd",
-    # "runEnd",
-    # "print_",
-    # "waitSeconds",
-    # "waitUntil",
-    # "either",
-    # "select",
-    # "sequence",
-    # "repeatingSequence",
-    # "parallel",
-    # "race",
-    # "deadline",
-    "Trigger",  # was here in 2023
 ]
 
 if not TYPE_CHECKING:

commands2/button/commandgenerichid.py

@@ -1,3 +1,4 @@
+# validated: 2024-01-20 DS 92149efa11fa button/CommandGenericHID.java
 from typing import Optional
 
 from wpilib.event import EventLoop
@@ -9,7 +10,7 @@
 
 class CommandGenericHID:
     """
-    A version of GenericHID with Trigger factories for command-based.
+    A version of :class:`wpilib.interfaces.GenericHID` with :class:`.Trigger` factories for command-based.
     """
 
     def __init__(self, port: int):
@@ -31,7 +32,10 @@ def button(self, button: int, loop: Optional[EventLoop] = None) -> Trigger:
         Constructs an event instance around this button's digital signal.
 
         :param button: The button index
-        :param loop: the event loop instance to attache the event to.
+        :param loop: the event loop instance to attach the event to, defaults
+                     to :func:`commands2.CommandScheduler.getDefaultButtonLoop`
+
+        :returns: A trigger instance attached to the event loop
         """
         if loop is None:
             loop = CommandScheduler.getInstance().getDefaultButtonLoop()
@@ -48,8 +52,9 @@ def pov(
 
         :param angle: POV angle in degrees, or -1 for the center / not pressed.
         :param pov: index of the POV to read (starting at 0). Defaults to 0.
-        :param loop: the event loop instance to attach the event to. Defaults to {@link
-            CommandScheduler#getDefaultButtonLoop() the default command scheduler button loop}.
+        :param loop: the event loop instance to attach the event to, defaults
+                     to :func:`commands2.CommandScheduler.getDefaultButtonLoop`
+
         :returns: a Trigger instance based around this angle of a POV on the HID.
         """
         if loop is None:
@@ -59,8 +64,7 @@ def pov(
     def povUp(self) -> Trigger:
         """
         Constructs a Trigger instance based around the 0 degree angle (up) of the default (index 0) POV
-        on the HID, attached to {@link CommandScheduler#getDefaultButtonLoop() the default command
-        scheduler button loop}.
+        on the HID, attached to :func:`commands2.CommandScheduler.getDefaultButtonLoop`
 
         :returns: a Trigger instance based around the 0 degree angle of a POV on the HID.
         """
@@ -69,8 +73,7 @@ def povUp(self) -> Trigger:
     def povUpRight(self) -> Trigger:
         """
         Constructs a Trigger instance based around the 45 degree angle (right up) of the default (index
-        0) POV on the HID, attached to {@link CommandScheduler#getDefaultButtonLoop() the default
-        command scheduler button loop}.
+        0) POV on the HID, attached to :func:`commands2.CommandScheduler.getDefaultButtonLoop`.
 
         :returns: a Trigger instance based around the 45 degree angle of a POV on the HID.
         """
@@ -79,8 +82,7 @@ def povUpRight(self) -> Trigger:
     def povRight(self) -> Trigger:
         """
         Constructs a Trigger instance based around the 90 degree angle (right) of the default (index 0)
-        POV on the HID, attached to {@link CommandScheduler#getDefaultButtonLoop() the default command
-        scheduler button loop}.
+        POV on the HID, attached to :func:`commands2.CommandScheduler.getDefaultButtonLoop`.
 
         :returns: a Trigger instance based around the 90 degree angle of a POV on the HID.
         """
@@ -89,8 +91,7 @@ def povRight(self) -> Trigger:
     def povDownRight(self) -> Trigger:
         """
         Constructs a Trigger instance based around the 135 degree angle (right down) of the default
-        (index 0) POV on the HID, attached to {@link CommandScheduler#getDefaultButtonLoop() the
-        default command scheduler button loop}.
+        (index 0) POV on the HID, attached to :func:`commands2.CommandScheduler.getDefaultButtonLoop`.
 
         :returns: a Trigger instance based around the 135 degree angle of a POV on the HID.
         """
@@ -99,8 +100,7 @@ def povDownRight(self) -> Trigger:
     def povDown(self) -> Trigger:
         """
         Constructs a Trigger instance based around the 180 degree angle (down) of the default (index 0)
-        POV on the HID, attached to {@link CommandScheduler#getDefaultButtonLoop() the default command
-        scheduler button loop}.
+        POV on the HID, attached to :func:`commands2.CommandScheduler.getDefaultButtonLoop`.
 
         :returns: a Trigger instance based around the 180 degree angle of a POV on the HID.
         """
@@ -109,8 +109,7 @@ def povDown(self) -> Trigger:
     def povDownLeft(self) -> Trigger:
         """
         Constructs a Trigger instance based around the 225 degree angle (down left) of the default
-        (index 0) POV on the HID, attached to {@link CommandScheduler#getDefaultButtonLoop() the
-        default command scheduler button loop}.
+        (index 0) POV on the HID, attached to :func:`commands2.CommandScheduler.getDefaultButtonLoop`.
 
         :returns: a Trigger instance based around the 225 degree angle of a POV on the HID.
         """
@@ -119,8 +118,7 @@ def povDownLeft(self) -> Trigger:
     def povLeft(self) -> Trigger:
         """
         Constructs a Trigger instance based around the 270 degree angle (left) of the default (index 0)
-        POV on the HID, attached to {@link CommandScheduler#getDefaultButtonLoop() the default command
-        scheduler button loop}.
+        POV on the HID, attached to :func:`commands2.CommandScheduler.getDefaultButtonLoop`.
 
         :returns: a Trigger instance based around the 270 degree angle of a POV on the HID.
         """
@@ -129,8 +127,7 @@ def povLeft(self) -> Trigger:
     def povUpLeft(self) -> Trigger:
         """
         Constructs a Trigger instance based around the 315 degree angle (left up) of the default (index
-        0) POV on the HID, attached to {@link CommandScheduler#getDefaultButtonLoop() the default
-        command scheduler button loop}.
+        0) POV on the HID, attached to :func:`commands2.CommandScheduler.getDefaultButtonLoop`.
 
         :returns: a Trigger instance based around the 315 degree angle of a POV on the HID.
         """
@@ -139,8 +136,7 @@ def povUpLeft(self) -> Trigger:
     def povCenter(self) -> Trigger:
         """
         Constructs a Trigger instance based around the center (not pressed) position of the default
-        (index 0) POV on the HID, attached to {@link CommandScheduler#getDefaultButtonLoop() the
-        default command scheduler button loop}.
+        (index 0) POV on the HID, attached to :func:`commands2.CommandScheduler.getDefaultButtonLoop`.
 
         :returns: a Trigger instance based around the center position of a POV on the HID.
         """
@@ -150,14 +146,15 @@ def axisLessThan(
         self, axis: int, threshold: float, loop: Optional[EventLoop] = None
     ) -> Trigger:
         """
-        Constructs a Trigger instance that is true when the axis value is less than {@code threshold},
+        Constructs a Trigger instance that is true when the axis value is less than ``threshold``,
         attached to the given loop.
 
         :param axis: The axis to read, starting at 0
         :param threshold: The value below which this trigger should return true.
         :param loop: the event loop instance to attach the trigger to
+
         :returns: a Trigger instance that is true when the axis value is less than the provided
-            threshold.
+                  threshold.
         """
         if loop is None:
             loop = CommandScheduler.getInstance().getDefaultButtonLoop()
@@ -167,14 +164,15 @@ def axisGreaterThan(
         self, axis: int, threshold: float, loop: Optional[EventLoop] = None
     ) -> Trigger:
         """
-        Constructs a Trigger instance that is true when the axis value is greater than {@code
-        threshold}, attached to the given loop.
+        Constructs a Trigger instance that is true when the axis value is greater than
+        ``threshold``, attached to the given loop.
 
         :param axis: The axis to read, starting at 0
         :param threshold: The value above which this trigger should return true.
         :param loop: the event loop instance to attach the trigger to.
+
         :returns: a Trigger instance that is true when the axis value is greater than the provided
-            threshold.
+                  threshold.
         """
         if loop is None:
             loop = CommandScheduler.getInstance().getDefaultButtonLoop()

commands2/button/commandjoystick.py

@@ -1,3 +1,4 @@
+# validated: 2024-01-20 DS 92aecab2ef05 button/CommandJoystick.java
 from typing import Optional
 
 from wpilib import Joystick
@@ -10,7 +11,7 @@
 
 class CommandJoystick(CommandGenericHID):
     """
-    A version of Joystick with Trigger factories for command-based.
+    A version of :class:`wpilib.Joystick` with :class:`.Trigger` factories for command-based.
     """
 
     _hid: Joystick
@@ -25,7 +26,7 @@ def __init__(self, port: int):
         super().__init__(port)
         self._hid = Joystick(port)
 
-    def getHID(self):
+    def getHID(self) -> Joystick:
         """
         Get the underlying GenericHID object.
 
@@ -37,7 +38,9 @@ def trigger(self, loop: Optional[EventLoop] = None) -> Trigger:
         """
         Constructs an event instance around the trigger button's digital signal.
 
-        :param loop: the event loop instance to attach the event to.
+        :param loop: the event loop instance to attach the event to, defaults
+                     to :func:`commands2.CommandScheduler.getDefaultButtonLoop`
+
         :returns: an event instance representing the trigger button's digital signal attached to the
             given loop.
         """
@@ -49,9 +52,11 @@ def top(self, loop: Optional[EventLoop] = None) -> Trigger:
         """
         Constructs an event instance around the top button's digital signal.
 
-        :param loop: the event loop instance to attach the event to.
+        :param loop: the event loop instance to attach the event to, defaults
+                     to :func:`commands2.CommandScheduler.getDefaultButtonLoop`
+
         :returns: an event instance representing the top button's digital signal attached to the given
-            loop.
+                  loop.
         """
         if loop is None:
             loop = CommandScheduler.getInstance().getDefaultButtonLoop()
@@ -121,21 +126,21 @@ def getZChannel(self) -> int:
         """
         return self._hid.getZChannel()
 
-    def getThrottleChannel(self) -> int:
+    def getTwistChannel(self) -> int:
         """
-        Get the channel currently associated with the throttle axis.
+        Get the channel currently associated with the twist axis.
 
         :returns: The channel for the axis.
         """
-        return self._hid.getThrottleChannel()
+        return self._hid.getTwistChannel()
 
-    def getTwistChannel(self) -> int:
+    def getThrottleChannel(self) -> int:
         """
-        Get the channel currently associated with the twist axis.
+        Get the channel currently associated with the throttle axis.
 
         :returns: The channel for the axis.
         """
-        return self._hid.getTwistChannel()
+        return self._hid.getThrottleChannel()
 
     def getX(self) -> float:
         """