ophyd-async 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

ophyd_async/core/{_device/_signal/signal.py → signal.py}

@@ -2,24 +2,37 @@ 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,
+    Status,
     Subscribable,
 )
 
-from ...async_status import AsyncStatus
-from ...utils import DEFAULT_TIMEOUT, Callback, ReadingValueCallback, T
-from .._backend.signal_backend import SignalBackend
-from .._backend.sim_signal_backend import SimSignalBackend
-from ..device import Device
+from ophyd_async.core.mock_signal_backend import MockSignalBackend
+from ophyd_async.protocols import AsyncConfigurable, AsyncReadable, AsyncStageable
 
-_sim_backends: Dict[Signal, SimSignalBackend] = {}
+from .async_status import AsyncStatus
+from .device import Device
+from .signal_backend import SignalBackend
+from .soft_signal_backend import SoftSignalBackend
+from .utils import DEFAULT_TIMEOUT, CalculatableTimeout, CalculateTimeout, Callback, T
 
 
 def _add_timeout(func):
@@ -43,34 +56,30 @@ 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 = ""
         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):
-        if sim:
-            self._backend = SimSignalBackend(
-                datatype=self._init_backend.datatype, source=self._init_backend.source
+        self._initial_backend = self._backend = backend
+        super().__init__(name)
+
+    async def connect(
+        self, mock=False, timeout=DEFAULT_TIMEOUT, force_reconnect: bool = False
+    ):
+        if mock and not isinstance(self._backend, MockSignalBackend):
+            # Using a soft backend, look to the initial value
+            self._backend = MockSignalBackend(
+                initial_backend=self._initial_backend,
             )
-            _sim_backends[self] = self._backend
-        else:
-            self._backend = self._init_backend
-            _sim_backends.pop(self, None)
-        await self._backend.connect()
+        self.log.debug(f"Connecting to {self.source}")
+        await self._backend.connect(timeout=timeout)
 
     @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
 
@@ -89,10 +98,12 @@ class _SignalCache(Generic[T]):
         self._value: Optional[T] = None
 
         self.backend = backend
+        signal.log.debug(f"Making subscription on source {signal.source}")
         backend.set_callback(self._callback)
 
     def close(self):
         self.backend.set_callback(None)
+        self._signal.log.debug(f"Closing subscription on source {self._signal.source}")
 
     async def get_reading(self) -> Reading:
         await self._valid.wait()
@@ -105,6 +116,10 @@ class _SignalCache(Generic[T]):
         return self._value
 
     def _callback(self, reading: Reading, value: T):
+        self._signal.log.debug(
+            f"Updated subscription: reading of source {self._signal.source} changed"
+            f"from {self._reading} to {reading}"
+        )
         self._reading = reading
         self._value = value
         self._valid.set()
@@ -131,7 +146,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
@@ -164,14 +179,16 @@ 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:
         """The current value"""
-        return await self._backend_or_cache(cached).get_value()
+        value = await self._backend_or_cache(cached).get_value()
+        self.log.debug(f"get_value() on source {self.source} returned {value}")
+        return value
 
     def subscribe_value(self, function: Callback[T]):
         """Subscribe to updates in value of a device"""
@@ -199,44 +216,187 @@ class SignalR(Signal[T], Readable, Stageable, Subscribable):
 class SignalW(Signal[T], Movable):
     """Signal that can be set"""
 
-    def set(self, value: T, wait=True, timeout=None) -> AsyncStatus:
+    def set(
+        self, value: T, wait=True, timeout: CalculatableTimeout = CalculateTimeout
+    ) -> AsyncStatus:
         """Set the value and return a status saying when it's done"""
-        coro = self._backend.put(value, wait=wait, timeout=timeout or self._timeout)
-        return AsyncStatus(coro)
+        if timeout is CalculateTimeout:
+            timeout = self._timeout
+
+        async def do_set():
+            self.log.debug(f"Putting value {value} to backend at source {self.source}")
+            await self._backend.put(value, wait=wait, timeout=timeout)
+            self.log.debug(
+                f"Successfully put value {value} to backend at source {self.source}"
+            )
 
+        return AsyncStatus(do_set())
 
-class SignalRW(SignalR[T], SignalW[T]):
+
+class SignalRW(SignalR[T], SignalW[T], Locatable):
     """Signal that can be both read and set"""
 
+    async def locate(self) -> Location:
+        location: Location = {
+            "setpoint": await self._backend.get_setpoint(),
+            "readback": await self.get_value(),
+        }
+        return location
+
 
 class SignalX(Signal):
     """Signal that puts the default value"""
 
-    async def execute(self, wait=True, timeout=None):
-        """Execute the action and return a status saying when it's done"""
-        await self._backend.put(None, wait=wait, timeout=timeout or self._timeout)
+    def trigger(
+        self, wait=True, timeout: CalculatableTimeout = CalculateTimeout
+    ) -> AsyncStatus:
+        """Trigger the action and return a status saying when it's done"""
+        if timeout is CalculateTimeout:
+            timeout = self._timeout
+        coro = self._backend.put(None, wait=wait, timeout=timeout)
+        return AsyncStatus(coro)
+
 
+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 SoftSignalBackend"""
+    signal = SignalRW(SoftSignalBackend(datatype, initial_value), name=name)
+    return signal
+
+
+def soft_signal_r_and_setter(
+    datatype: Optional[Type[T]] = None,
+    initial_value: Optional[T] = None,
+    name: str = "",
+) -> Tuple[SignalR[T], Callable[[T], None]]:
+    """Returns a tuple of a read-only Signal and a callable 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 = SoftSignalBackend(datatype, initial_value)
+    signal = SignalR(backend, name=name)
 
-def set_sim_value(signal: Signal[T], value: T):
-    """Set the value of a signal that is in sim mode."""
-    _sim_backends[signal]._set_value(value)
+    return (signal, backend.set_value)
 
 
-def set_sim_put_proceeds(signal: Signal[T], proceeds: bool):
-    """Allow or block a put with wait=True from proceeding"""
-    event = _sim_backends[signal].put_proceeds
-    if proceeds:
-        event.set()
-    else:
-        event.clear()
+def _generate_assert_error_msg(
+    name: str, expected_result: str, actuall_result: str
+) -> str:
+    WARNING = "\033[93m"
+    FAIL = "\033[91m"
+    ENDC = "\033[0m"
+    return (
+        f"Expected {WARNING}{name}{ENDC} to produce"
+        + f"\n{FAIL}{actuall_result}{ENDC}"
+        + f"\nbut actually got \n{FAIL}{expected_result}{ENDC}"
+    )
+
+
+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)
+
+    """
+    actual_value = await signal.get_value()
+    assert actual_value == value, _generate_assert_error_msg(
+        signal.name, value, actual_value
+    )
+
+
+async def assert_reading(
+    readable: AsyncReadable, expected_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.
 
-def set_sim_callback(signal: Signal[T], callback: ReadingValueCallback[T]) -> None:
-    """Monitor the value of a signal that is in sim mode"""
-    return _sim_backends[signal].set_callback(callback)
+    Notes
+    -----
+    Example usage::
+        await assert_reading(readable, reading)
+
+    """
+    actual_reading = await readable.read()
+    assert expected_reading == actual_reading, _generate_assert_error_msg(
+        readable.name, expected_reading, actual_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)
+
+    """
+    actual_configurable = await configurable.read_configuration()
+    assert configuration == actual_configurable, _generate_assert_error_msg(
+        configurable.name, configuration, actual_configurable
+    )
 
 
-async def observe_value(signal: SignalR[T]) -> AsyncGenerator[T, None]:
+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), _generate_assert_error_msg(
+        "documents", list(numbers), list(docs)
+    )
+    actual_numbers = {name: len(d) for name, d in docs.items()}
+    assert actual_numbers == numbers, _generate_assert_error_msg(
+        "emitted", numbers, actual_numbers
+    )
+
+
+async def observe_value(
+    signal: SignalR[T], timeout: float | None = None, done_status: Status | None = None
+) -> AsyncGenerator[T, None]:
     """Subscribe to the value of a signal so it can be iterated from.
 
     Parameters
