ophyd-async 0.3.1a1__py3-none-any.whl → 0.3.3__py3-none-any.whl

ophyd_async/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.3.1a1'
-__version_tuple__ = version_tuple = (0, 3, 1)
+__version__ = version = '0.3.3'
+__version_tuple__ = version_tuple = (0, 3, 3)

ophyd_async/core/__init__.py

@@ -50,7 +50,7 @@ from .signal import (
     soft_signal_rw,
     wait_for_value,
 )
-from .signal_backend import SignalBackend
+from .signal_backend import RuntimeSubsetEnum, SignalBackend, SubsetEnum
 from .soft_signal_backend import SoftSignalBackend
 from .standard_readable import ConfigSignal, HintedSignal, StandardReadable
 from .utils import (
@@ -68,66 +68,69 @@ from .utils import (
 )
 
 __all__ = [
-    "get_mock_put",
-    "callback_on_mock_put",
-    "mock_puts_blocked",
-    "set_mock_values",
-    "reset_mock_put_calls",
-    "SignalBackend",
-    "SoftSignalBackend",
+    "AsyncStatus",
+    "CalculatableTimeout",
+    "CalculateTimeout",
+    "Callback",
+    "ConfigSignal",
+    "DEFAULT_TIMEOUT",
     "DetectorControl",
-    "MockSignalBackend",
     "DetectorTrigger",
     "DetectorWriter",
-    "StandardDetector",
     "Device",
     "DeviceCollector",
     "DeviceVector",
-    "Signal",
-    "SignalR",
-    "SignalW",
-    "SignalRW",
-    "SignalX",
-    "soft_signal_r_and_setter",
-    "soft_signal_rw",
-    "observe_value",
-    "set_and_wait_for_value",
-    "set_mock_put_proceeds",
-    "set_mock_value",
-    "wait_for_value",
-    "AsyncStatus",
-    "WatchableAsyncStatus",
     "DirectoryInfo",
     "DirectoryProvider",
+    "HardwareTriggeredFlyable",
+    "HintedSignal",
+    "MockSignalBackend",
     "NameProvider",
+    "NotConnected",
+    "ReadingValueCallback",
+    "RuntimeSubsetEnum",
+    "SubsetEnum",
     "ShapeProvider",
-    "StaticDirectoryProvider",
+    "Signal",
+    "SignalBackend",
+    "SignalR",
+    "SignalRW",
+    "SignalW",
+    "SignalX",
+    "SoftSignalBackend",
+    "StandardDetector",
     "StandardReadable",
-    "ConfigSignal",
-    "HintedSignal",
+    "StaticDirectoryProvider",
+    "T",
     "TriggerInfo",
     "TriggerLogic",
-    "HardwareTriggeredFlyable",
-    "CalculateTimeout",
-    "CalculatableTimeout",
-    "DEFAULT_TIMEOUT",
-    "Callback",
-    "NotConnected",
-    "ReadingValueCallback",
-    "T",
+    "WatchableAsyncStatus",
+    "assert_configuration",
+    "assert_emitted",
+    "assert_mock_put_called_with",
+    "assert_reading",
+    "assert_value",
+    "callback_on_mock_put",
     "get_dtype",
-    "get_unique",
-    "merge_gathered_dicts",
-    "wait_for_connection",
+    "get_mock_put",
     "get_signal_values",
+    "get_unique",
+    "load_device",
     "load_from_yaml",
+    "merge_gathered_dicts",
+    "mock_puts_blocked",
+    "observe_value",
+    "reset_mock_put_calls",
+    "save_device",
     "save_to_yaml",
+    "set_and_wait_for_value",
+    "set_mock_put_proceeds",
+    "set_mock_value",
+    "set_mock_values",
     "set_signal_values",
+    "soft_signal_r_and_setter",
+    "soft_signal_rw",
+    "wait_for_connection",
+    "wait_for_value",
     "walk_rw_signals",
-    "load_device",
-    "save_device",
-    "assert_reading",
-    "assert_value",
-    "assert_configuration",
-    "assert_emitted",
 ]

ophyd_async/core/device_save_loader.py

@@ -1,6 +1,5 @@
 from enum import Enum
-from functools import partial
-from typing import Any, Callable, Dict, Generator, List, Optional, Sequence, Union
+from typing import Any, Callable, Dict, Generator, List, Optional, Sequence
 
 import numpy as np
 import numpy.typing as npt
@@ -8,13 +7,10 @@ import yaml
 from bluesky.plan_stubs import abs_set, wait
 from bluesky.protocols import Location
 from bluesky.utils import Msg
-from epicscorelibs.ca.dbr import ca_array, ca_float, ca_int, ca_str
 
 from .device import Device
 from .signal import SignalRW
 
-CaType = Union[ca_float, ca_int, ca_str, ca_array]
-
 
 def ndarray_representer(dumper: yaml.Dumper, array: npt.NDArray[Any]) -> yaml.Node:
     return dumper.represent_sequence(
@@ -22,19 +18,6 @@ def ndarray_representer(dumper: yaml.Dumper, array: npt.NDArray[Any]) -> yaml.No
     )
 
 
-def ca_dbr_representer(dumper: yaml.Dumper, value: CaType) -> yaml.Node:
-    # if it's an array, just call ndarray_representer...
-    represent_array = partial(ndarray_representer, dumper)
-
-    representers: Dict[CaType, Callable[[CaType], yaml.Node]] = {
-        ca_float: dumper.represent_float,
-        ca_int: dumper.represent_int,
-        ca_str: dumper.represent_str,
-        ca_array: represent_array,
-    }
-    return representers[type(value)](value)
-
-
 class OphydDumper(yaml.Dumper):
     def represent_data(self, data: Any) -> Any:
         if isinstance(data, Enum):
@@ -152,11 +135,6 @@ def save_to_yaml(phases: Sequence[Dict[str, Any]], save_path: str) -> None:
 
     yaml.add_representer(np.ndarray, ndarray_representer, Dumper=yaml.Dumper)
 
-    yaml.add_representer(ca_float, ca_dbr_representer, Dumper=yaml.Dumper)
-    yaml.add_representer(ca_int, ca_dbr_representer, Dumper=yaml.Dumper)
-    yaml.add_representer(ca_str, ca_dbr_representer, Dumper=yaml.Dumper)
-    yaml.add_representer(ca_array, ca_dbr_representer, Dumper=yaml.Dumper)
-
     with open(save_path, "w") as file:
         yaml.dump(phases, file, Dumper=OphydDumper, default_flow_style=False)
 

ophyd_async/core/signal.py

@@ -31,7 +31,7 @@ from ophyd_async.protocols import AsyncConfigurable, AsyncReadable, AsyncStageab
 from .async_status import AsyncStatus
 from .device import Device
 from .signal_backend import SignalBackend
-from .soft_signal_backend import SoftSignalBackend
+from .soft_signal_backend import SignalMetadata, SoftSignalBackend
 from .utils import DEFAULT_TIMEOUT, CalculatableTimeout, CalculateTimeout, Callback, T
 
 
@@ -57,7 +57,7 @@ class Signal(Device, Generic[T]):
 
     def __init__(
         self,
-        backend: SignalBackend[T],
+        backend: Optional[SignalBackend[T]] = None,
         timeout: Optional[float] = DEFAULT_TIMEOUT,
         name: str = "",
     ) -> None:
@@ -66,13 +66,24 @@ class Signal(Device, Generic[T]):
         super().__init__(name)
 
     async def connect(
-        self, mock=False, timeout=DEFAULT_TIMEOUT, force_reconnect: bool = False
+        self,
+        mock=False,
+        timeout=DEFAULT_TIMEOUT,
+        force_reconnect: bool = False,
+        backend: Optional[SignalBackend[T]] = None,
     ):
+        if backend:
+            if self._initial_backend and backend is not self._initial_backend:
+                raise ValueError(
+                    "Backend at connection different from initialised one."
+                )
+            self._backend = backend
         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,
-            )
+            self._backend = MockSignalBackend(initial_backend=self._backend)
+
+        if self._backend is None:
+            raise RuntimeError("`connect` called on signal without backend")
         self.log.debug(f"Connecting to {self.source}")
         await self._backend.connect(timeout=timeout)
 
