ophyd-async 0.2.0__tar.gz → 0.3a1__tar.gz

{ophyd-async-0.2.0 → ophyd-async-0.3a1}/.codecov.yml

@@ -5,7 +5,7 @@ coverage:
     project:
       default:
         target: auto
-        threshold: 0.1%
+        threshold: 1%
     patch:
       default:
         target: auto

{ophyd-async-0.2.0/src/ophyd_async.egg-info → ophyd-async-0.3a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ophyd-async
-Version: 0.2.0
+Version: 0.3a1
 Summary: Asynchronous Bluesky hardware abstraction code, compatible with control systems like EPICS and Tango
 Author-email: Tom Cobb <tom.cobb@diamond.ac.uk>
 License: BSD 3-Clause License
@@ -46,7 +46,7 @@ Requires-Dist: networkx>=2.0
 Requires-Dist: numpy
 Requires-Dist: packaging
 Requires-Dist: pint
-Requires-Dist: bluesky
+Requires-Dist: bluesky>=1.13.0a3
 Requires-Dist: event-model
 Requires-Dist: p4p
 Requires-Dist: pyyaml

ophyd-async-0.3a1/docs/user/explanations/event-loop-choice.rst

@@ -0,0 +1,52 @@
+Device Collector Event-Loop Choice
+----------------------------------
+
+In a sync context, the ophyd-async :python:`DeviceCollector` requires the bluesky event-loop
+to connect to devices. In an async context, it does not.
+
+Sync Context
+============
+
+In a sync context the run-engine must be initialized prior to connecting to devices.
+We enfore usage of the bluesky event-loop in this context.
+
+The following will fail if :python:`RE = RunEngine()` has not been called already:
+
+.. code:: python
+
+  with DeviceCollector():
+      device1 = Device1(prefix)
+      device2 = Device2(prefix)
+      device3 = Device3(prefix)
+
+The :python:`DeviceCollector` connects to devices in the event-loop created in the run-engine.
+
+
+Async Context
+=============
+
+In an async context device connection is decoupled from the run-engine.
+The following attempts connection to all the devices in the :python:`DeviceCollector`
+before or after run-engine initialization.
+
+.. code:: python
+
+  async def connection_function() :
+      async with DeviceCollector():
+          device1 = Device1(prefix)
+          device2 = Device2(prefix)
+          device3 = Device3(prefix)
+
+  asyncio.run(connection_function())
+
+The devices will be unable to be used in the run-engine unless they share the same event-loop.
+When the run-engine is initialised it will create a new background event-loop to use if one
+is not passed in with :python:`RunEngine(loop=loop)`.
+
+If the user wants to use devices in the async :python:`DeviceCollector` within the run-engine
+they can either:
+
+* Run the :python:`DeviceCollector` first and pass the event-loop into the run-engine.
+* Initialize the run-engine first and run the :python:`DeviceCollector` using the bluesky event-loop.
+
+

{ophyd-async-0.2.0 → ophyd-async-0.3a1}/docs/user/index.rst

@@ -45,6 +45,7 @@ side-bar.
             :maxdepth: 1
 
             explanations/docs-structure
+            explanations/event-loop-choice
 
         +++
 

{ophyd-async-0.2.0 → ophyd-async-0.3a1}/pyproject.toml

@@ -18,11 +18,11 @@ dependencies = [
     "numpy",
     "packaging",
     "pint",
-    "bluesky",
+    "bluesky>=1.13.0a3",
     "event-model",
     "p4p",
     "pyyaml",
-] # Add project dependencies here, e.g. ["click", "numpy"]
+]
 
 dynamic = ["version"]
 license.file = "LICENSE"

{ophyd-async-0.2.0 → ophyd-async-0.3a1}/src/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.3a1'
+__version_tuple__ = version_tuple = (0, 3)

{ophyd-async-0.2.0 → ophyd-async-0.3a1}/src/ophyd_async/core/__init__.py