@@ -244,6 +404,12 @@ async def observe_value(signal: SignalR[T]) -> AsyncGenerator[T, None]:
     signal:
         Call subscribe_value on this at the start, and clear_sub on it at the
         end
+    timeout:
+        If given, how long to wait for each updated value in seconds. If an update
+        is not produced in this time then raise asyncio.TimeoutError
+    done_status:
+        If this status is complete, stop observing and make the iterator return.
+        If it raises an exception then this exception will be raised by the iterator.
 
     Notes
     -----
@@ -252,18 +418,36 @@ async def observe_value(signal: SignalR[T]) -> AsyncGenerator[T, None]:
         async for value in observe_value(sig):
             do_something_with(value)
     """
-    q: asyncio.Queue[T] = asyncio.Queue()
+
+    q: asyncio.Queue[T | Status] = asyncio.Queue()
+    if timeout is None:
+        get_value = q.get
+    else:
+
+        async def get_value():
+            return await asyncio.wait_for(q.get(), timeout)
+
+    if done_status is not None:
+        done_status.add_callback(q.put_nowait)
+
     signal.subscribe_value(q.put_nowait)
     try:
         while True:
-            yield await q.get()
+            item = await get_value()
+            if done_status and item is done_status:
+                if exc := done_status.exception():
+                    raise exc
+                else:
+                    break
+            else:
+                yield item
     finally:
         signal.clear_sub(q.put_nowait)
 
 
 class _ValueChecker(Generic[T]):
     def __init__(self, matcher: Callable[[T], bool], matcher_name: str):
-        self._last_value: Optional[T]
+        self._last_value: Optional[T] = None
         self._matcher = matcher
         self._matcher_name = matcher_name
 
@@ -273,7 +457,7 @@ class _ValueChecker(Generic[T]):
             if self._matcher(value):
                 return
 
-    async def wait_for_value(self, signal: SignalR[T], timeout: float):
+    async def wait_for_value(self, signal: SignalR[T], timeout: Optional[float]):
         try:
             await asyncio.wait_for(self._wait_for_value(signal), timeout)
         except asyncio.TimeoutError as e:
@@ -284,7 +468,7 @@ class _ValueChecker(Generic[T]):
 
 
 async def wait_for_value(
-    signal: SignalR[T], match: Union[T, Callable[[T], bool]], timeout: float
+    signal: SignalR[T], match: Union[T, Callable[[T], bool]], timeout: Optional[float]
 ):
     """Wait for a signal to have a matching value.
 