@@ -261,9 +272,17 @@ def soft_signal_rw(
     datatype: Optional[Type[T]] = None,
     initial_value: Optional[T] = None,
     name: str = "",
+    units: str | None = None,
+    precision: int | None = None,
 ) -> SignalRW[T]:
-    """Creates a read-writable Signal with a SoftSignalBackend"""
-    signal = SignalRW(SoftSignalBackend(datatype, initial_value), name=name)
+    """Creates a read-writable Signal with a SoftSignalBackend.
+    May pass metadata, which are propagated into describe.
+    """
+    metadata = SignalMetadata(units=units, precision=precision)
+    signal = SignalRW(
+        SoftSignalBackend(datatype, initial_value, metadata=metadata),
+        name=name,
+    )
     return signal
 
 
@@ -271,27 +290,31 @@ def soft_signal_r_and_setter(
     datatype: Optional[Type[T]] = None,
     initial_value: Optional[T] = None,
     name: str = "",
+    units: str | None = None,
+    precision: int | None = None,
 ) -> 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
+    which the signal can be internally modified within the device.
+    May pass metadata, which are propagated into describe.
+    Use soft_signal_rw if you want a device that is externally modifiable
     """
-    backend = SoftSignalBackend(datatype, initial_value)
+    metadata = SignalMetadata(units=units, precision=precision)
+    backend = SoftSignalBackend(datatype, initial_value, metadata=metadata)
     signal = SignalR(backend, name=name)
 
     return (signal, backend.set_value)
 
 
 def _generate_assert_error_msg(
-    name: str, expected_result: str, actuall_result: str
+    name: str, expected_result: str, actual_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}"
+        + f"\n{FAIL}{expected_result}{ENDC}"
+        + f"\nbut actually got \n{FAIL}{actual_result}{ENDC}"
     )
 
 
@@ -313,7 +336,9 @@ async def assert_value(signal: SignalR[T], value: Any) -> None:
     """
     actual_value = await signal.get_value()
     assert actual_value == value, _generate_assert_error_msg(
-        signal.name, value, actual_value
+        name=signal.name,
+        expected_result=value,
+        actual_result=actual_value,
     )
 
 