@@ -10,18 +10,14 @@ from .detector import DetectorControl, DetectorTrigger, DetectorWriter, Standard
 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, TriggerInfo, TriggerLogic
 from .signal import (
     Signal,
     SignalR,
@@ -79,8 +75,6 @@ __all__ = [
     "StaticDirectoryProvider",
     "StandardReadable",
     "TriggerInfo",
-    "DetectorGroupLogic",
-    "SameTriggerDetectorGroupLogic",
     "TriggerLogic",
     "HardwareTriggeredFlyable",
     "DEFAULT_TIMEOUT",
@@ -97,4 +91,6 @@ __all__ = [
     "save_to_yaml",
     "set_signal_values",
     "walk_rw_signals",
+    "load_device",
+    "save_device",
 ]

ophyd-async-0.3a1/src/ophyd_async/core/_providers.py

@@ -0,0 +1,66 @@
+from abc import abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Protocol, Sequence, Union
+
+
+@dataclass
+class DirectoryInfo:
+    """
+    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):
+    @abstractmethod
+    def __call__(self) -> DirectoryInfo:
+        """Get the current directory to write files into"""
+
+
+class StaticDirectoryProvider(DirectoryProvider):
+    def __init__(
+        self,
+        directory_path: Union[str, Path],
+        filename_prefix: str = "",
+        filename_suffix: str = "",
+        resource_dir: Path = Path("."),
+    ) -> None:
+        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
+
+
+class NameProvider(Protocol):
+    @abstractmethod
+    def __call__(self) -> str:
+        """Get the name to be used as a data_key in the descriptor document"""
+
+
+class ShapeProvider(Protocol):
+    @abstractmethod
+    async def __call__(self) -> Sequence[int]:
+        """Get the shape of the data collection"""

{ophyd-async-0.2.0 → ophyd-async-0.3a1}/src/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-0.2.0 → ophyd-async-0.3a1}/src/ophyd_async/core/detector.py

@@ -1,18 +1,33 @@
 """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,
+    List,
+    Optional,
+    Sequence,
+    TypeVar,
+)
 
 from bluesky.protocols import (
-    Asset,
+    Collectable,
     Configurable,
     Descriptor,
+    Flyable,
+    Preparable,
     Readable,
     Reading,
     Stageable,
+    StreamAsset,
     Triggerable,
-    WritesExternalAssets,
+    WritesStreamAssets,
 )
 
 from .async_status import AsyncStatus
@@ -20,6 +35,8 @@ from .device import Device
 from .signal import SignalR
 from .utils import DEFAULT_TIMEOUT, merge_gathered_dicts
 
+T = TypeVar("T")
+
 
 class DetectorTrigger(str, Enum):
     #: Detector generates internal trigger for given rate
@@ -32,6 +49,18 @@ class DetectorTrigger(str, Enum):
     variable_gate = "variable_gate"
 
 
+@dataclass(frozen=True)
+class TriggerInfo:
+    #: 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):
     @abstractmethod
     def get_deadtime(self, exposure: float) -> float:
@@ -40,8 +69,8 @@ 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.
@@ -68,17 +97,17 @@ 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 each index 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
@@ -92,16 +121,18 @@ class StandardDetector(
     Configurable,
     Readable,
     Triggerable,
-    WritesExternalAssets,
+    Preparable,
+    Flyable,
+    Collectable,
+    WritesStreamAssets,
 ):
-    """Detector with useful default behaviour.
+    """Detector with useful step and flyscan 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.
     """
 
     def __init__(
@@ -127,6 +158,16 @@ class StandardDetector(
         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,6 +178,13 @@ class StandardDetector(
     def writer(self) -> DetectorWriter:
         return self._writer
 
+    @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:
@@ -144,7 +192,6 @@ class StandardDetector(
                 raise Exception(
                     "config signal must be named before it is passed to the detector"
                 )
-
             try:
                 await signal.get_value()
             except NotImplementedError:
@@ -154,17 +201,20 @@ 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]:
+        """Read the detector"""
+        # All data is in StreamResources, not Events, so nothing to output here
+        return {}
 
     def describe(self) -> Dict[str, Descriptor]:
         return self._describe
@@ -173,27 +223,99 @@ class StandardDetector(
     async def trigger(self) -> None:
         """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:
+        """Arm detector"""
+        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.
+        """
+        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 def collect_asset_docs(
+        self, index: Optional[int] = None
+    ) -> AsyncIterator[StreamAsset]:
+        """Collect stream datum documents for all indices written.
 
-        async for doc in self.writer.collect_stream_docs(indices_written):
+        The index is optional, and provided for flyscans, however this needs to be
+        retrieved for stepscans.
+        """
+        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-0.2.0 → ophyd-async-0.3a1}/src/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)
@@ -140,41 +153,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 +173,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