@@ -330,6 +514,10 @@ async def set_and_wait_for_value(
     - Read the same Signal to check the operation has started
     - Return the Status so calling code can wait for operation to complete
 
+    This function sets a signal to a specified value, optionally with or without a
+    ca/pv put callback, and waits for the readback value of the signal to match the
+    value it was set to.
+
     Parameters
     ----------
     signal:

ophyd_async/core/{_device/_backend/signal_backend.py → signal_backend.py}

@@ -1,9 +1,9 @@
 from abc import abstractmethod
 from typing import Generic, Optional, Type
 
-from bluesky.protocols import Descriptor, Reading
+from bluesky.protocols import DataKey, Reading
 
-from ...utils import ReadingValueCallback, T
+from .utils import DEFAULT_TIMEOUT, ReadingValueCallback, T
 
 
 class SignalBackend(Generic[T]):
@@ -13,10 +13,13 @@ class SignalBackend(Generic[T]):
     datatype: Optional[Type[T]] = None
 
     #: Like ca://PV_PREFIX:SIGNAL
-    source: str = ""
+    @abstractmethod
+    def source(self, 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):
+    async def connect(self, timeout: float = DEFAULT_TIMEOUT):
         """Connect to underlying hardware"""
 
     @abstractmethod
@@ -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_datakey(self, source: str) -> DataKey:
         """Metadata like source, dtype, shape, precision, units"""
 
     @abstractmethod
@@ -35,6 +38,10 @@ class SignalBackend(Generic[T]):
     async def get_value(self) -> T:
         """The current value"""
 
+    @abstractmethod
+    async def get_setpoint(self) -> T:
+        """The point that a signal was requested to move to."""
+
     @abstractmethod
     def set_callback(self, callback: Optional[ReadingValueCallback[T]]) -> None:
         """Observe changes to the current value, timestamp and severity"""

ophyd_async/core/{_device/_backend/sim_signal_backend.py → soft_signal_backend.py}

@@ -1,18 +1,17 @@
 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
+from typing import Dict, Generic, Optional, Type, Union, cast, get_origin
 
-from bluesky.protocols import Descriptor, Dtype, Reading
+import numpy as np
+from bluesky.protocols import DataKey, Dtype, Reading
 
-from ...utils import ReadingValueCallback, T, get_dtype
 from .signal_backend import SignalBackend
+from .utils import DEFAULT_TIMEOUT, ReadingValueCallback, T, get_dtype
 
 primitive_dtypes: Dict[type, Dtype] = {
     str: "string",
@@ -22,7 +21,7 @@ primitive_dtypes: Dict[type, Dtype] = {
 }
 
 
-class SimConverter(Generic[T]):
+class SoftConverter(Generic[T]):
     def value(self, value: T) -> T:
         return value
 
@@ -36,12 +35,17 @@ class SimConverter(Generic[T]):
             alarm_severity=-1 if severity > 2 else severity,
         )
 
-    def descriptor(self, source: str, value) -> Descriptor:
+    def get_datakey(self, source: str, value) -> DataKey:
+        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:
@@ -50,9 +54,9 @@ class SimConverter(Generic[T]):
         return datatype()
 
 
-class SimArrayConverter(SimConverter):
-    def descriptor(self, source: str, value) -> Descriptor:
-        return dict(source=source, dtype="array", shape=[len(value)])
+class SoftArrayConverter(SoftConverter):
+    def get_datakey(self, source: str, value) -> DataKey:
+        return {"source": source, "dtype": "array", "shape": [len(value)]}
 
     def make_initial_value(self, datatype: Optional[Type[T]]) -> T:
         if datatype is None:
@@ -65,7 +69,7 @@ class SimArrayConverter(SimConverter):
 
 
 @dataclass
-class SimEnumConverter(SimConverter):
+class SoftEnumConverter(SoftConverter):
     enum_class: Type[Enum]
 
     def write_value(self, value: Union[Enum, str]) -> Enum:
@@ -74,11 +78,9 @@ class SimEnumConverter(SimConverter):
         else:
             return self.enum_class(value)
 
-    def descriptor(self, source: str, value) -> Descriptor:
+    def get_datakey(self, source: str, value) -> DataKey:
         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:
@@ -87,48 +89,50 @@ class SimEnumConverter(SimConverter):
         return cast(T, list(datatype.__members__.values())[0])  # type: ignore
 
 
-class DisconnectedSimConverter(SimConverter):
-    def __getattribute__(self, __name: str) -> Any:
-        raise NotImplementedError("No PV has been set as connect() has not been called")
-
-
 def make_converter(datatype):
     is_array = get_dtype(datatype) is not None
     is_sequence = get_origin(datatype) == abc.Sequence
     is_enum = issubclass(datatype, Enum) if inspect.isclass(datatype) else False
 
     if is_array or is_sequence:
-        return SimArrayConverter()
+        return SoftArrayConverter()
     if is_enum:
-        return SimEnumConverter(datatype)
+        return SoftEnumConverter(datatype)
 
-    return SimConverter()
+    return SoftConverter()
 
 
-class SimSignalBackend(SignalBackend[T]):
-    """An simulated backend to a Signal, created with ``Signal.connect(sim=True)``"""
+class SoftSignalBackend(SignalBackend[T]):
+    """An backend to a soft Signal, for test signals see ``MockSignalBackend``."""
 
     _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.put_proceeds = asyncio.Event()
-        self.put_proceeds.set()
-        self.callback: Optional[ReadingValueCallback[T]] = None
+        self._initial_value = initial_value
+        self.converter: SoftConverter = make_converter(datatype)
+        if self._initial_value is None:
+            self._initial_value = self.converter.make_initial_value(self.datatype)
+        else:
+            self._initial_value = self.converter.write_value(self._initial_value)
 
-    async def connect(self) -> None:
-        self.converter = make_converter(self.datatype)
-        self._initial_value = self.converter.make_initial_value(self.datatype)
+        self.callback: Optional[ReadingValueCallback[T]] = None
         self._severity = 0
+        self.set_value(self._initial_value)
+
+    def source(self, name: str) -> str:
+        return f"soft://{name}"
 
-        await self.put(None)
+    async def connect(self, timeout: float = DEFAULT_TIMEOUT) -> None:
+        """Connection isn't required for soft signals."""
+        pass
 
     async def put(self, value: Optional[T], wait=True, timeout=None):
         write_value = (
@@ -136,13 +140,11 @@ class SimSignalBackend(SignalBackend[T]):
             if value is not None
             else self._initial_value
         )
-        self._set_value(write_value)
 
-        if wait:
-            await asyncio.wait_for(self.put_proceeds.wait(), timeout)
+        self.set_value(write_value)
 
-    def _set_value(self, value: T):
-        """Method to bypass asynchronous logic, designed to only be used in tests."""
+    def set_value(self, value: T):
+        """Method to bypass asynchronous logic."""
         self._value = value
         self._timestamp = time.monotonic()
         reading: Reading = self.converter.reading(
@@ -152,8 +154,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_datakey(self, source: str) -> DataKey:
+        return self.converter.get_datakey(source, self._value)
 
     async def get_reading(self) -> Reading:
         return self.converter.reading(self._value, self._timestamp, self._severity)
@@ -161,6 +163,10 @@ class SimSignalBackend(SignalBackend[T]):
     async def get_value(self) -> T:
         return self.converter.value(self._value)
 
+    async def get_setpoint(self) -> T:
+        """For a soft signal, the setpoint and readback values are the same."""
+        return await self.get_value()
+
     def set_callback(self, callback: Optional[ReadingValueCallback[T]]) -> None:
         if callback:
             assert not self.callback, "Cannot set a callback when one is already set"