@@ -338,7 +363,9 @@ async def assert_reading(
     """
     actual_reading = await readable.read()
     assert expected_reading == actual_reading, _generate_assert_error_msg(
-        readable.name, expected_reading, actual_reading
+        name=readable.name,
+        expected_result=expected_reading,
+        actual_result=actual_reading,
     )
 
 
@@ -364,7 +391,9 @@ async def assert_configuration(
     """
     actual_configurable = await configurable.read_configuration()
     assert configuration == actual_configurable, _generate_assert_error_msg(
-        configurable.name, configuration, actual_configurable
+        name=configurable.name,
+        expected_result=configuration,
+        actual_result=actual_configurable,
     )
 
 
@@ -386,11 +415,15 @@ def assert_emitted(docs: Mapping[str, list[dict]], **numbers: int):
         resource=1, datum=1, event=1, stop=1)
     """
     assert list(docs) == list(numbers), _generate_assert_error_msg(
-        "documents", list(numbers), list(docs)
+        name="documents",
+        expected_result=list(numbers),
+        actual_result=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
+        name="emitted",
+        expected_result=numbers,
+        actual_result=actual_numbers,
     )
 
 

ophyd_async/core/signal_backend.py

@@ -1,5 +1,13 @@
 from abc import abstractmethod
-from typing import Generic, Optional, Type
+from typing import (
+    TYPE_CHECKING,
+    ClassVar,
+    Generic,
+    Literal,
+    Optional,
+    Tuple,
+    Type,
+)
 
 from bluesky.protocols import DataKey, Reading
 
@@ -45,3 +53,41 @@ class SignalBackend(Generic[T]):
     @abstractmethod
     def set_callback(self, callback: Optional[ReadingValueCallback[T]]) -> None:
         """Observe changes to the current value, timestamp and severity"""
+
+
+class _RuntimeSubsetEnumMeta(type):
+    def __str__(cls):
+        if hasattr(cls, "choices"):
+            return f"SubsetEnum{list(cls.choices)}"
+        return "SubsetEnum"
+
+    def __getitem__(cls, _choices):
+        if isinstance(_choices, str):
+            _choices = (_choices,)
+        else:
+            if not isinstance(_choices, tuple) or not all(
+                isinstance(c, str) for c in _choices
+            ):
+                raise TypeError(
+                    "Choices must be a str or a tuple of str, " f"not {type(_choices)}."
+                )
+            if len(set(_choices)) != len(_choices):
+                raise TypeError("Duplicate elements in runtime enum choices.")
+
+        class _RuntimeSubsetEnum(cls):
+            choices = _choices
+
+        return _RuntimeSubsetEnum
+
+
+class RuntimeSubsetEnum(metaclass=_RuntimeSubsetEnumMeta):
+    choices: ClassVar[Tuple[str, ...]]
+
+    def __init__(self):
+        raise RuntimeError("SubsetEnum cannot be instantiated")
+
+
+if TYPE_CHECKING:
+    SubsetEnum = Literal
+else:
+    SubsetEnum = RuntimeSubsetEnum

ophyd_async/core/soft_signal_backend.py

@@ -3,14 +3,23 @@ from __future__ import annotations
 import inspect
 import time
 from collections import abc
-from dataclasses import dataclass
 from enum import Enum
-from typing import Dict, Generic, Optional, Type, Union, cast, get_origin
+from typing import (
+    Dict,
+    Generic,
+    Optional,
+    Tuple,
+    Type,
+    TypedDict,
+    Union,
+    cast,
+    get_origin,
+)
 
 import numpy as np
 from bluesky.protocols import DataKey, Dtype, Reading
 
-from .signal_backend import SignalBackend
+from .signal_backend import RuntimeSubsetEnum, SignalBackend
 from .utils import DEFAULT_TIMEOUT, ReadingValueCallback, T, get_dtype
 
 primitive_dtypes: Dict[type, Dtype] = {
@@ -21,6 +30,11 @@ primitive_dtypes: Dict[type, Dtype] = {
 }
 
 
+class SignalMetadata(TypedDict):
+    units: str | None = None
+    precision: int | None = None
+
+
 class SoftConverter(Generic[T]):
     def value(self, value: T) -> T:
         return value
@@ -35,7 +49,8 @@ class SoftConverter(Generic[T]):
             alarm_severity=-1 if severity > 2 else severity,
         )
 
-    def get_datakey(self, source: str, value) -> DataKey:
+    def get_datakey(self, source: str, value, **metadata) -> DataKey:
+        dk = {"source": source, "shape": [], **metadata}
         dtype = type(value)
         if np.issubdtype(dtype, np.integer):
             dtype = int
@@ -44,8 +59,8 @@ class SoftConverter(Generic[T]):
         assert (
             dtype in primitive_dtypes
         ), f"invalid converter for value of type {type(value)}"
-        dtype_name = primitive_dtypes[dtype]
-        return {"source": source, "dtype": dtype_name, "shape": []}
+        dk["dtype"] = primitive_dtypes[dtype]
+        return dk
 
     def make_initial_value(self, datatype: Optional[Type[T]]) -> T:
         if datatype is None:
@@ -55,8 +70,8 @@ class SoftConverter(Generic[T]):
 
 
 class SoftArrayConverter(SoftConverter):
-    def get_datakey(self, source: str, value) -> DataKey:
-        return {"source": source, "dtype": "array", "shape": [len(value)]}
+    def get_datakey(self, source: str, value, **metadata) -> DataKey:
+        return {"source": source, "dtype": "array", "shape": [len(value)], **metadata}
 
     def make_initial_value(self, datatype: Optional[Type[T]]) -> T:
         if datatype is None:
@@ -68,31 +83,45 @@ class SoftArrayConverter(SoftConverter):
         return cast(T, datatype(shape=0))  # type: ignore
 
 
-@dataclass
 class SoftEnumConverter(SoftConverter):
-    enum_class: Type[Enum]
+    choices: Tuple[str, ...]
 
-    def write_value(self, value: Union[Enum, str]) -> Enum:
+    def __init__(self, datatype: Union[RuntimeSubsetEnum, Enum]):
+        if issubclass(datatype, Enum):
+            self.choices = tuple(v.value for v in datatype)
+        else:
+            self.choices = datatype.choices
+
+    def write_value(self, value: Union[Enum, str]) -> str:
         if isinstance(value, Enum):
+            return value.value
+        else:  # Runtime enum
             return value
-        else:
-            return self.enum_class(value)
 
-    def get_datakey(self, source: str, value) -> DataKey:
-        choices = [e.value for e in self.enum_class]
-        return {"source": source, "dtype": "string", "shape": [], "choices": choices}  # type: ignore
+    def get_datakey(self, source: str, value, **metadata) -> DataKey:
+        return {
+            "source": source,
+            "dtype": "string",
+            "shape": [],
+            "choices": self.choices,
+            **metadata,
+        }
 
     def make_initial_value(self, datatype: Optional[Type[T]]) -> T:
         if datatype is None:
             return cast(T, None)
 
-        return cast(T, list(datatype.__members__.values())[0])  # type: ignore
+        if issubclass(datatype, Enum):
+            return cast(T, list(datatype.__members__.values())[0])  # type: ignore
+        return cast(T, self.choices[0])
 
 
 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
+    is_enum = inspect.isclass(datatype) and (
+        issubclass(datatype, Enum) or issubclass(datatype, RuntimeSubsetEnum)
+    )
 
     if is_array or is_sequence:
         return SoftArrayConverter()
@@ -114,9 +143,11 @@ class SoftSignalBackend(SignalBackend[T]):
         self,
         datatype: Optional[Type[T]],
         initial_value: Optional[T] = None,
+        metadata: SignalMetadata = None,
     ) -> None:
         self.datatype = datatype
         self._initial_value = initial_value
+        self._metadata = metadata or {}
         self.converter: SoftConverter = make_converter(datatype)
         if self._initial_value is None:
             self._initial_value = self.converter.make_initial_value(self.datatype)
@@ -155,7 +186,7 @@ class SoftSignalBackend(SignalBackend[T]):
             self.callback(reading, self._value)
 
     async def get_datakey(self, source: str) -> DataKey:
-        return self.converter.get_datakey(source, self._value)
+        return self.converter.get_datakey(source, self._value, **self._metadata)
 
     async def get_reading(self) -> Reading:
         return self.converter.reading(self._value, self._timestamp, self._severity)