step.step_builder
=================

.. py:module:: step.step_builder

.. autoapi-nested-parse::

   Base class for auto-generated step builders.

   A StepBuilder collects constructor arguments via fluent methods and
   implements ``StepProtocol`` so it can be used directly in ``seq([...])``.
   When executed, it builds the real Step and delegates to it.

   Builder classes are generated by raccoon codegen from ``@dsl_step``-decorated
   Step classes.  Each ``__init__`` parameter becomes a fluent setter method,
   and a snake_case factory function is generated alongside.



Classes
-------

.. autoapisummary::

   step.step_builder.StepBuilder


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

.. py:class:: StepBuilder

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


   Base class for generated step builders.

   Subclasses must implement ``_build()`` to construct the real Step
   from the collected parameters.

   Since StepBuilder extends Step, it satisfies StepProtocol and can be
   used anywhere a Step is expected (seq, parallel, mission step lists).


   .. py:method:: on_anomaly(callback_or_step: Union[StepAnomalyCallback, Step]) -> StepBuilder

      Register a callback or step invoked when a timing anomaly is detected.

      Accepts either an async callback ``(step, robot) -> None`` or a
      ``Step`` instance to run when the anomaly fires::

          drive_forward(25).on_anomaly(my_handler)

          async def my_handler(step, robot):
              ...

          # Or pass a step directly:
          drive_forward(25).on_anomaly(play_sound())



   .. py:method:: skip_timing() -> StepBuilder

      Exclude this step from timing anomaly tracking.

      Use for steps whose duration is inherently variable
      (e.g., condition-only drives, user-input waits).



   .. py:method:: resolve() -> step.base.Step

      Build the underlying Step and apply any chained options.

      Idempotent — composite constructors call this to replace a builder
      with its real Step at validation time, so resource conflict checks
      and signature lookups see the actual underlying step rather than
      an empty builder placeholder. Subsequent calls return the cached
      instance, so this is safe even if a builder ends up reachable from
      multiple parents.

      Once a builder has been resolved, mutating it via ``on_anomaly()``
      or ``skip_timing()`` is a no-op against the cached step — call
      those before placing the builder inside a composite.