Deprecate deadlineWith and add deadlineFor instead

From wpilibsuite/allwpilib#6544

Author: spacey-sooty

Diff for: .gittrack

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

Diff for: commands2/command.py

@@ -266,6 +266,35 @@ def deadlineWith(self, *parallel: Command) -> ParallelDeadlineGroup:
         command ends and interrupting all the others. Often more convenient/less-verbose than
         constructing a new ParallelDeadlineGroup explicitly.
 
+        .. note:: This decorator works by adding this command to a composition.
+                  The command the decorator was called on cannot be scheduled
+                  independently or be added to a different composition (namely,
+                  decorators), unless it is manually cleared from the list of composed
+                  commands with :func:`commands2.CommandScheduler.removeComposedCommand`.
+                  The command composition returned from this method can be further
+                  decorated without issue.
+
+        :param parallel: the commands to run in parallel
+        :returns: the decorated command
+        """
+        import warnings
+
+        warnings.warn(
+            "deadlineWith is deprecated use deadlineFor instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+        from .paralleldeadlinegroup import ParallelDeadlineGroup
+
+        return ParallelDeadlineGroup(self, *parallel)
+
+    def deadlineFor(self, *parallel: Command) -> ParallelDeadlineGroup:
+        """
+        Decorates this command with a set of commands to run parallel to it, ending when the calling
+        command ends and interrupting all the others. Often more convenient/less-verbose than
+        constructing a new ParallelDeadlineGroup explicitly.
+
         .. note:: This decorator works by adding this command to a composition.
                   The command the decorator was called on cannot be scheduled
                   independently or be added to a different composition (namely,

Diff for: tests/test_command_decorators.py

@@ -96,6 +96,24 @@ def test_deadlineWith(scheduler: commands2.CommandScheduler):
     assert not group.isScheduled()
 
 
+def test_deadlineFor(scheduler: commands2.CommandScheduler):
+    condition = OOBoolean(False)
+    condition.set(False)
+
+    dictator = commands2.WaitUntilCommand(condition)
+    endsBefore = commands2.InstantCommand()
+    endsAfter = commands2.WaitUntilCommand(lambda: False)
+
+    group = dictator.deadlineFor(endsBefore, endsAfter)
+
+    scheduler.schedule(group)
+    scheduler.run()
+    assert group.isScheduled()
+    condition.set(True)
+    scheduler.run()
+    assert not group.isScheduled()
+
+
 def test_alongWith(scheduler: commands2.CommandScheduler):
     condition = OOBoolean()
     condition.set(False)