step.timeout_dsl
================

.. py:module:: step.timeout_dsl

.. autoapi-nested-parse::

   Auto-generated step builders and DSL functions — DO NOT EDIT.

   Source: timeout.py



Classes
-------

.. autoapisummary::

   step.timeout_dsl.TimeoutBuilder


Functions
---------

.. autoapisummary::

   step.timeout_dsl.timeout


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

.. py:class:: TimeoutBuilder

   Bases: :py:obj:`raccoon.step.step_builder.StepBuilder`


   Builder for Timeout. Auto-generated — do not edit.


   .. py:method:: step(value: step.Step)


   .. py:method:: seconds(value: Union[float, int])


.. py:function:: timeout(step: step.Step = _UNSET, seconds: Union[float, int] = _UNSET)

   Wrap a step with a time limit, cancelling it if it runs too long.

   Executes the given step normally but enforces a maximum wall-clock
   duration. If the wrapped step completes within the budget, the
   timeout step finishes successfully. If the step exceeds the time
   limit, it is cancelled via ``asyncio.wait_for`` and an error is
   logged. Any exception raised by the wrapped step propagates
   normally.

   This is especially useful around blocking steps like
   ``motor_move_to`` or ``wait_for_button`` that could stall
   indefinitely if the hardware misbehaves.

   :param step: The step to execute under a time constraint. Must be a valid ``Step`` (or ``StepProtocol``) instance.
   :param seconds: Maximum allowed execution time in seconds. Must be positive.

   :returns: A TimeoutBuilder (chainable via ``.step()``, ``.seconds()``, ``.on_anomaly()``, ``.skip_timing()``).

   Example::

       from raccoon.step import timeout
       from raccoon.step.motor import motor_move_to

       # Give the arm 5 seconds to reach position 300; cancel if stuck
       timeout(
           motor_move_to(robot.motor(2), position=300, velocity=800),
           seconds=5.0,
       )

       # Ensure operator presses button within 30 seconds
       timeout(wait_for_button(), seconds=30.0)