ophyd-async 0.2.0__py3-none-any.whl → 0.3a2__py3-none-any.whl

ophyd_async/__init__.py

@@ -1,6 +1,3 @@
-from importlib.metadata import version  # noqa
-
-__version__ = version("ophyd-async")
-del version
+from ._version import __version__
 
 __all__ = ["__version__"]

ophyd_async/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.2.0'
-__version_tuple__ = version_tuple = (0, 2, 0)
+__version__ = version = '0.3a2'
+__version_tuple__ = version_tuple = (0, 3)

ophyd_async/core/__init__.py

@@ -6,22 +6,24 @@ from ._providers import (
     StaticDirectoryProvider,
 )
 from .async_status import AsyncStatus
-from .detector import DetectorControl, DetectorTrigger, DetectorWriter, StandardDetector
+from .detector import (
+    DetectorControl,
+    DetectorTrigger,
+    DetectorWriter,
+    StandardDetector,
+    TriggerInfo,
+)
 from .device import Device, DeviceCollector, DeviceVector
 from .device_save_loader import (
     get_signal_values,
+    load_device,
     load_from_yaml,
+    save_device,
     save_to_yaml,
     set_signal_values,
     walk_rw_signals,
 )
-from .flyer import (
-    DetectorGroupLogic,
-    HardwareTriggeredFlyable,
-    SameTriggerDetectorGroupLogic,
-    TriggerInfo,
-    TriggerLogic,
-)
+from .flyer import HardwareTriggeredFlyable, TriggerLogic
 from .signal import (
     Signal,
     SignalR,
@@ -33,6 +35,8 @@ from .signal import (
     set_sim_callback,
     set_sim_put_proceeds,
     set_sim_value,
+    soft_signal_r_and_backend,
+    soft_signal_rw,
     wait_for_value,
 )
 from .signal_backend import SignalBackend
@@ -65,6 +69,8 @@ __all__ = [
     "SignalW",
     "SignalRW",
     "SignalX",
+    "soft_signal_r_and_backend",
+    "soft_signal_rw",
     "observe_value",
     "set_and_wait_for_value",
     "set_sim_callback",
@@ -79,8 +85,6 @@ __all__ = [
     "StaticDirectoryProvider",
     "StandardReadable",
     "TriggerInfo",
-    "DetectorGroupLogic",
-    "SameTriggerDetectorGroupLogic",
     "TriggerLogic",
     "HardwareTriggeredFlyable",
     "DEFAULT_TIMEOUT",
@@ -97,4 +101,6 @@ __all__ = [
     "save_to_yaml",
     "set_signal_values",
     "walk_rw_signals",
+    "load_device",
+    "save_device",
 ]

ophyd_async/core/_providers.py

@@ -1,12 +1,30 @@
 from abc import abstractmethod
 from dataclasses import dataclass
-from typing import Protocol, Sequence
+from pathlib import Path
+from typing import Optional, Protocol, Sequence, Union
 
 
 @dataclass
 class DirectoryInfo:
-    directory_path: str
-    filename_prefix: str
+    """
+    Information about where and how to write a file.
+
+    The bluesky event model splits the URI for a resource into two segments to aid in
+    different applications mounting filesystems at different mount points.
+    The portion of this path which is relevant only for the writer is the 'root',
+    while the path from an agreed upon mutual mounting is the resource_path.
+    The resource_dir is used with the filename to construct the resource_path.
+
+    :param root: Path of a root directory, relevant only for the file writer
+    :param resource_dir: Directory into which files should be written, relative to root
+    :param prefix: Optional filename prefix to add to all files
+    :param suffix: Optional filename suffix to add to all files
+    """
+
+    root: Path
+    resource_dir: Path
+    prefix: Optional[str] = ""
+    suffix: Optional[str] = ""
 
 
 class DirectoryProvider(Protocol):
@@ -16,8 +34,23 @@ class DirectoryProvider(Protocol):
 
 
 class StaticDirectoryProvider(DirectoryProvider):
-    def __init__(self, directory_path: str, filename_prefix: str) -> None:
-        self._directory_info = DirectoryInfo(directory_path, filename_prefix)
+    def __init__(
+        self,
+        directory_path: Union[str, Path],
+        filename_prefix: str = "",
+        filename_suffix: str = "",
+        resource_dir: Optional[Path] = None,
+    ) -> None:
+        if resource_dir is None:
+            resource_dir = Path(".")
+        if isinstance(directory_path, str):
+            directory_path = Path(directory_path)
+        self._directory_info = DirectoryInfo(
+            root=directory_path,
+            resource_dir=resource_dir,
+            prefix=filename_prefix,
+            suffix=filename_suffix,
+        )
 
     def __call__(self) -> DirectoryInfo:
         return self._directory_info

ophyd_async/core/async_status.py

@@ -85,12 +85,12 @@ class AsyncStatus(Status):
 
     def __repr__(self) -> str:
         if self.done:
-            if self.exception() is not None:
-                status = "errored"
+            if e := self.exception():
+                status = f"errored: {repr(e)}"
             else:
                 status = "done"
         else:
             status = "pending"
-        return f"<{type(self).__name__} {status}>"
+        return f"<{type(self).__name__}, task: {self.task.get_coro()}, {status}>"
 
     __str__ = __repr__

ophyd_async/core/detector.py

@@ -1,27 +1,47 @@
 """Module which defines abstract classes to work with detectors"""
+
 import asyncio
+import time
 from abc import ABC, abstractmethod
+from dataclasses import dataclass
 from enum import Enum
-from typing import AsyncIterator, Dict, Optional, Sequence
+from typing import (
+    AsyncGenerator,
+    AsyncIterator,
+    Callable,
+    Dict,
+    Generic,
+    List,
+    Optional,
+    Sequence,
+    TypeVar,
+)
 
 from bluesky.protocols import (
-    Asset,
-    Configurable,
+    Collectable,
     Descriptor,
-    Readable,
+    Flyable,
+    Preparable,
     Reading,
     Stageable,
+    StreamAsset,
     Triggerable,
-    WritesExternalAssets,
+    WritesStreamAssets,
 )
 
+from ophyd_async.protocols import AsyncConfigurable, AsyncReadable
+
 from .async_status import AsyncStatus
 from .device import Device
 from .signal import SignalR
 from .utils import DEFAULT_TIMEOUT, merge_gathered_dicts
 
+T = TypeVar("T")
+
 
 class DetectorTrigger(str, 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
@@ -32,7 +52,26 @@ class DetectorTrigger(str, Enum):
     variable_gate = "variable_gate"
 
 
+@dataclass(frozen=True)
+class TriggerInfo:
+    """Minimal set of information required to setup triggering on a detector"""
+
+    #: Number of triggers that will be sent
+    num: int
+    #: Sort of triggers that will be sent
+    trigger: DetectorTrigger
+    #: What is the minimum deadtime between triggers
+    deadtime: float
+    #: What is the maximum high time of the triggers
+    livetime: float
+
+
 class DetectorControl(ABC):
+    """
+    Classes implementing this interface should hold the logic for
+    arming and disarming a detector
+    """
+
     @abstractmethod
     def get_deadtime(self, exposure: float) -> float:
         """For a given exposure, how long should the time between exposures be"""
@@ -40,21 +79,36 @@ class DetectorControl(ABC):
     @abstractmethod
     async def arm(
         self,
+        num: int,
         trigger: DetectorTrigger = DetectorTrigger.internal,
-        num: int = 0,
         exposure: Optional[float] = None,
     ) -> AsyncStatus:
-        """Arm the detector and return AsyncStatus.
+        """
+        Arm detector, do all necessary steps to prepare detector for triggers.
+
+        Args:
+            num: Expected number of frames
+            trigger: Type of trigger for which to prepare the detector. Defaults to
+            DetectorTrigger.internal.
+            exposure: 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.
 
-        Awaiting the return value will wait for num frames to be written.
+        Returns:
+            AsyncStatus: Status representing the arm operation. This function returning
+            represents the start of the arm. The returned status completing means
+            the detector is now armed.
         """
 
     @abstractmethod
     async def disarm(self):
-        """Disarm the detector"""
+        """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)"""
+
     @abstractmethod
     async def open(self, multiplier: int = 1) -> Dict[str, Descriptor]:
         """Open writer and wait for it to be ready for data.
@@ -68,40 +122,39 @@ class DetectorWriter(ABC):
         """
 
     @abstractmethod
-    async def wait_for_index(
-        self, index: int, timeout: Optional[float] = DEFAULT_TIMEOUT
-    ) -> None:
-        """Wait until a specific index is ready to be collected"""
+    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"""
 
     @abstractmethod
     async def get_indices_written(self) -> int:
         """Get the number of indices written"""
 
     @abstractmethod
-    def collect_stream_docs(self, indices_written: int) -> AsyncIterator[Asset]:
+    def collect_stream_docs(self, indices_written: int) -> AsyncIterator[StreamAsset]:
         """Create Stream docs up to given number written"""
 
     @abstractmethod
     async def close(self) -> None:
-        """Close writer and wait for it to be finished"""
+        """Close writer, blocks until I/O is complete"""
 
 
 class StandardDetector(
     Device,
     Stageable,
-    Configurable,
-    Readable,
+    AsyncConfigurable,
+    AsyncReadable,
     Triggerable,
-    WritesExternalAssets,
+    Preparable,
+    Flyable,
+    Collectable,
+    WritesStreamAssets,
+    Generic[T],
 ):
-    """Detector with useful default behaviour.
-
-    Must be supplied instances of classes that inherit from DetectorControl and
-    DetectorData, to dictate how the detector will be controlled (i.e. arming and
-    disarming) as well as how the detector data will be written (i.e. opening and
-    closing the writer, and handling data writing indices).
-
-    NOTE: only for step-scans.
+    """
+    Useful detector base class for step and fly scanning detectors.
+    Aggregates controller and writer logic together.
     """
 
     def __init__(
@@ -113,20 +166,34 @@ class StandardDetector(
         writer_timeout: float = DEFAULT_TIMEOUT,
     ) -> None:
         """
-        Parameters
-        ----------
-        control:
-            instance of class which inherits from :class:`DetectorControl`
-        data:
-            instance of class which inherits from :class:`DetectorData`
-        name:
-            detector name
+        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 "".
+            writer_timeout: Timeout for frame writing to start, if the
+            timeout is reached, ophyd-async assumes the detector
+            has a problem and raises an error.
+            Defaults to DEFAULT_TIMEOUT.
         """
         self._controller = controller
         self._writer = writer
         self._describe: Dict[str, Descriptor] = {}
         self._config_sigs = list(config_sigs)
         self._frame_writing_timeout = writer_timeout
+        # For prepare
+        self._arm_status: Optional[AsyncStatus] = None
+        self._trigger_info: Optional[TriggerInfo] = None
+        # For kickoff
+        self._watchers: List[Callable] = []
+        self._fly_status: Optional[AsyncStatus] = None
+        self._fly_start: float
+
+        self._intial_frame: int
+        self._last_frame: int
         super().__init__(name)
 
     @property
@@ -137,14 +204,20 @@ class StandardDetector(
     def writer(self) -> DetectorWriter:
         return self._writer
 
-    async def check_config_sigs(self):
+    @AsyncStatus.wrap
+    async def stage(self) -> None:
+        # Disarm the detector, stop filewriting, and open file for writing.
+        await self._check_config_sigs()
+        await asyncio.gather(self.writer.close(), self.controller.disarm())
+        self._describe = await self.writer.open()
+
+    async def _check_config_sigs(self):
         """Checks configuration signals are named and connected."""
         for signal in self._config_sigs:
             if signal._name == "":
                 raise Exception(
                     "config signal must be named before it is passed to the detector"
                 )
-
             try:
                 await signal.get_value()
             except NotImplementedError:
@@ -154,46 +227,122 @@ class StandardDetector(
                 )
 
     @AsyncStatus.wrap
-    async def stage(self) -> None:
-        """Disarm the detector, stop filewriting, and open file for writing."""
-        await self.check_config_sigs()
-        await asyncio.gather(self.writer.close(), self.controller.disarm())
-        self._describe = await self.writer.open()
+    async def unstage(self) -> None:
+        # Stop data writing.
+        await self.writer.close()
+
+    async def read_configuration(self) -> Dict[str, Reading]:
+        return await merge_gathered_dicts(sig.read() for sig in self._config_sigs)
 
     async def describe_configuration(self) -> Dict[str, Descriptor]:
         return await merge_gathered_dicts(sig.describe() for sig in self._config_sigs)
 
-    async def read_configuration(self) -> Dict[str, Reading]:
-        return await merge_gathered_dicts(sig.read() for sig in self._config_sigs)
+    async def read(self) -> Dict[str, Reading]:
+        # All data is in StreamResources, not Events, so nothing to output here
+        return {}
 
-    def describe(self) -> Dict[str, Descriptor]:
+    async def describe(self) -> Dict[str, Descriptor]:
         return self._describe
 
     @AsyncStatus.wrap
     async def trigger(self) -> None:
-        """Arm the detector and wait for it to finish."""
+        # Arm the detector and wait for it to finish.
         indices_written = await self.writer.get_indices_written()
-        written_status = await self.controller.arm(DetectorTrigger.internal, num=1)
+        written_status = await self.controller.arm(
+            num=1,
+            trigger=DetectorTrigger.internal,
+        )
         await written_status
-        await self.writer.wait_for_index(
-            indices_written + 1, timeout=self._frame_writing_timeout
+        end_observation = indices_written + 1
+
+        async for index in self.writer.observe_indices_written(
+            self._frame_writing_timeout
+        ):
+            if index >= end_observation:
+                break
+
+    def prepare(
+        self,
+        value: T,
+    ) -> AsyncStatus:
+        # Just arm detector for the time being
+        return AsyncStatus(self._prepare(value))
+
+    async def _prepare(self, value: T) -> None:
+        """
+        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
+        """
+        assert type(value) is TriggerInfo
+        self._trigger_info = value
+        self._initial_frame = await self.writer.get_indices_written()
+        self._last_frame = self._initial_frame + self._trigger_info.num
+
+        required = self.controller.get_deadtime(self._trigger_info.livetime)
+        assert required <= self._trigger_info.deadtime, (
+            f"Detector {self.controller} needs at least {required}s deadtime, "
+            f"but trigger logic provides only {self._trigger_info.deadtime}s"
         )
 
-    async def read(self) -> Dict[str, Reading]:
-        """Read the detector"""
-        # All data is in StreamResources, not Events, so nothing to output here
-        return {}
+        self._arm_status = await self.controller.arm(
+            num=self._trigger_info.num,
+            trigger=self._trigger_info.trigger,
+            exposure=self._trigger_info.livetime,
+        )
 
-    async def collect_asset_docs(self) -> AsyncIterator[Asset]:
-        """Collect stream datum documents for all indices written."""
-        indices_written = await self.writer.get_indices_written()
+    @AsyncStatus.wrap
+    async def kickoff(self) -> None:
+        self._fly_status = AsyncStatus(self._fly(), self._watchers)
+        self._fly_start = time.monotonic()
+
+    async def _fly(self) -> None:
+        await self._observe_writer_indicies(self._last_frame)
+
+    async def _observe_writer_indicies(self, end_observation: int):
+        async for index in self.writer.observe_indices_written(
+            self._frame_writing_timeout
+        ):
+            for watcher in self._watchers:
+                watcher(
+                    name=self.name,
+                    current=index,
+                    initial=self._initial_frame,
+                    target=end_observation,
+                    unit="",
+                    precision=0,
+                    time_elapsed=time.monotonic() - self._fly_start,
+                )
+            if index >= end_observation:
+                break
+
+    @AsyncStatus.wrap
+    async def complete(self) -> AsyncStatus:
+        assert self._fly_status, "Kickoff not run"
+        return await self._fly_status
+
+    async def describe_collect(self) -> Dict[str, Descriptor]:
+        return self._describe
 
-        async for doc in self.writer.collect_stream_docs(indices_written):
+    async def collect_asset_docs(
+        self, index: Optional[int] = None
+    ) -> AsyncIterator[StreamAsset]:
+        # Collect stream datum documents for all indices written.
+        # The index is optional, and provided for fly scans, however this needs to be
+        # retrieved for step scans.
+        if not index:
+            index = await self.writer.get_indices_written()
+        async for doc in self.writer.collect_stream_docs(index):
             yield doc
-        # async for doc in self.writer.collect_stream_docs(indices_written):
-        #     yield doc
 
-    @AsyncStatus.wrap
-    async def unstage(self) -> None:
-        """Stop data writing."""
-        await self.writer.close()
+    async def get_index(self) -> int:
+        return await self.writer.get_indices_written()

ophyd_async/core/device.py

@@ -1,16 +1,24 @@
 """Base device"""
+
 from __future__ import annotations
 
-import asyncio
-import logging
 import sys
-from contextlib import suppress
-from typing import Any, Dict, Generator, Iterator, Optional, Set, Tuple, TypeVar
+from typing import (
+    Any,
+    Coroutine,
+    Dict,
+    Generator,
+    Iterator,
+    Optional,
+    Set,
+    Tuple,
+    TypeVar,
+)
 
 from bluesky.protocols import HasName
 from bluesky.run_engine import call_in_bluesky_event_loop
 
-from .utils import NotConnected, wait_for_connection
+from .utils import DEFAULT_TIMEOUT, NotConnected, wait_for_connection
 
 
 class Device(HasName):
@@ -50,16 +58,21 @@ class Device(HasName):
             child.set_name(child_name)
             child.parent = self
 
-    async def connect(self, sim: bool = False):
+    async def connect(self, sim: bool = False, timeout: float = DEFAULT_TIMEOUT):
         """Connect self and all child Devices.
 
+        Contains a timeout that gets propagated to child.connect methods.
+
         Parameters
         ----------
         sim:
             If True then connect in simulation mode.
+        timeout:
+            Time to wait before failing with a TimeoutError.
         """
         coros = {
-            name: child_device.connect(sim) for name, child_device in self.children()
+            name: child_device.connect(sim, timeout=timeout)
+            for name, child_device in self.children()
         }
         if coros:
             await wait_for_connection(**coros)
@@ -69,6 +82,14 @@ VT = TypeVar("VT", bound=Device)
 
 
 class DeviceVector(Dict[int, VT], Device):
+    """
+    Defines device components with indices.
+
+    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.demo.DynamicSensorGroup`
+    """
+
     def children(self) -> Generator[Tuple[str, Device], None, None]:
         for attr_name, attr in self.items():
             if isinstance(attr, Device):
@@ -140,41 +161,19 @@ class DeviceCollector:
 
     async def _on_exit(self) -> None:
         # Name and kick off connect for devices
-        tasks: Dict[asyncio.Task, str] = {}
+        connect_coroutines: Dict[str, Coroutine] = {}
         for name, obj in self._objects_on_exit.items():
             if name not in self._names_on_enter and isinstance(obj, Device):
                 if self._set_name and not obj.name:
                     obj.set_name(name)
                 if self._connect:
-                    task = asyncio.create_task(obj.connect(self._sim))
-                    tasks[task] = name
-        # Wait for all the signals to have finished
-        if tasks:
-            await self._wait_for_tasks(tasks)
-
-    async def _wait_for_tasks(self, tasks: Dict[asyncio.Task, str]):
-        done, pending = await asyncio.wait(tasks, timeout=self._timeout)
-        if pending:
-            msg = f"{len(pending)} Devices did not connect:"
-            for t in pending:
-                t.cancel()
-                with suppress(Exception):
-                    await t
-                e = t.exception()
-                msg += f"\n  {tasks[t]}: {type(e).__name__}"
-                lines = str(e).splitlines()
-                if len(lines) <= 1:
-                    msg += f": {e}"
-                else:
-                    msg += "".join(f"\n    {line}" for line in lines)
-            logging.error(msg)
-        raised = [t for t in done if t.exception()]
-        if raised:
-            logging.error(f"{len(raised)} Devices raised an error:")
-            for t in raised:
-                logging.exception(f"  {tasks[t]}:", exc_info=t.exception())
-        if pending or raised:
-            raise NotConnected("Not all Devices connected")
+                    connect_coroutines[name] = obj.connect(
+                        self._sim, timeout=self._timeout
+                    )
+
+        # Connect to all the devices
+        if connect_coroutines:
+            await wait_for_connection(**connect_coroutines)
 
     async def __aexit__(self, type, value, traceback):
         self._objects_on_exit = self._caller_locals()
@@ -182,4 +181,12 @@ class DeviceCollector:
 
     def __exit__(self, type_, value, traceback):
         self._objects_on_exit = self._caller_locals()
-        return call_in_bluesky_event_loop(self._on_exit())
+        try:
+            fut = call_in_bluesky_event_loop(self._on_exit())
+        except RuntimeError:
+            raise NotConnected(
+                "Could not connect devices. Is the bluesky event loop running? See "
+                "https://blueskyproject.io/ophyd-async/main/"
+                "user/explanations/event-loop-choice.html for more info."
+            )
+        return fut