ophyd-async 0.9.0a2__py3-none-any.whl → 0.10.0a2__py3-none-any.whl

ophyd_async/core/_detector.py

@@ -1,9 +1,10 @@
-"""Module which defines abstract classes to work with detectors"""
+"""Module which defines abstract classes to work with detectors."""
 
 import asyncio
 import time
 from abc import ABC, abstractmethod
 from collections.abc import AsyncGenerator, AsyncIterator, Callable, Iterator, Sequence
+from enum import Enum
 from functools import cached_property
 from typing import (
     Generic,
@@ -28,48 +29,62 @@ from ._device import Device, DeviceConnector
 from ._protocol import AsyncConfigurable, AsyncReadable
 from ._signal import SignalR
 from ._status import AsyncStatus, WatchableAsyncStatus
-from ._utils import DEFAULT_TIMEOUT, StrictEnum, WatcherUpdate, merge_gathered_dicts
+from ._utils import DEFAULT_TIMEOUT, WatcherUpdate, merge_gathered_dicts
 
 
-class DetectorTrigger(StrictEnum):
-    """Type of mechanism for triggering a detector to take frames"""
+class DetectorTrigger(Enum):
+    """Type of mechanism for triggering a detector to take frames."""
 
-    #: Detector generates internal trigger for given rate
-    INTERNAL = "internal"
-    #: Expect a series of arbitrary length trigger signals
-    EDGE_TRIGGER = "edge_trigger"
-    #: Expect a series of constant width external gate signals
-    CONSTANT_GATE = "constant_gate"
-    #: Expect a series of variable width external gate signals
-    VARIABLE_GATE = "variable_gate"
+    INTERNAL = "INTERNAL"
+    """Detector generates internal trigger for given rate"""
+
+    EDGE_TRIGGER = "EDGE_TRIGGER"
+    """Expect a series of arbitrary length trigger signals"""
+
+    CONSTANT_GATE = "CONSTANT_GATE"
+    """Expect a series of constant width external gate signals"""
+
+    VARIABLE_GATE = "VARIABLE_GATE"
+    """Expect a series of variable width external gate signals"""
 
 
 class TriggerInfo(BaseModel):
-    """Minimal set of information required to setup triggering on a detector"""
-
-    #: Number of triggers that will be sent, (0 means infinite) Can be:
-    #  - A single integer or
-    #  - A list of integers for multiple triggers
-    # Example for tomography: TriggerInfo(number=[2,3,100,3])
-    #:     This would trigger:
-    #:     - 2 times for dark field images
-    #:     - 3 times for initial flat field images
-    #:     - 100 times for projections
-    #:     - 3 times for final flat field images
-    number_of_triggers: NonNegativeInt | list[NonNegativeInt]
-    #: Sort of triggers that will be sent
+    """Minimal set of information required to setup triggering on a detector."""
+
+    number_of_triggers: NonNegativeInt | list[NonNegativeInt] = Field(default=1)
+    """Number of triggers that will be sent, (0 means infinite).
+
+    Can be:
+    - A single integer or
+    - A list of integers for multiple triggers
+
+    Example for tomography: ``TriggerInfo(number=[2,3,100,3])``.
+    This would trigger:
+
+    - 2 times for dark field images
+    - 3 times for initial flat field images
+    - 100 times for projections
+    - 3 times for final flat field images
+    """
+
     trigger: DetectorTrigger = Field(default=DetectorTrigger.INTERNAL)
-    #: What is the minimum deadtime between triggers
-    deadtime: float | None = Field(default=None, ge=0)
-    #: What is the maximum high time of the triggers
+    """Sort of triggers that will be sent"""
+
+    deadtime: float = Field(default=0.0, ge=0)
+    """What is the minimum deadtime between triggers"""
+
     livetime: float | None = Field(default=None, ge=0)
-    #: What is the maximum timeout on waiting for a frame
+    """What is the maximum high time of the triggers"""
+
     frame_timeout: float | None = Field(default=None, gt=0)
-    #: How many triggers make up a single StreamDatum index, to allow multiple frames
-    #: from a faster detector to be zipped with a single frame from a slow detector
-    #: e.g. if num=10 and multiplier=5 then the detector will take 10 frames,
-    #: but publish 2 indices, and describe() will show a shape of (5, h, w)
+    """What is the maximum timeout on waiting for a frame"""
+
     multiplier: int = 1
+    """How many triggers make up a single StreamDatum index, to allow multiple frames
+    from a faster detector to be zipped with a single frame from a slow detector
+    e.g. if num=10 and multiplier=5 then the detector will take 10 frames,
+    but publish 2 indices, and describe() will show a shape of (5, h, w)
+    """
 
     @computed_field
     @cached_property
@@ -82,89 +97,68 @@ class TriggerInfo(BaseModel):
 
 
 class DetectorController(ABC):
-    """
-    Classes implementing this interface should hold the logic for
-    arming and disarming a detector
-    """
+    """Detector logic for arming and disarming the detector."""
 
     @abstractmethod
     def get_deadtime(self, exposure: float | None) -> float:
-        """For a given exposure, how long should the time between exposures be"""
+        """For a given exposure, how long should the time between exposures be."""
 
     @abstractmethod
     async def prepare(self, trigger_info: TriggerInfo) -> None:
-        """
-        Do all necessary steps to prepare the detector for triggers.
-
-        Args:
-            trigger_info: This is a Pydantic model which contains
-                number Expected number of frames.
-                trigger Type of trigger for which to prepare the detector. Defaults
-                to DetectorTrigger.internal.
-                livetime Livetime / Exposure time with which to set up the detector.
-                Defaults to None
-                if not applicable or the detector is expected to use its previously-set
-                exposure time.
-                deadtime Defaults to None. This is the minimum deadtime between
-                triggers.
-                multiplier The number of triggers grouped into a single StreamDatum
-                index.
+        """Do all necessary steps to prepare the detector for triggers.
+
+        :param trigger_info: The sort of triggers to expect.
         """
 
     @abstractmethod
     async def arm(self) -> None:
-        """
-        Arm the detector
-        """
+        """Arm the detector."""
 
     @abstractmethod
     async def wait_for_idle(self):
-        """
-        This will wait on the internal _arm_status and wait for it to get disarmed/idle
-        """
+        """Wait on the internal _arm_status and wait for it to get disarmed/idle."""
 
     @abstractmethod
     async def disarm(self):
-        """Disarm the detector, return detector to an idle state"""
+        """Disarm the detector, return detector to an idle state."""
 
 
 class DetectorWriter(ABC):
-    """Logic for making a detector write data to somewhere persistent
-    (e.g. an HDF5 file)"""
+    """Logic for making detector write data to somewhere persistent (e.g. HDF5 file)."""
 
     @abstractmethod
     async def open(self, multiplier: int = 1) -> dict[str, DataKey]:
         """Open writer and wait for it to be ready for data.
 
-        Args:
-            multiplier: Each StreamDatum index corresponds to this many
-                written exposures
-
-        Returns:
-            Output for ``describe()``
+        :param multiplier:
+            Each StreamDatum index corresponds to this many written exposures
+        :return: Output for ``describe()``
         """
 
-    @abstractmethod
-    def observe_indices_written(
-        self, timeout=DEFAULT_TIMEOUT
-    ) -> AsyncGenerator[int, None]:
-        """Yield the index of each frame (or equivalent data point) as it is written"""
+    @property
+    def hints(self) -> Hints:
+        """The hints to be used for the detector."""
+        return {}
 
     @abstractmethod
     async def get_indices_written(self) -> int:
-        """Get the number of indices written"""
+        """Get the number of indices written."""
+
+    # Note: this method is really async, but if we make it async here then we
+    # need to give it a body with a redundant yield statement, which is a bit
+    # awkward. So we just leave it as a regular method and let the user
+    # implement it as async.
+    @abstractmethod
+    def observe_indices_written(self, timeout: float) -> AsyncGenerator[int, None]:
+        """Yield the index of each frame (or equivalent data point) as it is written."""
 
     @abstractmethod
     def collect_stream_docs(self, indices_written: int) -> AsyncIterator[StreamAsset]:
-        """Create Stream docs up to given number written"""
+        """Create Stream docs up to given number written."""
 
     @abstractmethod
     async def close(self) -> None:
-        """Close writer, blocks until I/O is complete"""
-
-    @property
-    def hints(self) -> Hints:
-        return {}
+        """Close writer, blocks until I/O is complete."""
 
 
 # Add type var for controller so we can define
@@ -192,9 +186,14 @@ class StandardDetector(
     WritesStreamAssets,
     Generic[DetectorControllerT, DetectorWriterT],
 ):
-    """
-    Useful detector base class for step and fly scanning detectors.
+    """Detector base class for step and fly scanning detectors.
+
     Aggregates controller and writer logic together.
+
+    :param controller: Logic for arming and disarming the detector
+    :param writer: Logic for making the detector write persistent data
+    :param config_sigs: Signals to read when describe and read configuration are called
+    :param name: Device name
     """
 
     def __init__(
@@ -205,16 +204,6 @@ class StandardDetector(
         name: str = "",
         connector: DeviceConnector | None = None,
     ) -> None:
-        """
-        Constructor
-
-        Args:
-            controller: Logic for arming and disarming the detector
-            writer: Logic for making the detector write persistent data
-            config_sigs: Signals to read when describe and read
-            configuration are called. Defaults to ().
-            name: Device name. Defaults to "".
-        """
         self._controller = controller
         self._writer = writer
         self._describe: dict[str, DataKey] = {}
@@ -236,13 +225,13 @@ class StandardDetector(
 
     @AsyncStatus.wrap
     async def stage(self) -> None:
-        # Disarm the detector, stop file writing.
+        """Make sure the detector is idle and ready to be used."""
         await self._check_config_sigs()
         await asyncio.gather(self._writer.close(), self._controller.disarm())
         self._trigger_info = None
 
     async def _check_config_sigs(self):
-        """Checks configuration signals are named and connected."""
+        """Check configuration signals are named and connected."""
         for signal in self._config_sigs:
             if signal.name == "":
                 raise Exception(
@@ -258,7 +247,7 @@ class StandardDetector(
 
     @AsyncStatus.wrap
     async def unstage(self) -> None:
-        # Stop data writing.
+        """Disarm the detector and stop file writing."""
         await asyncio.gather(self._writer.close(), self._controller.disarm())
 
     async def read_configuration(self) -> dict[str, Reading]:
@@ -268,6 +257,7 @@ class StandardDetector(
         return await merge_gathered_dicts(sig.describe() for sig in self._config_sigs)
 
     async def read(self) -> dict[str, Reading]:
+        """There is no data to be placed in events, so this is empty."""
         # All data is in StreamResources, not Events, so nothing to output here
         return {}
 
@@ -281,14 +271,11 @@ class StandardDetector(
                 TriggerInfo(
                     number_of_triggers=1,
                     trigger=DetectorTrigger.INTERNAL,
-                    deadtime=None,
-                    livetime=None,
-                    frame_timeout=None,
                 )
             )
 
-        self._trigger_info = _ensure_trigger_info_exists(self._trigger_info)
-        if self._trigger_info.trigger is not DetectorTrigger.INTERNAL:
+        trigger_info = _ensure_trigger_info_exists(self._trigger_info)
+        if trigger_info.trigger is not DetectorTrigger.INTERNAL:
             msg = "The trigger method can only be called with INTERNAL triggering"
             raise ValueError(msg)
 
@@ -299,28 +286,19 @@ class StandardDetector(
         end_observation = indices_written + 1
 
         async for index in self._writer.observe_indices_written(
-            DEFAULT_TIMEOUT
-            + (self._trigger_info.livetime or 0)
-            + (self._trigger_info.deadtime or 0)
+            DEFAULT_TIMEOUT + (trigger_info.livetime or 0) + trigger_info.deadtime
         ):
             if index >= end_observation:
                 break
 
     @AsyncStatus.wrap
     async def prepare(self, value: TriggerInfo) -> None:
-        """
-        Arm detector.
+        """Arm detector.
 
         Prepare the detector with trigger information. This is determined at and passed
         in from the plan level.
 
-        This currently only prepares detectors for flyscans and stepscans just use the
-        trigger information determined in trigger.
-
-        To do: Unify prepare to be use for both fly and step scans.
-
-        Args:
-            value: TriggerInfo describing how to trigger the detector
+        :param value: TriggerInfo describing how to trigger the detector
         """
         if value.trigger != DetectorTrigger.INTERNAL and not value.deadtime:
             msg = "Deadtime must be supplied when in externally triggered mode"
@@ -332,25 +310,28 @@ class StandardDetector(
                 f"deadtime, but trigger logic provides only {value.deadtime}s"
             )
             raise ValueError(msg)
-
-        self._trigger_info = value
+        elif not value.deadtime:
+            value.deadtime = self._controller.get_deadtime(value.livetime)
         self._number_of_triggers_iter = iter(
-            self._trigger_info.number_of_triggers
-            if isinstance(self._trigger_info.number_of_triggers, list)
-            else [self._trigger_info.number_of_triggers]
+            value.number_of_triggers
+            if isinstance(value.number_of_triggers, list)
+            else [value.number_of_triggers]
         )
-        self._initial_frame = await self._writer.get_indices_written()
         self._describe, _ = await asyncio.gather(
             self._writer.open(value.multiplier), self._controller.prepare(value)
         )
+        self._initial_frame = await self._writer.get_indices_written()
         if value.trigger != DetectorTrigger.INTERNAL:
             await self._controller.arm()
-            self._fly_start = time.monotonic()
+        self._trigger_info = value
 
     @AsyncStatus.wrap
     async def kickoff(self):
         if self._trigger_info is None or self._number_of_triggers_iter is None:
             raise RuntimeError("Prepare must be called before kickoff!")
+        if self._trigger_info.trigger == DetectorTrigger.INTERNAL:
+            await self._controller.arm()
+        self._fly_start = time.monotonic()
         try:
             self._frames_to_complete = next(self._number_of_triggers_iter)
             self._completable_frames += self._frames_to_complete
@@ -362,13 +343,13 @@ class StandardDetector(
 
     @WatchableAsyncStatus.wrap
     async def complete(self):
-        self._trigger_info = _ensure_trigger_info_exists(self._trigger_info)
+        trigger_info = _ensure_trigger_info_exists(self._trigger_info)
         indices_written = self._writer.observe_indices_written(
-            self._trigger_info.frame_timeout
+            trigger_info.frame_timeout
             or (
                 DEFAULT_TIMEOUT
-                + (self._trigger_info.livetime or 0)
-                + (self._trigger_info.deadtime or 0)
+                + (trigger_info.livetime or 0)
+                + (trigger_info.deadtime or 0)
             )
         )
         try:
@@ -388,7 +369,7 @@ class StandardDetector(
                     break
         finally:
             await indices_written.aclose()
-            if self._completable_frames >= self._trigger_info.total_number_of_triggers:
+            if self._completable_frames >= trigger_info.total_number_of_triggers:
                 self._completable_frames = 0
                 self._frames_to_complete = 0
                 self._number_of_triggers_iter = None

ophyd_async/core/_device.py

@@ -17,7 +17,7 @@ class DeviceConnector:
     """Defines how a `Device` should be connected and type hints processed."""
 
     def create_children_from_annotations(self, device: Device):
-        """Used when children can be created from introspecting the hardware.
+        """Use when children can be created from introspecting the hardware.
 
         Some control systems allow introspection of a device to determine what
         children it has. To allow this to work nicely with typing we add these
@@ -26,15 +26,20 @@ class DeviceConnector:
             my_signal: SignalRW[int]
             my_device: MyDevice
 
-        This method will be run during ``Device.__init__``, and is responsible
+        This method will be run during `Device.__init__`, and is responsible
         for turning all of those type hints into real Signal and Device instances.
 
         Subsequent runs of this function should do nothing, to allow it to be
         called early in Devices that need to pass references to their children
-        during ``__init__``.
+        during `__init__`.
         """
 
     async def connect_mock(self, device: Device, mock: LazyMock):
+        """Use during [](#Device.connect) with `mock=True`.
+
+        This is called when there is no cached connect done in `mock=True`
+        mode. It connects the Device and all its children in mock mode.
+        """
         # Connect serially, no errors to gather up as in mock mode
         exceptions: dict[str, Exception] = {}
         for name, child_device in device.children():
@@ -46,11 +51,10 @@ class DeviceConnector:
             raise NotConnected.with_other_exceptions_logged(exceptions)
 
     async def connect_real(self, device: Device, timeout: float, force_reconnect: bool):
-        """Used during ``Device.connect``.
+        """Use during [](#Device.connect) with `mock=False`.
 
-        This is called when a previous connect has not been done, or has been
-        done in a different mock more. It should connect the Device and all its
-        children.
+        This is called when there is no cached connect done in `mock=False`
+        mode. It connects the Device and all its children in real mode in parallel.
         """
         # Connect in parallel, gathering up NotConnected errors
         coros = {
@@ -61,11 +65,15 @@ class DeviceConnector:
 
 
 class Device(HasName):
-    """Common base class for all Ophyd Async Devices."""
+    """Common base class for all Ophyd Async Devices.
+
+    :param name: Optional name of the Device
+    :param connector: Optional DeviceConnector instance to use at connect()
+    """
 
-    _name: str = ""
-    #: The parent Device if it exists
     parent: Device | None = None
+    """The parent Device if it exists"""
+    _name: str = ""
     # None if connect hasn't started, a Task if it has
     _connect_task: asyncio.Task | None = None
     # The mock if we have connected in mock mode
@@ -83,7 +91,7 @@ class Device(HasName):
 
     @property
     def name(self) -> str:
-        """Return the name of the Device"""
+        """Return the name of the Device."""
         return self._name
 
     @cached_property
@@ -91,24 +99,26 @@ class Device(HasName):
         return {}
 
     def children(self) -> Iterator[tuple[str, Device]]:
+        """For each attribute that is a Device, yield the name and Device.
+
+        :yields: `(attr_name, attr)` for each child attribute that is a Device.
+        """
         yield from self._child_devices.items()
 
     @cached_property
     def log(self) -> LoggerAdapter:
+        """Return a logger configured with the device name."""
         return LoggerAdapter(
             getLogger("ophyd_async.devices"), {"ophyd_async_device_name": self.name}
         )
 
     def set_name(self, name: str, *, child_name_separator: str | None = None) -> None:
-        """Set ``self.name=name`` and each ``self.child.name=name+"-child"``.
-
-        Parameters
-        ----------
-        name:
-            New name to set
-        child_name_separator:
-            Use this as a separator instead of "-". Use "_" instead to make the same
-            names as the equivalent ophyd sync device.
+        """Set `self.name=name` and each `self.child.name=name+"-child"`.
+
+        :param name: New name to set.
+        :param child_name_separator:
+            Use this as a separator instead of "-". Use "_" instead to make the
+            same names as the equivalent ophyd sync device.
         """
         self._name = name
         if child_name_separator:
@@ -147,16 +157,19 @@ class Device(HasName):
         timeout: float = DEFAULT_TIMEOUT,
         force_reconnect: bool = False,
     ) -> None:
-        """Connect self and all child Devices.
-
-        Contains a timeout that gets propagated to child.connect methods.
-
-        Parameters
-        ----------
-        mock:
-            If True then use ``MockSignalBackend`` for all Signals
-        timeout:
-            Time to wait before failing with a TimeoutError.
+        """Connect the device and all child devices.
+
+        Successful connects will be cached so subsequent calls will return
+        immediately. Contains a timeout that gets propagated to child.connect
+        methods.
+
+        :param mock:
+            If True then use [](#MockSignalBackend) for all Signals. If passed a
+            [](#LazyMock) then pass this down for use within the Signals,
+            otherwise create one.
+        :param timeout: Time to wait before failing with a TimeoutError.
+        :param force_reconnect:
+            If True, force a reconnect even if the last connect succeeded.
         """
         if not hasattr(self, "_connector"):
             msg = (
@@ -205,12 +218,9 @@ DeviceT = TypeVar("DeviceT", bound=Device)
 
 
 class DeviceVector(MutableMapping[int, DeviceT], Device):
-    """
-    Defines device components with indices.
+    """Defines a dictionary of Device children with arbitrary integer keys.
 
-    In the below example, foos becomes a dictionary on the parent device
-    at runtime, so parent.foos[2] returns a FooDevice. For example usage see
-    :class:`~ophyd_async.epics.sim.DynamicSensorGroup`
+    :see-also: [](#implementing-devices) for examples of how to use this class.
     """
 
     def __init__(
@@ -274,7 +284,7 @@ class DeviceProcessor:
         self._locals_on_exit: dict[str, Any] = {}
 
     def _caller_locals(self) -> dict[str, Any]:
-        """Walk up until we find a stack frame that doesn't have us as self"""
+        """Walk up until we find a stack frame that doesn't have us as self."""
         try:
             raise ValueError
         except ValueError:
@@ -341,33 +351,29 @@ def init_devices(
     connect=True,
     mock=False,
     timeout: float = 10.0,
-) -> DeviceProcessor:
-    """Auto initialise top level Device instances to be used as a context manager
-
-    Parameters
-    ----------
-    set_name:
-        If True, call ``device.set_name(variable_name)`` on all Devices
-        created within the context manager that have an empty ``name``
-    child_name_separator:
-        Use this as a separator if we call ``set_name``.
-    connect:
-        If True, call ``device.connect(mock, timeout)`` in parallel on all
-        Devices created within the context manager
-    mock:
-        If True, connect Signals in mock mode
-    timeout:
-        How long to wait for connect before logging an exception
-
-    Notes
-    -----
-    Example usage::
-
-        [async] with init_devices():
-            t1x = motor.Motor("BLxxI-MO-TABLE-01:X")
-            t1y = motor.Motor("pva://BLxxI-MO-TABLE-01:Y")
-            # Names and connects devices here
-        assert t1x.name == "t1x"
+):
+    """Auto initialize top level Device instances: to be used as a context manager.
+
+    :param set_name:
+        If True, call `device.set_name(variable_name)` on all Devices created
+        within the context manager that have an empty `name`.
+    :param child_name_separator: Separator for child names if `set_name` is True.
+    :param connect:
+        If True, call `device.connect(mock, timeout)` in parallel on all Devices
+        created within the context manager.
+    :param mock: If True, connect Signals in mock mode.
+    :param timeout: How long to wait for connect before logging an exception.
+    :raises RuntimeError: If used inside a plan, use [](#ensure_connected) instead.
+    :raises NotConnected: If devices could not be connected.
+
+    For example, to connect and name 2 motors in parallel:
+    ```python
+    [async] with init_devices():
+        t1x = motor.Motor("BLxxI-MO-TABLE-01:X")
+        t1y = motor.Motor("pva://BLxxI-MO-TABLE-01:Y")
+        # Names and connects devices here
+    assert t1x.name == "t1x"
+    ```
     """
 
     async def process_devices(devices: dict[str, Device]):