step.timeout_or
===============

.. py:module:: step.timeout_or


Classes
-------

.. autoapisummary::

   step.timeout_or.TimeoutOr


Functions
---------

.. autoapisummary::

   step.timeout_or.timeout_or


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

.. py:class:: TimeoutOr(step: step.Step, seconds: Union[float, int], fallback: step.Step)

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


   Run a step with a time limit; execute a fallback step if it times out.


   .. py:attribute:: step


   .. py:attribute:: seconds


   .. py:attribute:: fallback


   .. py:method:: collected_resources() -> frozenset[str]


.. py:function:: timeout_or(step: step.Step, seconds: Union[float, int], fallback: step.Step) -> TimeoutOr

   Run a step with a time limit, executing a fallback step if it times out.

   Executes ``step`` normally and enforces a maximum wall-clock duration. If
   the step completes within the budget it finishes successfully and the
   fallback is never run. If ``step`` exceeds the time limit it is cancelled
   and ``fallback`` is executed in its place.

   This is useful when a motion step might stall (e.g., a drive that never
   reaches its target) and you want a recovery action rather than simply
   logging an error and moving on.

   :param step: The primary step to execute under a time constraint. Must be a
                valid ``Step`` instance.
   :param seconds: Maximum allowed execution time in seconds. Must be positive.
   :param fallback: The step to execute when ``step`` times out.

   :returns: A TimeoutOr step instance.

   Example::

       from raccoon.step import timeout_or
       from raccoon.step.motion import drive_forward, drive_backward

       # Try driving forward 30 cm; if stuck after 3 s, back up 5 cm instead
       timeout_or(
           drive_forward(30),
           seconds=3.0,
           fallback=drive_backward(5),
       )