step.annotation
===============

.. py:module:: step.annotation


Attributes
----------

.. autoapisummary::

   step.annotation.T
   step.annotation.F


Classes
-------

.. autoapisummary::

   step.annotation.DslMeta


Functions
---------

.. autoapisummary::

   step.annotation.dsl_step
   step.annotation.dsl


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

.. py:class:: DslMeta

   Discovery metadata attached by ``@dsl`` to steps and factories.


   .. py:attribute:: hidden
      :type:  bool
      :value: False



   .. py:attribute:: name
      :type:  Optional[str]
      :value: None



   .. py:attribute:: tags
      :type:  tuple[str, Ellipsis]
      :value: ()



.. py:data:: T

.. py:data:: F

.. py:function:: dsl_step(cls: T) -> T
                 dsl_step(cls: None = None, *, tags: Optional[list[str] | tuple[str, Ellipsis]] = None) -> Callable[[T], T]

   Mark a Step class for builder + DSL function generation.

   Codegen scans for classes decorated with ``@dsl_step``,
   introspects their ``__init__`` parameters, and generates:

   - A ``<ClassName>Builder(StepBuilder)`` with fluent setter methods
   - A ``snake_case()`` factory function decorated with ``@dsl(tags=...)``

   The marker also applies ``@dsl(hidden=True)`` so the raw class is
   hidden from the UI (users interact via the generated DSL function).

   Usage::

       @dsl_step(tags=["motion", "drive"])
       class DriveForward(MotionStep):
           def __init__(self, cm: float = None, speed: float = 1.0,
                        until: StopCondition = None):
               ...

   Codegen produces ``DriveForwardBuilder`` and ``drive_forward()``.
   Tags are propagated to the generated ``@dsl(tags=...)`` factory.


.. py:function:: dsl(_target: T) -> T
                 dsl(_target: F) -> F
                 dsl(_target: None = None, *, hidden: bool = False, name: Optional[str] = None, tags: Optional[list[str] | tuple[str, Ellipsis]] = None) -> Callable[[Union[T, F]], Union[T, F]]

   Mark a class or function as part of the DSL.

   Usage:
     @dsl
     class X(Step): ...

     @dsl(hidden=True, name="TurnLeft", tags=["movement", "rotation"])
     class Y(Step): ...

     @dsl(name="Wait", tags=["timing"])
     def wait_seconds(seconds: float) -> WaitStep:
         return WaitStep(seconds)

   :param hidden: If True, hide from auto-discovery/UI.
   :param name: Custom display name (defaults to class/function name).
   :param tags: List of tags for grouping in web UI.