Refactor wrapped scan plans so they more user friendly

src/dodal/plans/__init__.py

@@ -1,33 +0,0 @@
-from .spec_path import spec_scan
-from .wrapped import (
-    count,
-    list_grid_rscan,
-    list_grid_scan,
-    list_rscan,
-    list_scan,
-    num_grid_rscan,
-    num_grid_scan,
-    num_rscan,
-    num_scan,
-    step_grid_rscan,
-    step_grid_scan,
-    step_rscan,
-    step_scan,
-)
-
-__all__ = [
-    "count",
-    "list_grid_rscan",
-    "list_grid_scan",
-    "list_rscan",
-    "list_scan",
-    "num_grid_rscan",
-    "num_grid_scan",
-    "num_rscan",
-    "num_scan",
-    "spec_scan",
-    "step_grid_rscan",
-    "step_grid_scan",
-    "step_rscan",
-    "step_scan",
-]

src/dodal/plans/scans/__init__.py

@@ -0,0 +1,33 @@
+from .spec_path import spec_scan
+from .wrapped import (
+    count,
+    list_grid_rscan,
+    list_grid_scan,
+    list_rscan,
+    list_scan,
+    num_grid_rscan,
+    num_grid_scan,
+    num_rscan,
+    num_scan,
+    step_grid_rscan,
+    step_grid_scan,
+    step_rscan,
+    step_scan,
+)
+
+__all__ = [
+    "count",
+    "list_grid_rscan",
+    "list_grid_scan",
+    "list_rscan",
+    "list_scan",
+    "num_grid_rscan",
+    "num_grid_scan",
+    "num_rscan",
+    "num_scan",
+    "spec_scan",
+    "step_grid_rscan",
+    "step_grid_scan",
+    "step_rscan",
+    "step_scan",
+]

src/dodal/plans/scans/annotations.py

@@ -0,0 +1,92 @@
+from typing import Annotated as A
+
+from pydantic import BeforeValidator, Field
+
+from dodal.plans.scans.types import (
+    Detectors,
+    MovableListOfPoints,
+    MovableStartStep,
+    MovableStartStop,
+    MovableStartStopNum,
+    MovableStartStopStep,
+)
+from dodal.plans.scans.validators import trajectory_validator
+
+DetectorsA = A[
+    Detectors,
+    Field(
+        description="Set of readable devices, will take a reading at each point",
+    ),
+]
+
+MovableStartStepA = A[
+    MovableStartStep,
+    Field(
+        description="Trajectory defined by a movable, start position, and step size."
+    ),
+    BeforeValidator(
+        trajectory_validator(
+            length=3,
+            template="(movable, start, step)",
+            expected_type=MovableStartStep,
+        )
+    ),
+]
+
+MovableStartStopA = A[
+    MovableStartStop,
+    Field(
+        description="Trajectory defined by a movable, start position, and stop position.",
+    ),
+    BeforeValidator(
+        trajectory_validator(
+            length=3,
+            template="(movable, start, stop)",
+            expected_type=MovableStartStop,
+        )
+    ),
+]
+
+MovableStartStopNumA = A[
+    MovableStartStopNum,
+    Field(
+        description="Trajectory defined by a movable, start position, stop position, "
+        "and number of points."
+    ),
+    BeforeValidator(
+        trajectory_validator(
+            length=4,
+            template="(movable, start, stop, num)",
+            expected_type=MovableStartStopNum,
+        )
+    ),
+]
+
+MovableListOfPointsA = A[
+    MovableListOfPoints,
+    Field(
+        description="Trajectory defined by a movable and a list of positions to move to."
+    ),
+    BeforeValidator(
+        trajectory_validator(
+            length=2,
+            template="(movable, [point1, point2, ...])",
+            expected_type=MovableListOfPoints,
+        )
+    ),
+]
+
+MovableStartStopStepA = A[
+    MovableStartStopStep,
+    Field(
+        description="Trajectory defined by a movable, start position, stop position, "
+        "and step size."
+    ),
+    BeforeValidator(
+        trajectory_validator(
+            length=4,
+            template="(movable, start, stop, step)",
+            expected_type=MovableStartStopStep,
+        )
+    ),
+]

src/dodal/plans/spec_path.py → src/dodal/plans/scans/spec_path.py

@@ -1,32 +1,29 @@
 import operator
 from functools import reduce
-from typing import Annotated, Any
+from typing import Annotated
 
 import bluesky.plans as bp
-from bluesky.protocols import Movable, Readable
+from bluesky.protocols import Movable
+from bluesky.utils import CustomPlanMetadata, plan
 from cycler import Cycler, cycler
 from pydantic import Field, validate_call
 from scanspec.specs import Spec
 
 from dodal.common import MsgGenerator
 from dodal.plan_stubs.data_session import attach_data_session_metadata_decorator
+from dodal.plans.scans.annotations import DetectorsA
 
 
 @attach_data_session_metadata_decorator()
 @validate_call(config={"arbitrary_types_allowed": True})
+@plan
 def spec_scan(
-    detectors: Annotated[
-        set[Readable],
-        Field(
-            description="Set of readable devices, will take a reading at each point, \
-            in addition to any Movables in the Spec",
-        ),
-    ],
+    detectors: DetectorsA,
     spec: Annotated[
         Spec[Movable],
         Field(description="ScanSpec modelling the path of the scan"),
     ],
-    metadata: dict[str, Any] | None = None,
+    metadata: CustomPlanMetadata | None = None,
 ) -> MsgGenerator:
     """Generic plan for reading `detectors` at every point of a ScanSpec `Spec`.
     A `Spec` is an N-dimensional path.
@@ -44,7 +41,7 @@ def spec_scan(
         **(metadata or {}),
     }
 
-    yield from bp.scan_nd(tuple(detectors), _as_cycler(spec), md=_md)
+    yield from bp.scan_nd(detectors, _as_cycler(spec), md=_md)
 
 
 def _as_cycler(spec: Spec[Movable]) -> Cycler:

src/dodal/plans/scans/types.py

@@ -0,0 +1,19 @@
+from collections.abc import Sequence
+from typing import Any
+
+from bluesky.protocols import Movable, Readable
+from ophyd_async.core import AsyncReadable
+
+Number = float | int
+
+Detectors = Sequence[Readable | AsyncReadable]
+
+MovableStartStep = tuple[Movable[Number], Number, Number]
+
+MovableStartStop = tuple[Movable[Number], Number, Number]
+
+MovableStartStopNum = tuple[Movable[Number], Number, Number, int]
+
+MovableListOfPoints = tuple[Movable[Any], list[Any]]
+
+MovableStartStopStep = tuple[Movable[Number], Number, Number, Number]