libstp.step.logic.loop
======================

.. py:module:: libstp.step.logic.loop


Classes
-------

.. autoapisummary::

   libstp.step.logic.loop.LoopForeverStep
   libstp.step.logic.loop.LoopForStep


Functions
---------

.. autoapisummary::

   libstp.step.logic.loop.loop_forever
   libstp.step.logic.loop.loop_for


Module Contents
---------------

.. py:class:: LoopForeverStep(step: libstp.step.StepProtocol)

   Bases: :py:obj:`libstp.step.Step`


   Base async action executed by missions and higher-level step combinators.


   .. py:attribute:: step


.. py:class:: LoopForStep(step: libstp.step.StepProtocol, iterations: int)

   Bases: :py:obj:`libstp.step.Step`


   Base async action executed by missions and higher-level step combinators.


   .. py:attribute:: step


   .. py:attribute:: iterations


.. py:function:: loop_forever(step: libstp.step.StepProtocol) -> LoopForeverStep

   Repeat a step indefinitely until externally cancelled.

   Wraps the given step in an infinite loop. Each iteration awaits the
   child step to completion before starting the next. The loop only
   terminates when the enclosing context cancels it (e.g. via
   ``do_while_active`` or ``do_until_checkpoint``).

   :param step: The step to execute repeatedly. Must satisfy ``StepProtocol``.

   :returns: A step that runs ``step`` in an infinite loop.
   :rtype: LoopForeverStep

   Example::

       from libstp.step.logic import loop_forever
       from libstp.step.motor import set_motor_speed

       # Continuously toggle a motor on and off (until parent cancels)
       toggle = seq([
           set_motor_speed(0, 1000),
           wait(0.5),
           set_motor_speed(0, 0),
           wait(0.5),
       ])
       do_until_checkpoint(30.0, loop_forever(toggle))


.. py:function:: loop_for(step: libstp.step.StepProtocol, iterations: int) -> LoopForStep

   Repeat a step a fixed number of times.

   Wraps the given step in a counted loop. Each iteration awaits the
   child step to completion before starting the next. After all
   iterations complete, the step finishes normally.

   :param step: The step to execute repeatedly. Must satisfy ``StepProtocol``.
   :param iterations: Number of times to run the step. Must be a positive
                      integer.

   :returns: A step that runs ``step`` exactly ``iterations`` times.
   :rtype: LoopForStep

   Example::

       from libstp.step.logic import loop_for
       from libstp.step.motor import set_motor_speed

       # Drive forward in three short bursts
       burst = seq([
           set_motor_speed(0, 800),
           wait(0.3),
           set_motor_speed(0, 0),
           wait(0.2),
       ])
       loop_for(burst, 3)