ophyd-async 0.14.2__py3-none-any.whl → 0.15__py3-none-any.whl

ophyd_async/core/_utils.py

@@ -5,6 +5,8 @@ import logging
 from collections.abc import Awaitable, Callable, Iterable, Mapping, Sequence
 from dataclasses import dataclass
 from enum import Enum, EnumMeta, StrEnum
+from functools import lru_cache
+from inspect import isawaitable
 from typing import (
     Any,
     Generic,
@@ -13,6 +15,7 @@ from typing import (
     TypeVar,
     get_args,
     get_origin,
+    get_type_hints,
 )
 
 import numpy as np
@@ -204,6 +207,20 @@ async def wait_for_connection(**coros: Awaitable[None]):
         raise NotConnectedError.with_other_exceptions_logged(exceptions)
 
 
+# Cache get_type_hints calls to avoid expensive introspection across the codebase
+@lru_cache(maxsize=512)
+def cached_get_type_hints(cls: type, include_extras: bool = False) -> dict[str, Any]:
+    """Get type hints with caching to avoid expensive introspection."""
+    return get_type_hints(cls, include_extras=include_extras)
+
+
+# Cache get_origin calls to avoid expensive type introspection
+@lru_cache(maxsize=512)
+def cached_get_origin(tp: Any) -> Any:
+    """Get the origin of a type with caching."""
+    return get_origin(tp)
+
+
 def get_dtype(datatype: type) -> np.dtype:
     """Get the runtime dtype from a numpy ndarray type annotation.
 
@@ -215,7 +232,7 @@ def get_dtype(datatype: type) -> np.dtype:
 
     ```
     """
-    if not get_origin(datatype) == np.ndarray:
+    if not cached_get_origin(datatype) == np.ndarray:
         raise TypeError(f"Expected Array1D[dtype], got {datatype}")
     # datatype = numpy.ndarray[typing.Any, numpy.dtype[numpy.float64]]
     # so extract numpy.float64 from it
@@ -240,7 +257,7 @@ def get_enum_cls(datatype: type | None) -> type[EnumTypes] | None:
 
     ```
     """
-    if get_origin(datatype) is Sequence:
+    if cached_get_origin(datatype) is Sequence:
         datatype = get_args(datatype)[0]
     datatype = get_origin_class(datatype)
     if datatype and issubclass(datatype, Enum):
@@ -292,10 +309,36 @@ async def merge_gathered_dicts(
     return ret
 
 
-async def gather_dict(coros: Mapping[T, Awaitable[V]]) -> dict[T, V]:
-    """Take named coros and return a dict of their name to their return value."""
-    values = await asyncio.gather(*coros.values())
-    return dict(zip(coros, values, strict=True))
+def _partition_awaitable(
+    maybe_awaitables: Iterable[T | Awaitable[T]],
+) -> tuple[dict[int, Awaitable[T]], dict[int, T]]:
+    awaitable: dict[int, Awaitable[T]] = {}
+    not_awaitable: dict[int, T] = {}
+    for i, x in enumerate(maybe_awaitables):
+        if isawaitable(x):
+            awaitable[i] = x
+        else:
+            not_awaitable[i] = x
+    return awaitable, not_awaitable
+
+
+async def gather_dict(coros: dict[T | Awaitable[T], V | Awaitable[V]]) -> dict[T, V]:
+    """Await any coros in the keys or values of a dictionary."""
+    k_awaitable, k_not_awaitable = _partition_awaitable(coros.keys())
+    v_awaitable, v_not_awaitable = _partition_awaitable(coros.values())
+
+    # Await all awaitables in parallel
+    k_results, v_results = await asyncio.gather(
+        asyncio.gather(*k_awaitable.values()),
+        asyncio.gather(*v_awaitable.values()),
+    )
+
+    # Combine awaited and non-awaited values by index
+    k_map = k_not_awaitable | dict(zip(k_awaitable, k_results, strict=True))
+    v_map = v_not_awaitable | dict(zip(v_awaitable, v_results, strict=True))
+
+    # Reconstruct dict in original index order
+    return {k_map[i]: v_map[i] for i in range(len(coros))}
 
 
 def in_micros(t: float) -> int:
@@ -310,8 +353,10 @@ def in_micros(t: float) -> int:
     return int(np.ceil(t * 1e6))
 
 
+@lru_cache(maxsize=512)
 def get_origin_class(annotatation: Any) -> type | None:
-    origin = get_origin(annotatation) or annotatation
+    """Get the origin class of a type annotation with caching."""
+    origin = cached_get_origin(annotatation) or annotatation
     if isinstance(origin, type):
         return origin
     return None
@@ -363,3 +408,8 @@ def error_if_none(value: T | None, msg: str) -> T:
     if value is None:
         raise RuntimeError(msg)
     return value
+
+
+def non_zero(value):
+    """Return True if the value cast to an int is not zero."""
+    return int(value) != 0

ophyd_async/epics/adcore/_core_io.py

@@ -8,8 +8,9 @@ from ophyd_async.core import (
     SignalR,
     SignalRW,
     StrictEnum,
+    non_zero,
 )
-from ophyd_async.epics.core import EpicsDevice, PvSuffix
+from ophyd_async.epics.core import EpicsDevice, EpicsOptions, PvSuffix
 
 from ._utils import ADBaseDataType, ADFileWriteMode, ADImageMode, convert_ad_dtype_to_np
 
@@ -23,7 +24,7 @@ class NDArrayBaseIO(EpicsDevice):
 
     unique_id: A[SignalR[int], PvSuffix("UniqueId_RBV")]
     nd_attributes_file: A[SignalRW[str], PvSuffix("NDAttributesFile")]
-    acquire: A[SignalRW[bool], PvSuffix.rbv("Acquire")]
+    acquire: A[SignalRW[bool], PvSuffix.rbv("Acquire"), EpicsOptions(wait=non_zero)]
     array_size_x: A[SignalR[int], PvSuffix("ArraySizeX_RBV")]
     array_size_y: A[SignalR[int], PvSuffix("ArraySizeY_RBV")]
     data_type: A[SignalR[ADBaseDataType], PvSuffix("DataType_RBV")]
@@ -200,7 +201,7 @@ class NDFileIO(NDArrayBaseIO):
     file_write_mode: A[SignalRW[ADFileWriteMode], PvSuffix.rbv("FileWriteMode")]
     num_capture: A[SignalRW[int], PvSuffix.rbv("NumCapture")]
     num_captured: A[SignalR[int], PvSuffix("NumCaptured_RBV")]
-    capture: A[SignalRW[bool], PvSuffix.rbv("Capture")]
+    capture: A[SignalRW[bool], PvSuffix.rbv("Capture"), EpicsOptions(wait=non_zero)]
     array_size0: A[SignalR[int], PvSuffix("ArraySize0")]
     array_size1: A[SignalR[int], PvSuffix("ArraySize1")]
     create_directory: A[SignalRW[int], PvSuffix("CreateDirectory")]
@@ -240,11 +241,17 @@ class NDCBFlushOnSoftTrgMode(StrictEnum):
 
 
 class NDPluginCBIO(NDPluginBaseIO):
+    """Plugin that outputs pre/post-trigger NDArrays based on defined conditions.
+
+    This mirrors the interface provided by ADCore//Db/NDCircularBuff.template
+    See HTML docs at https://areadetector.github.io/areaDetector/ADCore/NDPluginCircularBuff.html
+    """
+
     pre_count: A[SignalRW[int], PvSuffix.rbv("PreCount")]
     post_count: A[SignalRW[int], PvSuffix.rbv("PostCount")]
     preset_trigger_count: A[SignalRW[int], PvSuffix.rbv("PresetTriggerCount")]
-    trigger: A[SignalRW[bool], PvSuffix.rbv("Trigger")]
-    capture: A[SignalRW[bool], PvSuffix.rbv("Capture")]
+    trigger: A[SignalRW[bool], PvSuffix.rbv("Trigger"), EpicsOptions(wait=non_zero)]
+    capture: A[SignalRW[bool], PvSuffix.rbv("Capture"), EpicsOptions(wait=non_zero)]
     flush_on_soft_trg: A[
         SignalRW[NDCBFlushOnSoftTrgMode], PvSuffix.rbv("FlushOnSoftTrg")
     ]

ophyd_async/epics/adcore/_core_logic.py

@@ -218,7 +218,7 @@ class ADBaseContAcqController(ADBaseController[ADBaseIO]):
         )
 
         # Send the trigger to begin acquisition
-        await self.cb_plugin.trigger.set(True, wait=False)
+        await self.cb_plugin.trigger.set(True)
 
     async def disarm(self) -> None:
         await stop_busy_record(self.cb_plugin.capture, False)

ophyd_async/epics/core/__init__.py

@@ -10,7 +10,7 @@ from ._signal import (
     epics_signal_w,
     epics_signal_x,
 )
-from ._util import stop_busy_record
+from ._util import EpicsOptions, stop_busy_record
 
 __all__ = [
     "PviDeviceConnector",
@@ -25,4 +25,5 @@ __all__ = [
     "epics_signal_w",
     "epics_signal_x",
     "stop_busy_record",
+    "EpicsOptions",
 ]

ophyd_async/epics/core/_aioca.py

@@ -36,7 +36,12 @@ from ophyd_async.core import (
     wait_for_connection,
 )
 
-from ._util import EpicsSignalBackend, format_datatype, get_supported_values
+from ._util import (
+    EpicsOptions,
+    EpicsSignalBackend,
+    format_datatype,
+    get_supported_values,
+)
 
 logger = logging.getLogger("ophyd_async")
 
@@ -255,12 +260,13 @@ class CaSignalBackend(EpicsSignalBackend[SignalDatatypeT]):
         datatype: type[SignalDatatypeT] | None,
         read_pv: str = "",
         write_pv: str = "",
+        options: EpicsOptions | None = None,
     ):
         self.converter: CaConverter = DisconnectedCaConverter(float, dbr.DBR_DOUBLE)
         self.initial_values: dict[str, AugmentedValue] = {}
         self.subscription: Subscription | None = None
         self._all_updates = _all_updates()
-        super().__init__(datatype, read_pv, write_pv)
+        super().__init__(datatype, read_pv, write_pv, options)
 
     def source(self, name: str, read: bool):
         return f"ca://{self.read_pv if read else self.write_pv}"
@@ -299,11 +305,15 @@ class CaSignalBackend(EpicsSignalBackend[SignalDatatypeT]):
             "alarm_severity": -1 if value.severity > 2 else value.severity,
         }
 
-    async def put(self, value: SignalDatatypeT | None, wait: bool):
+    async def put(self, value: SignalDatatypeT | None):
         if value is None:
             write_value = self.initial_values[self.write_pv]
         else:
             write_value = self.converter.write_value(value)
+        if callable(self.options.wait):
+            wait = self.options.wait(value)
+        else:
+            wait = self.options.wait
         try:
             await caput(
                 self.write_pv,

ophyd_async/epics/core/_epics_connector.py

@@ -5,7 +5,8 @@ from typing import Any
 
 from ophyd_async.core import Device, DeviceConnector, DeviceFiller
 
-from ._signal import EpicsSignalBackend, get_signal_backend_type, split_protocol_from_pv
+from ._signal import get_signal_backend_type, split_protocol_from_pv
+from ._util import EpicsOptions, EpicsSignalBackend
 
 
 @dataclass
@@ -44,6 +45,8 @@ def fill_backend_with_prefix(
             backend.write_pv = prefix + (
                 annotation.write_suffix or annotation.read_suffix
             )
+        elif isinstance(annotation, EpicsOptions):
+            backend.options = annotation
         else:
             unhandled.append(annotation)
     annotations.extend(unhandled)

ophyd_async/epics/core/_p4p.py

@@ -29,7 +29,12 @@ from ophyd_async.core import (
     wait_for_connection,
 )
 
-from ._util import EpicsSignalBackend, format_datatype, get_supported_values
+from ._util import (
+    EpicsOptions,
+    EpicsSignalBackend,
+    format_datatype,
+    get_supported_values,
+)
 
 logger = logging.getLogger("ophyd_async")
 
@@ -347,11 +352,12 @@ class PvaSignalBackend(EpicsSignalBackend[SignalDatatypeT]):
         datatype: type[SignalDatatypeT] | None,
         read_pv: str = "",
         write_pv: str = "",
+        options: EpicsOptions | None = None,
     ):
         self.converter: PvaConverter = DisconnectedPvaConverter(float)
         self.initial_values: dict[str, Any] = {}
         self.subscription: Subscription | None = None
-        super().__init__(datatype, read_pv, write_pv)
+        super().__init__(datatype, read_pv, write_pv, options)
 
     def source(self, name: str, read: bool):
         return f"pva://{self.read_pv if read else self.write_pv}"
@@ -380,11 +386,15 @@ class PvaSignalBackend(EpicsSignalBackend[SignalDatatypeT]):
             "alarm_severity": -1 if sv > 2 else sv,
         }
 
-    async def put(self, value: SignalDatatypeT | None, wait: bool):
+    async def put(self, value: SignalDatatypeT | None):
         if value is None:
             write_value = self.initial_values[self.write_pv]["value"]
         else:
             write_value = self.converter.write_value(value)
+        if callable(self.options.wait):
+            wait = self.options.wait(value)
+        else:
+            wait = self.options.wait
         await context().put(self.write_pv, {"value": write_value}, wait=wait)
 
     async def get_datakey(self, source: str) -> DataKey:

ophyd_async/epics/core/_signal.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from enum import Enum
 
 from ophyd_async.core import (
@@ -15,7 +16,7 @@ from ophyd_async.core import (
     get_unique,
 )
 
-from ._util import EpicsSignalBackend, get_pv_basename_and_field
+from ._util import EpicsOptions, EpicsSignalBackend, get_pv_basename_and_field
 
 
 class EpicsProtocol(Enum):
@@ -78,14 +79,18 @@ def get_signal_backend_type(protocol: EpicsProtocol) -> type[EpicsSignalBackend]
 
 
 def _epics_signal_backend(
-    datatype: type[SignalDatatypeT] | None, read_pv: str, write_pv: str
+    datatype: type[SignalDatatypeT] | None,
+    read_pv: str,
+    write_pv: str,
+    options: EpicsOptions | None = None,
 ) -> SignalBackend[SignalDatatypeT]:
     """Create an epics signal backend."""
     r_protocol, r_pv = split_protocol_from_pv(read_pv)
     w_protocol, w_pv = split_protocol_from_pv(write_pv)
     protocol = get_unique({read_pv: r_protocol, write_pv: w_protocol}, "protocols")
+
     signal_backend_type = get_signal_backend_type(protocol)
-    return signal_backend_type(datatype, r_pv, w_pv)
+    return signal_backend_type(datatype, r_pv, w_pv, options)
 
 
 def epics_signal_rw(
@@ -95,6 +100,7 @@ def epics_signal_rw(
     name: str = "",
     timeout: float = DEFAULT_TIMEOUT,
     attempts: int = 1,
+    wait: bool | Callable[[SignalDatatypeT], bool] = True,
 ) -> SignalRW[SignalDatatypeT]:
     """Create a `SignalRW` backed by 1 or 2 EPICS PVs.
 
@@ -104,7 +110,9 @@ def epics_signal_rw(
     :param name: The name of the signal (defaults to empty string)
     :param timeout: A timeout to be used when reading (not connecting) this signal
     """
-    backend = _epics_signal_backend(datatype, read_pv, write_pv or read_pv)
+    backend = _epics_signal_backend(
+        datatype, read_pv, write_pv or read_pv, EpicsOptions(wait=wait)
+    )
     return SignalRW(backend, name=name, timeout=timeout, attempts=attempts)
 
 
@@ -115,6 +123,7 @@ def epics_signal_rw_rbv(
     name: str = "",
     timeout: float = DEFAULT_TIMEOUT,
     attempts: int = 1,
+    wait: bool | Callable[[SignalDatatypeT], bool] = True,
 ) -> SignalRW[SignalDatatypeT]:
     """Create a `SignalRW` backed by 1 or 2 EPICS PVs, with a suffix on the readback pv.
 
@@ -131,7 +140,7 @@ def epics_signal_rw_rbv(
         read_pv = f"{write_pv}{read_suffix}"
 
     return epics_signal_rw(
-        datatype, read_pv, write_pv, name, timeout=timeout, attempts=attempts
+        datatype, read_pv, write_pv, name, timeout=timeout, attempts=attempts, wait=wait
     )
 
 
@@ -158,6 +167,7 @@ def epics_signal_w(
     name: str = "",
     timeout: float = DEFAULT_TIMEOUT,
     attempts: int = 1,
+    wait: bool | Callable[[SignalDatatypeT], bool] = True,
 ) -> SignalW[SignalDatatypeT]:
     """Create a `SignalW` backed by 1 EPICS PVs.
 
@@ -166,7 +176,9 @@ def epics_signal_w(
     :param name: The name of the signal (defaults to empty string)
     :param timeout: A timeout to be used when reading (not connecting) this signal
     """
-    backend = _epics_signal_backend(datatype, write_pv, write_pv)
+    backend = _epics_signal_backend(
+        datatype, write_pv, write_pv, EpicsOptions(wait=wait)
+    )
     return SignalW(backend, name=name, timeout=timeout, attempts=attempts)
 
 

ophyd_async/epics/core/_util.py

@@ -1,5 +1,6 @@
-from collections.abc import Mapping, Sequence
-from typing import Any, TypeVar, get_args, get_origin
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar, get_args, get_origin
 
 import numpy as np
 
@@ -19,6 +20,23 @@ from ophyd_async.core import (
 T = TypeVar("T")
 
 
+@dataclass
+class EpicsOptions(Generic[SignalDatatypeT]):
+    """Options for EPICS Signals."""
+
+    wait: bool | Callable[[SignalDatatypeT], bool] = True
+    """Whether to wait for server-side completion of the operation:
+
+    - `True`: Return when server-side operation has completed
+    - `False`: Return when server-side operation has started
+    - `callable`: Call with the value being put to decide whether to wait
+
+    For example, use `EpicsOption(wait=non_zero)` for busy records like
+    areaDetector acquire PVs that should not wait when being set to zero
+    as it causes a deadlock.
+    """
+
+
 def get_pv_basename_and_field(pv: str) -> tuple[str, str | None]:
     """Split PV into record name and field."""
     if "." in pv:
@@ -75,9 +93,11 @@ class EpicsSignalBackend(SignalBackend[SignalDatatypeT]):
         datatype: type[SignalDatatypeT] | None,
         read_pv: str = "",
         write_pv: str = "",
+        options: EpicsOptions | None = None,
     ):
         self.read_pv = read_pv
         self.write_pv = write_pv
+        self.options = options or EpicsOptions()
         super().__init__(datatype)
 
 
@@ -86,5 +106,5 @@ async def stop_busy_record(
     value: SignalDatatypeT,
     timeout: float = DEFAULT_TIMEOUT,
 ) -> None:
-    await signal.set(value, wait=False)
+    await signal.set(value)
     await wait_for_value(signal, value, timeout=timeout)

ophyd_async/epics/demo/_motor.py

@@ -55,8 +55,8 @@ class DemoMotor(EpicsDevice, StandardReadable, Movable, Stoppable):
         # If not supplied, calculate a suitable timeout for the move
         if timeout == CALCULATE_TIMEOUT:
             timeout = abs(new_position - old_position) / velocity + DEFAULT_TIMEOUT
-        # Wait for the value to set, but don't wait for put completion callback
-        await self.setpoint.set(new_position, wait=False)
+        # Setting the setpoint starts the motion
+        await self.setpoint.set(new_position)
         # Observe the readback Signal, and on each new position...
         async for current_position in observe_value(
             self.readback, done_timeout=timeout

ophyd_async/epics/motor.py

@@ -97,7 +97,7 @@ class InstantMotorMock(DeviceMock["Motor"]):
         set_mock_value(device.motor_done_move, 1)
 
         # When setpoint is written to, immediately update readback and done flag
-        def _instant_move(value, wait):
+        def _instant_move(value):
             set_mock_value(device.motor_done_move, 0)  # Moving
             set_mock_value(device.user_readback, value)  # Arrive instantly
             set_mock_value(device.motor_done_move, 1)  # Done
@@ -145,7 +145,9 @@ class Motor(
         # Note:cannot use epics_signal_x here, as the motor record specifies that
         # we must write 1 to stop the motor. Simply processing the record is not
         # sufficient.
-        self.motor_stop = epics_signal_w(int, prefix + ".STOP")
+        # Put with completion will never complete as we are waiting for completion on
+        # the move in set, so need to pass wait=False
+        self.motor_stop = epics_signal_w(int, prefix + ".STOP", wait=False)
 
         # Whether set() should complete successfully or not
         self._set_success = True
@@ -283,27 +285,23 @@ class Motor(
 
         await self.check_motor_limit(old_position, new_position)
 
-        move_status = self.user_setpoint.set(new_position, wait=True, timeout=timeout)
-        async for current_position in observe_value(
-            self.user_readback, done_status=move_status
-        ):
-            yield WatcherUpdate(
-                current=current_position,
-                initial=old_position,
-                target=new_position,
-                name=self.name,
-                unit=units,
-                precision=precision,
-            )
+        async with self.user_setpoint.set(new_position, timeout=timeout):
+            async for current_position in observe_value(self.user_readback):
+                yield WatcherUpdate(
+                    current=current_position,
+                    initial=old_position,
+                    target=new_position,
+                    name=self.name,
+                    unit=units,
+                    precision=precision,
+                )
         if not self._set_success:
             raise RuntimeError("Motor was stopped")
 
     async def stop(self, success=False):
         """Request to stop moving and return immediately."""
         self._set_success = success
-        # Put with completion will never complete as we are waiting for completion on
-        # the move above, so need to pass wait=False
-        await self.motor_stop.set(1, wait=False)
+        await self.motor_stop.set(1)
 
     async def locate(self) -> Location[float]:
         """Return the current setpoint and readback of the motor."""

ophyd_async/epics/odin/_odin_io.py

@@ -163,7 +163,7 @@ class OdinWriter(DetectorWriter):
 
     async def close(self) -> None:
         await stop_busy_record(self._drv.capture, Writing.DONE, timeout=DEFAULT_TIMEOUT)
-        await self._drv.meta_stop.set(True, wait=True)
+        await self._drv.meta_stop.set(True)
         if self._capture_status and not self._capture_status.done:
             await self._capture_status
         self._capture_status = None

ophyd_async/epics/pmac/_pmac_io.py

@@ -2,7 +2,7 @@ from collections.abc import Sequence
 
 import numpy as np
 
-from ophyd_async.core import Array1D, Device, DeviceVector, StandardReadable
+from ophyd_async.core import Array1D, Device, DeviceVector, StandardReadable, SubsetEnum
 from ophyd_async.epics import motor
 from ophyd_async.epics.core import epics_signal_r, epics_signal_rw, epics_signal_x
 
@@ -10,8 +10,16 @@ from ophyd_async.epics.core import epics_signal_r, epics_signal_rw, epics_signal
 CS_INDEX = {letter: index + 1 for index, letter in enumerate("ABCUVWXYZ")}
 
 
+class PmacExecuteState(SubsetEnum):
+    DONE = "Done"
+    EXECUTING = "Executing"
+
+
 class PmacTrajectoryIO(StandardReadable):
-    """Device that moves a PMAC Motor record."""
+    """Device that moves a PMAC Motor record.
+
+    This mirrors the interface provided by pmac/Db/pmacControllerTrajectory.template
+    """
 
     def __init__(self, prefix: str, name: str = "") -> None:
         self.time_array = epics_signal_rw(
@@ -45,6 +53,9 @@ class PmacTrajectoryIO(StandardReadable):
         # be a SignalRW to be waited on in PmacTrajectoryTriggerLogic.
         # TODO: Change record type to bo from busy (https://github.com/DiamondLightSource/pmac/issues/154)
         self.execute_profile = epics_signal_rw(bool, prefix + "ProfileExecute")
+        self.execute_state = epics_signal_r(
+            PmacExecuteState, prefix + "ProfileExecuteState_RBV"
+        )
         self.abort_profile = epics_signal_x(prefix + "ProfileAbort")
         self.profile_cs_name = epics_signal_rw(str, prefix + "ProfileCsName")
         self.calculate_velocities = epics_signal_rw(bool, prefix + "ProfileCalcVel")
@@ -56,6 +67,7 @@ class PmacAxisAssignmentIO(Device):
     """A Device that (direct) moves a PMAC Coordinate System Motor.
 
     Note that this does not go through a motor record.
+    This mirrors the interface provided by pmac/Db/motor_in_cs.template
     """
 
     def __init__(self, prefix: str, name: str = "") -> None:
@@ -66,7 +78,11 @@ class PmacAxisAssignmentIO(Device):
 
 
 class PmacCoordIO(Device):
-    """A Device that represents a Pmac Coordinate System."""
+    """A Device that represents a Pmac Coordinate System.
+
+    This mirrors the interfaces provided by pmac/Db/pmacCsController.template,
+    and pmac/Db/pmacDirectMotor.template
+    """
 
     def __init__(self, prefix: str, name: str = "") -> None:
         self.defer_moves = epics_signal_rw(bool, f"{prefix}DeferMoves")
@@ -81,7 +97,10 @@ class PmacCoordIO(Device):
 
 
 class PmacIO(Device):
-    """Device that represents a pmac controller."""
+    """Device that represents a pmac controller.
+
+    This mirrors the interface provided by pmac/Db/pmacController.template
+    """
 
     def __init__(
         self,