ophyd-async 0.3a1__py3-none-any.whl → 0.3a3__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.3a1'
+__version__ = version = '0.3a3'
 __version_tuple__ = version_tuple = (0, 3)

ophyd_async/core/__init__.py

@@ -6,7 +6,13 @@ 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,
@@ -17,23 +23,29 @@ from .device_save_loader import (
     set_signal_values,
     walk_rw_signals,
 )
-from .flyer import HardwareTriggeredFlyable, TriggerInfo, TriggerLogic
+from .flyer import HardwareTriggeredFlyable, TriggerLogic
 from .signal import (
     Signal,
     SignalR,
     SignalRW,
     SignalW,
     SignalX,
+    assert_configuration,
+    assert_emitted,
+    assert_reading,
+    assert_value,
     observe_value,
     set_and_wait_for_value,
     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
 from .sim_signal_backend import SimSignalBackend
-from .standard_readable import StandardReadable
+from .standard_readable import ConfigSignal, HintedSignal, StandardReadable
 from .utils import (
     DEFAULT_TIMEOUT,
     Callback,
@@ -61,6 +73,8 @@ __all__ = [
     "SignalW",
     "SignalRW",
     "SignalX",
+    "soft_signal_r_and_backend",
+    "soft_signal_rw",
     "observe_value",
     "set_and_wait_for_value",
     "set_sim_callback",
@@ -74,6 +88,8 @@ __all__ = [
     "ShapeProvider",
     "StaticDirectoryProvider",
     "StandardReadable",
+    "ConfigSignal",
+    "HintedSignal",
     "TriggerInfo",
     "TriggerLogic",
     "HardwareTriggeredFlyable",
@@ -93,4 +109,8 @@ __all__ = [
     "walk_rw_signals",
     "load_device",
     "save_device",
+    "assert_reading",
+    "assert_value",
+    "assert_configuration",
+    "assert_emitted",
 ]

ophyd_async/core/_providers.py

@@ -39,8 +39,10 @@ class StaticDirectoryProvider(DirectoryProvider):
         directory_path: Union[str, Path],
         filename_prefix: str = "",
         filename_suffix: str = "",
-        resource_dir: Path = Path("."),
+        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(

ophyd_async/core/detector.py

@@ -10,6 +10,7 @@ from typing import (
     AsyncIterator,
     Callable,
     Dict,
+    Generic,
     List,
     Optional,
     Sequence,
@@ -18,11 +19,9 @@ from typing import (
 
 from bluesky.protocols import (
     Collectable,
-    Configurable,
-    Descriptor,
+    DataKey,
     Flyable,
     Preparable,
-    Readable,
     Reading,
     Stageable,
     StreamAsset,
@@ -30,15 +29,18 @@ from bluesky.protocols import (
     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
@@ -51,6 +53,8 @@ class DetectorTrigger(str, Enum):
 
 @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
@@ -62,6 +66,11 @@ class TriggerInfo:
 
 
 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"""
@@ -73,19 +82,34 @@ class DetectorControl(ABC):
         trigger: DetectorTrigger = DetectorTrigger.internal,
         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]:
+    async def open(self, multiplier: int = 1) -> Dict[str, DataKey]:
         """Open writer and wait for it to be ready for data.
 
         Args:
@@ -100,7 +124,7 @@ class DetectorWriter(ABC):
     def observe_indices_written(
         self, timeout=DEFAULT_TIMEOUT
     ) -> AsyncGenerator[int, None]:
-        """Yield each index as it is written"""
+        """Yield the index of each frame (or equivalent data point) as it is written"""
 
     @abstractmethod
     async def get_indices_written(self) -> int:
@@ -112,50 +136,51 @@ class DetectorWriter(ABC):
 
     @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,
     Preparable,
     Flyable,
     Collectable,
     WritesStreamAssets,
+    Generic[T],
 ):
-    """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).
-
+    """
+    Useful detector base class for step and fly scanning detectors.
+    Aggregates controller and writer logic together.
     """
 
     def __init__(
         self,
         controller: DetectorControl,
         writer: DetectorWriter,
-        config_sigs: Sequence[SignalR] = (),
+        config_sigs: Sequence[AsyncReadable] = (),
         name: str = "",
         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._describe: Dict[str, DataKey] = {}
         self._config_sigs = list(config_sigs)
         self._frame_writing_timeout = writer_timeout
         # For prepare
@@ -180,15 +205,15 @@ class StandardDetector(
 
     @AsyncStatus.wrap
     async def stage(self) -> None:
-        """Disarm the detector, stop filewriting, and open file for writing."""
-        await self.check_config_sigs()
+        # 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):
+    async def _check_config_sigs(self):
         """Checks configuration signals are named and connected."""
         for signal in self._config_sigs:
-            if signal._name == "":
+            if signal.name == "":
                 raise Exception(
                     "config signal must be named before it is passed to the detector"
                 )
@@ -202,26 +227,25 @@ class StandardDetector(
 
     @AsyncStatus.wrap
     async def unstage(self) -> None:
-        """Stop data writing."""
+        # 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]:
+    async def describe_configuration(self) -> Dict[str, DataKey]:
         return await merge_gathered_dicts(sig.describe() 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]:
+    async def describe(self) -> Dict[str, DataKey]:
         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(
             num=1,
@@ -240,11 +264,12 @@ class StandardDetector(
         self,
         value: T,
     ) -> AsyncStatus:
-        """Arm detector"""
+        # Just arm detector for the time being
         return AsyncStatus(self._prepare(value))
 
     async def _prepare(self, value: T) -> None:
-        """Arm detector.
+        """
+        Arm detector.
 
         Prepare the detector with trigger information. This is determined at and passed
         in from the plan level.
@@ -253,6 +278,9 @@ class StandardDetector(
         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
@@ -301,17 +329,15 @@ class StandardDetector(
         assert self._fly_status, "Kickoff not run"
         return await self._fly_status
 
-    async def describe_collect(self) -> Dict[str, Descriptor]:
+    async def describe_collect(self) -> Dict[str, DataKey]:
         return self._describe
 
     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 flyscans, however this needs to be
-        retrieved for stepscans.
-        """
+        # 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):

ophyd_async/core/device.py

@@ -82,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):

ophyd_async/core/flyer.py

@@ -1,10 +1,9 @@
 from abc import ABC, abstractmethod
-from typing import Dict, Generic, Optional, Sequence, TypeVar
+from typing import Dict, Generic, Sequence, TypeVar
 
-from bluesky.protocols import Descriptor, Flyable, Preparable, Reading, Stageable
+from bluesky.protocols import DataKey, Flyable, Preparable, Reading, Stageable
 
 from .async_status import AsyncStatus
-from .detector import TriggerInfo
 from .device import Device
 from .signal import SignalR
 from .utils import merge_gathered_dicts
@@ -13,18 +12,18 @@ T = TypeVar("T")
 
 
 class TriggerLogic(ABC, Generic[T]):
-    @abstractmethod
-    def trigger_info(self, value: T) -> TriggerInfo:
-        """Return info about triggers that will be produced for a given value"""
-
     @abstractmethod
     async def prepare(self, value: T):
         """Move to the start of the flyscan"""
 
     @abstractmethod
-    async def start(self):
+    async def kickoff(self):
         """Start the flyscan"""
 
+    @abstractmethod
+    async def complete(self):
+        """Block until the flyscan is done"""
+
     @abstractmethod
     async def stop(self):
         """Stop flying and wait everything to be stopped"""
@@ -45,19 +44,12 @@ class HardwareTriggeredFlyable(
     ):
         self._trigger_logic = trigger_logic
         self._configuration_signals = tuple(configuration_signals)
-        self._describe: Dict[str, Descriptor] = {}
-        self._fly_status: Optional[AsyncStatus] = None
-        self._trigger_info: Optional[TriggerInfo] = None
         super().__init__(name=name)
 
     @property
     def trigger_logic(self) -> TriggerLogic[T]:
         return self._trigger_logic
 
-    @property
-    def trigger_info(self) -> Optional[TriggerInfo]:
-        return self._trigger_info
-
     @AsyncStatus.wrap
     async def stage(self) -> None:
         await self.unstage()
@@ -71,19 +63,18 @@ class HardwareTriggeredFlyable(
         return AsyncStatus(self._prepare(value))
 
     async def _prepare(self, value: T) -> None:
-        self._trigger_info = self._trigger_logic.trigger_info(value)
         # Move to start and setup the flyscan
         await self._trigger_logic.prepare(value)
 
     @AsyncStatus.wrap
     async def kickoff(self) -> None:
-        self._fly_status = AsyncStatus(self._trigger_logic.start())
+        await self._trigger_logic.kickoff()
 
-    def complete(self) -> AsyncStatus:
-        assert self._fly_status, "Kickoff not run"
-        return self._fly_status
+    @AsyncStatus.wrap
+    async def complete(self) -> None:
+        await self._trigger_logic.complete()
 
-    async def describe_configuration(self) -> Dict[str, Descriptor]:
+    async def describe_configuration(self) -> Dict[str, DataKey]:
         return await merge_gathered_dicts(
             [sig.describe() for sig in self._configuration_signals]
         )

ophyd_async/core/signal.py

@@ -2,19 +2,30 @@ from __future__ import annotations
 
 import asyncio
 import functools
-from typing import AsyncGenerator, Callable, Dict, Generic, Optional, Union
+from typing import (
+    Any,
+    AsyncGenerator,
+    Callable,
+    Dict,
+    Generic,
+    Mapping,
+    Optional,
+    Tuple,
+    Type,
+    Union,
+)
 
 from bluesky.protocols import (
-    Descriptor,
+    DataKey,
     Locatable,
     Location,
     Movable,
-    Readable,
     Reading,
-    Stageable,
     Subscribable,
 )
 
+from ophyd_async.protocols import AsyncConfigurable, AsyncReadable, AsyncStageable
+
 from .async_status import AsyncStatus
 from .device import Device
 from .signal_backend import SignalBackend
@@ -45,24 +56,18 @@ class Signal(Device, Generic[T]):
     """A Device with the concept of a value, with R, RW, W and X flavours"""
 
     def __init__(
-        self, backend: SignalBackend[T], timeout: Optional[float] = DEFAULT_TIMEOUT
+        self,
+        backend: SignalBackend[T],
+        timeout: Optional[float] = DEFAULT_TIMEOUT,
+        name: str = "",
     ) -> None:
-        self._name = ""
+        super().__init__(name)
         self._timeout = timeout
         self._init_backend = self._backend = backend
 
-    @property
-    def name(self) -> str:
-        return self._name
-
-    def set_name(self, name: str = ""):
-        self._name = name
-
     async def connect(self, sim=False, timeout=DEFAULT_TIMEOUT):
         if sim:
-            self._backend = SimSignalBackend(
-                datatype=self._init_backend.datatype, source=self._init_backend.source
-            )
+            self._backend = SimSignalBackend(datatype=self._init_backend.datatype)
             _sim_backends[self] = self._backend
         else:
             self._backend = self._init_backend
@@ -72,7 +77,7 @@ class Signal(Device, Generic[T]):
     @property
     def source(self) -> str:
         """Like ca://PV_PREFIX:SIGNAL, or "" if not set"""
-        return self._backend.source
+        return self._backend.source(self.name)
 
     __lt__ = __le__ = __eq__ = __ge__ = __gt__ = __ne__ = _fail
 
@@ -133,7 +138,7 @@ class _SignalCache(Generic[T]):
         return self._staged or bool(self._listeners)
 
 
-class SignalR(Signal[T], Readable, Stageable, Subscribable):
+class SignalR(Signal[T], AsyncReadable, AsyncStageable, Subscribable):
     """Signal that can be read from and monitored"""
 
     _cache: Optional[_SignalCache] = None
@@ -166,9 +171,9 @@ class SignalR(Signal[T], Readable, Stageable, Subscribable):
         return {self.name: await self._backend_or_cache(cached).get_reading()}
 
     @_add_timeout
-    async def describe(self) -> Dict[str, Descriptor]:
+    async def describe(self) -> Dict[str, DataKey]:
         """Return a single item dict with the descriptor in it"""
-        return {self.name: await self._backend.get_descriptor()}
+        return {self.name: await self._backend.get_datakey(self.source)}
 
     @_add_timeout
     async def get_value(self, cached: Optional[bool] = None) -> T:
@@ -253,6 +258,115 @@ def set_sim_callback(signal: Signal[T], callback: ReadingValueCallback[T]) -> No
     return _sim_backends[signal].set_callback(callback)
 
 
+def soft_signal_rw(
+    datatype: Optional[Type[T]] = None,
+    initial_value: Optional[T] = None,
+    name: str = "",
+) -> SignalRW[T]:
+    """Creates a read-writable Signal with a SimSignalBackend"""
+    signal = SignalRW(SimSignalBackend(datatype, initial_value), name=name)
+    return signal
+
+
+def soft_signal_r_and_backend(
+    datatype: Optional[Type[T]] = None,
+    initial_value: Optional[T] = None,
+    name: str = "",
+) -> Tuple[SignalR[T], SimSignalBackend]:
+    """Returns a tuple of a read-only Signal and its SimSignalBackend through
+    which the signal can be internally modified within the device. Use
+    soft_signal_rw if you want a device that is externally modifiable
+    """
+    backend = SimSignalBackend(datatype, initial_value)
+    signal = SignalR(backend, name=name)
+    return (signal, backend)
+
+
+async def assert_value(signal: SignalR[T], value: Any) -> None:
+    """Assert a signal's value and compare it an expected signal.
+
+    Parameters
+    ----------
+    signal:
+        signal with get_value.
+    value:
+        The expected value from the signal.
+
+    Notes
+    -----
+    Example usage::
+        await assert_value(signal, value)
+
+    """
+    assert await signal.get_value() == value
+
+
+async def assert_reading(
+    readable: AsyncReadable, reading: Mapping[str, Reading]
+) -> None:
+    """Assert readings from readable.
+
+    Parameters
+    ----------
+    readable:
+        Callable with readable.read function that generate readings.
+
+    reading:
+        The expected readings from the readable.
+
+    Notes
+    -----
+    Example usage::
+        await assert_reading(readable, reading)
+
+    """
+    assert await readable.read() == reading
+
+
+async def assert_configuration(
+    configurable: AsyncConfigurable,
+    configuration: Mapping[str, Reading],
+) -> None:
+    """Assert readings from Configurable.
+
+    Parameters
+    ----------
+    configurable:
+        Configurable with Configurable.read function that generate readings.
+
+    configuration:
+        The expected readings from configurable.
+
+    Notes
+    -----
+    Example usage::
+        await assert_configuration(configurable configuration)
+
+    """
+    assert await configurable.read_configuration() == configuration
+
+
+def assert_emitted(docs: Mapping[str, list[dict]], **numbers: int):
+    """Assert emitted document generated by running a Bluesky plan
+
+    Parameters
+    ----------
+    Doc:
+        A dictionary
+
+    numbers:
+        expected emission in kwarg from
+
+    Notes
+    -----
+    Example usage::
+        assert_emitted(docs, start=1, descriptor=1,
+        resource=1, datum=1, event=1, stop=1)
+    """
+    assert list(docs) == list(numbers)
+    assert {name: len(d) for name, d in docs.items()} == numbers
+
+
 async def observe_value(signal: SignalR[T], timeout=None) -> AsyncGenerator[T, None]:
     """Subscribe to the value of a signal so it can be iterated from.