ophyd-async 0.3a1__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.3a1'
+__version__ = version = '0.3a2'
 __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,7 +23,7 @@ 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,
@@ -29,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
@@ -61,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",

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,
     Flyable,
     Preparable,
-    Readable,
     Reading,
     Stageable,
     StreamAsset,
@@ -30,6 +29,8 @@ 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
@@ -39,6 +40,8 @@ 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 +54,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 +67,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,17 +83,32 @@ 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]:
         """Open writer and wait for it to be ready for data.
@@ -100,7 +125,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,27 +137,24 @@ 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__(
@@ -144,14 +166,18 @@ 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
@@ -180,12 +206,12 @@ 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 == "":
@@ -202,7 +228,7 @@ 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]:
@@ -212,16 +238,15 @@ class StandardDetector(
         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, 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(
             num=1,
@@ -240,11 +265,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 +279,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
@@ -307,11 +336,9 @@ class StandardDetector(
     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 .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,17 +63,16 @@ 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]:
         return await merge_gathered_dicts(

ophyd_async/core/signal.py

@@ -2,19 +2,20 @@ from __future__ import annotations
 
 import asyncio
 import functools
-from typing import AsyncGenerator, Callable, Dict, Generic, Optional, Union
+from typing import AsyncGenerator, Callable, Dict, Generic, Optional, Tuple, Type, Union
 
 from bluesky.protocols import (
     Descriptor,
     Locatable,
     Location,
     Movable,
-    Readable,
     Reading,
     Stageable,
     Subscribable,
 )
 
+from ophyd_async.protocols import AsyncReadable
+
 from .async_status import AsyncStatus
 from .device import Device
 from .signal_backend import SignalBackend
@@ -45,24 +46,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 +67,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 +128,7 @@ class _SignalCache(Generic[T]):
         return self._staged or bool(self._listeners)
 
 
-class SignalR(Signal[T], Readable, Stageable, Subscribable):
+class SignalR(Signal[T], AsyncReadable, Stageable, Subscribable):
     """Signal that can be read from and monitored"""
 
     _cache: Optional[_SignalCache] = None
@@ -168,7 +163,7 @@ class SignalR(Signal[T], Readable, Stageable, Subscribable):
     @_add_timeout
     async def describe(self) -> Dict[str, Descriptor]:
         """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_descriptor(self.source)}
 
     @_add_timeout
     async def get_value(self, cached: Optional[bool] = None) -> T:
@@ -253,6 +248,30 @@ 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 observe_value(signal: SignalR[T], timeout=None) -> AsyncGenerator[T, None]:
     """Subscribe to the value of a signal so it can be iterated from.
 

ophyd_async/core/signal_backend.py

@@ -13,7 +13,10 @@ class SignalBackend(Generic[T]):
     datatype: Optional[Type[T]] = None
 
     #: Like ca://PV_PREFIX:SIGNAL
-    source: str = ""
+    @abstractmethod
+    def source(name: str) -> str:
+        """Return source of signal. Signals may pass a name to the backend, which can be
+        used or discarded."""
 
     @abstractmethod
     async def connect(self, timeout: float = DEFAULT_TIMEOUT):
@@ -24,7 +27,7 @@ class SignalBackend(Generic[T]):
         """Put a value to the PV, if wait then wait for completion for up to timeout"""
 
     @abstractmethod
-    async def get_descriptor(self) -> Descriptor:
+    async def get_descriptor(self, source: str) -> Descriptor:
         """Metadata like source, dtype, shape, precision, units"""
 
     @abstractmethod

ophyd_async/core/sim_signal_backend.py

@@ -2,13 +2,13 @@ from __future__ import annotations
 
 import asyncio
 import inspect
-import re
 import time
 from collections import abc
 from dataclasses import dataclass
 from enum import Enum
 from typing import Any, Dict, Generic, Optional, Type, Union, cast, get_origin
 
+import numpy as np
 from bluesky.protocols import Descriptor, Dtype, Reading
 
 from .signal_backend import SignalBackend
@@ -37,11 +37,16 @@ class SimConverter(Generic[T]):
         )
 
     def descriptor(self, source: str, value) -> Descriptor:
+        dtype = type(value)
+        if np.issubdtype(dtype, np.integer):
+            dtype = int
+        elif np.issubdtype(dtype, np.floating):
+            dtype = float
         assert (
-            type(value) in primitive_dtypes
+            dtype in primitive_dtypes
         ), f"invalid converter for value of type {type(value)}"
-        dtype = primitive_dtypes[type(value)]
-        return dict(source=source, dtype=dtype, shape=[])
+        dtype_name = primitive_dtypes[dtype]
+        return {"source": source, "dtype": dtype_name, "shape": []}
 
     def make_initial_value(self, datatype: Optional[Type[T]]) -> T:
         if datatype is None:
@@ -52,7 +57,7 @@ class SimConverter(Generic[T]):
 
 class SimArrayConverter(SimConverter):
     def descriptor(self, source: str, value) -> Descriptor:
-        return dict(source=source, dtype="array", shape=[len(value)])
+        return {"source": source, "dtype": "array", "shape": [len(value)]}
 
     def make_initial_value(self, datatype: Optional[Type[T]]) -> T:
         if datatype is None:
@@ -76,9 +81,7 @@ class SimEnumConverter(SimConverter):
 
     def descriptor(self, source: str, value) -> Descriptor:
         choices = [e.value for e in self.enum_class]
-        return dict(
-            source=source, dtype="string", shape=[], choices=choices
-        )  # type: ignore
+        return {"source": source, "dtype": "string", "shape": [], "choices": choices}  # type: ignore
 
     def make_initial_value(self, datatype: Optional[Type[T]]) -> T:
         if datatype is None:
@@ -109,23 +112,32 @@ class SimSignalBackend(SignalBackend[T]):
     """An simulated backend to a Signal, created with ``Signal.connect(sim=True)``"""
 
     _value: T
-    _initial_value: T
+    _initial_value: Optional[T]
     _timestamp: float
     _severity: int
 
-    def __init__(self, datatype: Optional[Type[T]], source: str) -> None:
-        pv = re.split(r"://", source)[-1]
-        self.source = f"sim://{pv}"
+    def __init__(
+        self,
+        datatype: Optional[Type[T]],
+        initial_value: Optional[T] = None,
+    ) -> None:
         self.datatype = datatype
-        self.pv = source
         self.converter: SimConverter = DisconnectedSimConverter()
+        self._initial_value = initial_value
         self.put_proceeds = asyncio.Event()
         self.put_proceeds.set()
         self.callback: Optional[ReadingValueCallback[T]] = None
 
+    def source(self, name: str) -> str:
+        return f"soft://{name}"
+
     async def connect(self, timeout: float = DEFAULT_TIMEOUT) -> None:
         self.converter = make_converter(self.datatype)
-        self._initial_value = self.converter.make_initial_value(self.datatype)
+        if self._initial_value is None:
+            self._initial_value = self.converter.make_initial_value(self.datatype)
+        else:
+            # convert potentially unconverted initial value passed to init method
+            self._initial_value = self.converter.write_value(self._initial_value)
         self._severity = 0
 
         await self.put(None)
@@ -152,8 +164,8 @@ class SimSignalBackend(SignalBackend[T]):
         if self.callback:
             self.callback(reading, self._value)
 
-    async def get_descriptor(self) -> Descriptor:
-        return self.converter.descriptor(self.source, self._value)
+    async def get_descriptor(self, source: str) -> Descriptor:
+        return self.converter.descriptor(source, self._value)
 
     async def get_reading(self) -> Reading:
         return self.converter.reading(self._value, self._timestamp, self._severity)

ophyd_async/core/standard_readable.py

@@ -1,6 +1,8 @@
 from typing import Dict, Sequence, Tuple
 
-from bluesky.protocols import Configurable, Descriptor, Readable, Reading, Stageable
+from bluesky.protocols import Descriptor, Reading, Stageable
+
+from ophyd_async.protocols import AsyncConfigurable, AsyncReadable
 
 from .async_status import AsyncStatus
 from .device import Device
@@ -8,7 +10,7 @@ from .signal import SignalR
 from .utils import merge_gathered_dicts
 
 
-class StandardReadable(Device, Readable, Configurable, Stageable):
+class StandardReadable(Device, AsyncReadable, AsyncConfigurable, Stageable):
     """Device that owns its children and provides useful default behavior.
 
     - When its name is set it renames child Devices