ophyd-async 0.10.1__py3-none-any.whl → 0.11__py3-none-any.whl

ophyd_async/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.10.1'
-__version_tuple__ = version_tuple = (0, 10, 1)
+__version__ = version = '0.11'
+__version_tuple__ = version_tuple = (0, 11)

ophyd_async/core/__init__.py

@@ -16,7 +16,7 @@ from ._detector import (
 )
 from ._device import Device, DeviceConnector, DeviceVector, init_devices
 from ._device_filler import DeviceFiller
-from ._flyer import FlyerController, StandardFlyer
+from ._flyer import FlyerController, FlyMotorInfo, StandardFlyer
 from ._hdf_dataset import HDFDatasetDescription, HDFDocumentComposer
 from ._log import config_ophyd_async_logging
 from ._mock_signal_backend import MockSignalBackend
@@ -56,11 +56,14 @@ from ._signal import (
     soft_signal_rw,
     wait_for_value,
     walk_config_signals,
+    walk_devices,
     walk_rw_signals,
+    walk_signal_sources,
 )
 from ._signal_backend import (
     Array1D,
     DTypeScalar_co,
+    Primitive,
     SignalBackend,
     SignalDatatype,
     SignalDatatypeT,
@@ -75,6 +78,7 @@ from ._utils import (
     DEFAULT_TIMEOUT,
     CalculatableTimeout,
     Callback,
+    ConfinedModel,
     EnumTypes,
     LazyMock,
     NotConnected,
@@ -83,6 +87,7 @@ from ._utils import (
     SubsetEnum,
     SupersetEnum,
     WatcherUpdate,
+    error_if_none,
     gather_dict,
     get_dtype,
     get_enum_cls,
@@ -128,6 +133,7 @@ __all__ = [
     "EnumTypes",
     "Table",
     "SignalMetadata",
+    "Primitive",
     # Soft signal
     "SoftSignalBackend",
     "soft_signal_r_and_setter",
@@ -143,6 +149,8 @@ __all__ = [
     "set_and_wait_for_other_value",
     "walk_rw_signals",
     "walk_config_signals",
+    "walk_devices",
+    "walk_signal_sources",
     # Readable
     "StandardReadable",
     "StandardReadableFormat",
@@ -168,6 +176,7 @@ __all__ = [
     "HDFDocumentComposer",
     # Flyer
     "StandardFlyer",
+    "FlyMotorInfo",
     "FlyerController",
     # Settings
     "Settings",
@@ -179,8 +188,10 @@ __all__ = [
     "CalculatableTimeout",
     "DEFAULT_TIMEOUT",
     "Callback",
+    "ConfinedModel",
     "NotConnected",
     "Reference",
+    "error_if_none",
     "gather_dict",
     "get_dtype",
     "get_enum_cls",

ophyd_async/core/_derived_signal.py

@@ -11,7 +11,7 @@ from ._derived_signal_backend import (
 )
 from ._device import Device
 from ._signal import Signal, SignalR, SignalRW, SignalT, SignalW
-from ._signal_backend import SignalDatatypeT
+from ._signal_backend import Primitive, SignalDatatypeT
 
 
 class DerivedSignalFactory(Generic[TransformT]):
@@ -23,18 +23,31 @@ class DerivedSignalFactory(Generic[TransformT]):
     :param set_derived:
         An optional async function that takes the output of
         `transform_cls.raw_to_derived` and applies it to the raw devices.
-    :param raw_and_transform_devices:
-        Devices whose values will be passed as parameters to the `transform_cls`,
-        and as arguments to `transform_cls.raw_to_derived`.
+    :param raw_and_transform_devices_and_constants:
+        Devices and Constants whose values will be passed as parameters
+        to the `transform_cls`, and as arguments to `transform_cls.raw_to_derived`.
     """
 
     def __init__(
         self,
         transform_cls: type[TransformT],
         set_derived: Callable[..., Awaitable[None]] | None = None,
-        **raw_and_transform_devices,
+        **raw_and_transform_devices_and_constants,
     ):
         self._set_derived = set_derived
+        _raw_and_transform_devices, _raw_and_transform_constants = (
+            {
+                k: v
+                for k, v in raw_and_transform_devices_and_constants.items()
+                if isinstance(v, Device)
+            },
+            {
+                k: v
+                for k, v in raw_and_transform_devices_and_constants.items()
+                if isinstance(v, Primitive)
+            },
+        )
+
         # Check the raw and transform devices match the input arguments of the Transform
         if transform_cls is not Transform:
             # Populate expected parameters and types
@@ -48,26 +61,42 @@ class DerivedSignalFactory(Generic[TransformT]):
             }
 
             # Populate received parameters and types
-            # Use Signal datatype, or Locatable datatype, or set type as None
+            # Use Primitive's type, Signal's datatype,
+            # Locatable's datatype, or set type as None
             received = {
-                k: v.datatype if isinstance(v, Signal) else get_locatable_type(v)
-                for k, v in raw_and_transform_devices.items()
+                **{
+                    k: v.datatype if isinstance(v, Signal) else get_locatable_type(v)
+                    for k, v in _raw_and_transform_devices.items()
+                },
+                **{k: type(v) for k, v in _raw_and_transform_constants.items()},
             }
 
             if expected != received:
                 msg = (
-                    f"Expected devices to be passed as keyword arguments "
+                    f"Expected the following to be passed as keyword arguments "
                     f"{expected}, got {received}"
                 )
                 raise TypeError(msg)
         self._set_derived_takes_dict = (
             is_typeddict(_get_first_arg_datatype(set_derived)) if set_derived else False
         )
+
+        _raw_constants, _transform_constants = _partition_by_keys(
+            _raw_and_transform_constants, set(transform_cls.model_fields)
+        )
+
+        _raw_devices, _transform_devices = _partition_by_keys(
+            _raw_and_transform_devices, set(transform_cls.model_fields)
+        )
+
         self._transformer = SignalTransformer(
             transform_cls,
             set_derived,
             self._set_derived_takes_dict,
-            **raw_and_transform_devices,
+            _raw_devices,
+            _raw_constants,
+            _transform_devices,
+            _transform_constants,
         )
 
     def _make_signal(
@@ -177,7 +206,7 @@ def _get_first_arg_datatype(
 def _make_factory(
     raw_to_derived: Callable[..., SignalDatatypeT] | None = None,
     set_derived: Callable[[SignalDatatypeT], Awaitable[None]] | None = None,
-    raw_devices: dict[str, Device] | None = None,
+    raw_devices_and_constants: dict[str, Device | Primitive] | None = None,
 ) -> DerivedSignalFactory:
     if raw_to_derived:
 
@@ -190,7 +219,9 @@ def _make_factory(
         DerivedTransform.raw_to_derived.__annotations__ = get_type_hints(raw_to_derived)
 
         return DerivedSignalFactory(
-            DerivedTransform, set_derived=set_derived, **(raw_devices or {})
+            DerivedTransform,
+            set_derived=set_derived,
+            **(raw_devices_and_constants or {}),
         )
     else:
         return DerivedSignalFactory(Transform, set_derived=set_derived)
@@ -200,7 +231,7 @@ def derived_signal_r(
     raw_to_derived: Callable[..., SignalDatatypeT],
     derived_units: str | None = None,
     derived_precision: int | None = None,
-    **raw_devices: Device,
+    **raw_devices_and_constants: Device | Primitive,
 ) -> SignalR[SignalDatatypeT]:
     """Create a read only derived signal.
 
@@ -209,11 +240,14 @@ def derived_signal_r(
         returns the derived value.
     :param derived_units: Engineering units for the derived signal
     :param derived_precision: Number of digits after the decimal place to display
-    :param raw_devices:
-        A dictionary of Devices to provide the values for raw_to_derived. The names
-        of these arguments must match the arguments of raw_to_derived.
+    :param raw_devices_and_constants:
+        A dictionary of Devices and Constants to provide the values for raw_to_derived.
+        The names of these arguments must match the arguments of raw_to_derived.
     """
-    factory = _make_factory(raw_to_derived=raw_to_derived, raw_devices=raw_devices)
+    factory = _make_factory(
+        raw_to_derived=raw_to_derived,
+        raw_devices_and_constants=raw_devices_and_constants,
+    )
     return factory.derived_signal_r(
         datatype=_get_return_datatype(raw_to_derived),
         name="value",
@@ -227,7 +261,7 @@ def derived_signal_rw(
     set_derived: Callable[[SignalDatatypeT], Awaitable[None]],
     derived_units: str | None = None,
     derived_precision: int | None = None,
-    **raw_devices: Device,
+    **raw_devices_and_constants: Device | Primitive,
 ) -> SignalRW[SignalDatatypeT]:
     """Create a read-write derived signal.
 
@@ -239,9 +273,9 @@ def derived_signal_rw(
         either be an async function, or return an [](#AsyncStatus)
     :param derived_units: Engineering units for the derived signal
     :param derived_precision: Number of digits after the decimal place to display
-    :param raw_devices:
-        A dictionary of Devices to provide the values for raw_to_derived. The names
-        of these arguments must match the arguments of raw_to_derived.
+    :param raw_devices_and_constants:
+        A dictionary of Devices and Constants to provide the values for raw_to_derived.
+        The names of these arguments must match the arguments of raw_to_derived.
     """
     raw_to_derived_datatype = _get_return_datatype(raw_to_derived)
     set_derived_datatype = _get_first_arg_datatype(set_derived)
@@ -253,7 +287,9 @@ def derived_signal_rw(
         raise TypeError(msg)
 
     factory = _make_factory(
-        raw_to_derived=raw_to_derived, set_derived=set_derived, raw_devices=raw_devices
+        raw_to_derived=raw_to_derived,
+        set_derived=set_derived,
+        raw_devices_and_constants=raw_devices_and_constants,
     )
     return factory.derived_signal_rw(
         datatype=raw_to_derived_datatype,
@@ -297,3 +333,13 @@ def get_locatable_type(obj: object) -> type | None:
             if args:
                 return args[0]
     return None
+
+
+def _partition_by_keys(data: dict, keys: set) -> tuple[dict, dict]:
+    group_excluded, group_included = {}, {}
+    for k, v in data.items():
+        if k in keys:
+            group_included[k] = v
+        else:
+            group_excluded[k] = v
+    return group_excluded, group_included

ophyd_async/core/_derived_signal_backend.py

@@ -7,17 +7,23 @@ from typing import TYPE_CHECKING, Any, Generic, TypeVar
 
 from bluesky.protocols import Location, Reading, Subscribable
 from event_model import DataKey
-from pydantic import BaseModel
 
 from ._protocol import AsyncLocatable, AsyncReadable
 from ._signal_backend import SignalBackend, SignalDatatypeT, make_datakey, make_metadata
-from ._utils import Callback, T, gather_dict, merge_gathered_dicts
+from ._utils import (
+    Callback,
+    ConfinedModel,
+    T,
+    error_if_none,
+    gather_dict,
+    merge_gathered_dicts,
+)
 
 RawT = TypeVar("RawT")
 DerivedT = TypeVar("DerivedT")
 
 
-class Transform(BaseModel, Generic[RawT, DerivedT]):
+class Transform(ConfinedModel, Generic[RawT, DerivedT]):
     """Baseclass for bidirectional transforms for Derived Signals.
 
     Subclass and add:
@@ -77,15 +83,20 @@ class SignalTransformer(Generic[TransformT]):
         transform_cls: type[TransformT],
         set_derived: Callable[..., Awaitable[None]] | None,
         set_derived_takes_dict: bool,
-        **raw_and_transform_devices,
+        raw_devices,
+        raw_constants,
+        transform_devices,
+        transform_constants,
     ):
         self._transform_cls = transform_cls
         self._set_derived = set_derived
         self._set_derived_takes_dict = set_derived_takes_dict
-        self._transform_devices = {
-            k: raw_and_transform_devices.pop(k) for k in transform_cls.model_fields
-        }
-        self._raw_devices = raw_and_transform_devices
+
+        self._transform_devices = transform_devices
+        self._transform_constants = transform_constants
+        self._raw_devices = raw_devices
+        self._raw_constants = raw_constants
+
         self._derived_callbacks: dict[str, Callback[Reading]] = {}
         self._cached_readings: dict[str, Reading] | None = None
 
@@ -124,7 +135,7 @@ class SignalTransformer(Generic[TransformT]):
             k: transform_readings[sig.name]["value"]
             for k, sig in self.transform_readables.items()
         }
-        return self._transform_cls(**transform_args)
+        return self._transform_cls(**(transform_args | self._transform_constants))
 
     def _make_derived_readings(
         self, raw_and_transform_readings: dict[str, Reading]
@@ -142,10 +153,15 @@ class SignalTransformer(Generic[TransformT]):
         transform = self._make_transform_from_readings(raw_and_transform_readings)
         # Create the raw values from the rest then calculate the derived readings
         # using the transform
+        # Extend dictionary with values of any Constants passed as arguments
         raw_values = {
-            k: raw_and_transform_readings[sig.name]["value"]
-            for k, sig in self._raw_devices.items()
+            **{
+                k: raw_and_transform_readings[sig.name]["value"]
+                for k, sig in self._raw_devices.items()
+            },
+            **self._raw_constants,
         }
+
         derived_readings = {
             name: Reading(
                 value=derived, timestamp=timestamp, alarm_severity=alarm_severity
@@ -175,13 +191,15 @@ class SignalTransformer(Generic[TransformT]):
         return {k: v["value"] for k, v in derived_readings.items()}
 
     def _update_cached_reading(self, value: dict[str, Reading]):
-        if self._cached_readings is None:
-            msg = "Cannot update cached reading as it has not been initialised"
-            raise RuntimeError(msg)
-        self._cached_readings.update(value)
+        _cached_readings = error_if_none(
+            self._cached_readings,
+            "Cannot update cached reading as it has not been initialised",
+        )
+
+        _cached_readings.update(value)
         if self._complete_cached_reading():
             # We've got a complete set of values, callback on them
-            derived_readings = self._make_derived_readings(self._cached_readings)
+            derived_readings = self._make_derived_readings(_cached_readings)
             for name, callback in self._derived_callbacks.items():
                 callback(derived_readings[name])
 
@@ -228,18 +246,19 @@ class SignalTransformer(Generic[TransformT]):
         }
 
     async def set_derived(self, name: str, value: Any):
-        if self._set_derived is None:
-            msg = "Cannot put as no set_derived method given"
-            raise RuntimeError(msg)
+        _set_derived = error_if_none(
+            self._set_derived,
+            "Cannot put as no set_derived method given",
+        )
         if self._set_derived_takes_dict:
             # Need to get the other derived values and update the one that's changing
             derived = await self.get_locations()
             setpoints = {k: v["setpoint"] for k, v in derived.items()}
             setpoints[name] = value
-            await self._set_derived(setpoints)
+            await _set_derived(setpoints)
         else:
             # Only one derived signal, so pass it directly
-            await self._set_derived(value)
+            await _set_derived(value)
 
 
 class DerivedSignalBackend(SignalBackend[SignalDatatypeT]):
@@ -275,9 +294,12 @@ class DerivedSignalBackend(SignalBackend[SignalDatatypeT]):
         if wait is False:
             msg = "Cannot put with wait=False"
             raise RuntimeError(msg)
-        if value is None:
-            msg = "Must be given a value to put"
-            raise RuntimeError(msg)
+
+        value = error_if_none(
+            value,
+            "Must be given a value to put",
+        )
+
         await self.transformer.set_derived(self.name, value)
 
     async def get_datakey(self, source: str) -> DataKey:

ophyd_async/core/_detector.py

@@ -23,13 +23,13 @@ from bluesky.protocols import (
     WritesStreamAssets,
 )
 from event_model import DataKey
-from pydantic import BaseModel, Field, NonNegativeInt, PositiveInt, computed_field
+from pydantic import Field, NonNegativeInt, PositiveInt, computed_field
 
 from ._device import Device, DeviceConnector
 from ._protocol import AsyncConfigurable, AsyncReadable
 from ._signal import SignalR
 from ._status import AsyncStatus, WatchableAsyncStatus
-from ._utils import DEFAULT_TIMEOUT, WatcherUpdate, merge_gathered_dicts
+from ._utils import DEFAULT_TIMEOUT, ConfinedModel, WatcherUpdate, merge_gathered_dicts
 
 
 class DetectorTrigger(Enum):
@@ -48,7 +48,7 @@ class DetectorTrigger(Enum):
     """Expect a series of variable width external gate signals"""
 
 
-class TriggerInfo(BaseModel):
+class TriggerInfo(ConfinedModel):
     """Minimal set of information required to setup triggering on a detector."""
 
     number_of_events: NonNegativeInt | list[NonNegativeInt] = Field(default=1)

ophyd_async/core/_device.py

@@ -10,7 +10,13 @@ from typing import Any, TypeVar
 from bluesky.protocols import HasName
 from bluesky.run_engine import call_in_bluesky_event_loop, in_bluesky_event_loop
 
-from ._utils import DEFAULT_TIMEOUT, LazyMock, NotConnected, wait_for_connection
+from ._utils import (
+    DEFAULT_TIMEOUT,
+    LazyMock,
+    NotConnected,
+    error_if_none,
+    wait_for_connection,
+)
 
 
 class DeviceConnector:
@@ -148,6 +154,10 @@ class Device(HasName):
         elif name not in _not_device_attrs and isinstance(value, Device):
             value.parent = self
             self._child_devices[name] = value
+            # And if the name is set, then set the name of all children,
+            # including the child
+            if self._name:
+                self.set_name(self._name)
         # ...and avoiding the super call as we know it resolves to `object`
         return object.__setattr__(self, name, value)
 
@@ -171,12 +181,11 @@ class Device(HasName):
         :param force_reconnect:
             If True, force a reconnect even if the last connect succeeded.
         """
-        if not hasattr(self, "_connector"):
-            msg = (
-                f"{self}: doesn't have attribute `_connector`,"
-                " did you call `super().__init__` in your `__init__` method?"
-            )
-            raise RuntimeError(msg)
+        connector = error_if_none(
+            getattr(self, "_connector", None),
+            f"{self}: doesn't have attribute `_connector`,"
+            f" did you call `super().__init__` in your `__init__` method?",
+        )
         if mock:
             # Always connect in mock mode serially
             if isinstance(mock, LazyMock):
@@ -185,7 +194,7 @@ class Device(HasName):
             elif not self._mock:
                 # Make one
                 self._mock = LazyMock()
-            await self._connector.connect_mock(self, self._mock)
+            await connector.connect_mock(self, self._mock)
         else:
             # Try to cache the connect in real mode
             can_use_previous_connect = (
@@ -195,13 +204,13 @@ class Device(HasName):
             )
             if force_reconnect or not can_use_previous_connect:
                 self._mock = None
-                coro = self._connector.connect_real(self, timeout, force_reconnect)
+                coro = connector.connect_real(self, timeout, force_reconnect)
                 self._connect_task = asyncio.create_task(coro)
-            if not self._connect_task:
-                msg = "Connect task not created, this shouldn't happen"
-                raise RuntimeError(msg)
+            connect_task = error_if_none(
+                self._connect_task, "Connect task not created, this shouldn't happen"
+            )
             # Wait for it to complete
-            await self._connect_task
+            await connect_task
 
 
 _not_device_attrs = {
@@ -289,9 +298,8 @@ class DeviceProcessor:
             raise ValueError
         except ValueError:
             _, _, tb = sys.exc_info()
-            if not tb:
-                msg = "Can't get traceback, this shouldn't happen"
-                raise RuntimeError(msg)  # noqa: B904
+            tb = error_if_none(tb, "Can't get traceback, this shouldn't happen")
+
             caller_frame = tb.tb_frame
             while caller_frame.f_locals.get("self", None) is self:
                 caller_frame = caller_frame.f_back

ophyd_async/core/_flyer.py

@@ -2,10 +2,11 @@ from abc import ABC, abstractmethod
 from typing import Any, Generic
 
 from bluesky.protocols import Flyable, Preparable, Stageable
+from pydantic import Field
 
 from ._device import Device
 from ._status import AsyncStatus
-from ._utils import T
+from ._utils import CALCULATE_TIMEOUT, CalculatableTimeout, ConfinedModel, T
 
 
 class FlyerController(ABC, Generic[T]):
@@ -31,6 +32,39 @@ class FlyerController(ABC, Generic[T]):
         """Stop flying and wait everything to be stopped."""
 
 
+class FlyMotorInfo(ConfinedModel):
+    """Minimal set of information required to fly a motor."""
+
+    start_position: float = Field(frozen=True)
+    """Absolute position of the motor once it finishes accelerating to desired
+    velocity, in motor EGUs"""
+
+    end_position: float = Field(frozen=True)
+    """Absolute position of the motor once it begins decelerating from desired
+    velocity, in EGUs"""
+
+    time_for_move: float = Field(frozen=True, gt=0)
+    """Time taken for the motor to get from start_position to end_position, excluding
+    run-up and run-down, in seconds."""
+
+    timeout: CalculatableTimeout = Field(frozen=True, default=CALCULATE_TIMEOUT)
+    """Maximum time for the complete motor move, including run up and run down.
+    Defaults to `time_for_move` + run up and run down times + 10s."""
+
+    @property
+    def velocity(self) -> float:
+        """Calculate the velocity of the constant velocity phase."""
+        return (self.end_position - self.start_position) / self.time_for_move
+
+    def ramp_up_start_pos(self, acceleration_time: float) -> float:
+        """Calculate the start position with run-up distance added on."""
+        return self.start_position - acceleration_time * self.velocity / 2
+
+    def ramp_down_end_pos(self, acceleration_time: float) -> float:
+        """Calculate the end position with run-down distance added on."""
+        return self.end_position + acceleration_time * self.velocity / 2
+
+
 class StandardFlyer(
     Device,
     Stageable,

ophyd_async/core/_hdf_dataset.py

@@ -2,17 +2,18 @@ from collections.abc import Iterator
 from pathlib import Path
 from urllib.parse import urlunparse
 
+from bluesky.protocols import StreamAsset
 from event_model import (  # type: ignore
     ComposeStreamResource,
     ComposeStreamResourceBundle,
-    StreamDatum,
     StreamRange,
-    StreamResource,
 )
-from pydantic import BaseModel, Field
+from pydantic import Field
 
+from ._utils import ConfinedModel
 
-class HDFDatasetDescription(BaseModel):
+
+class HDFDatasetDescription(ConfinedModel):
     """A description of the type and shape of a dataset in an HDF file."""
 
     data_key: str
@@ -79,12 +80,12 @@ class HDFDocumentComposer:
             for ds in datasets
         ]
 
-    def stream_resources(self) -> Iterator[StreamResource]:
-        for bundle in self._bundles:
-            yield bundle.stream_resource_doc
+    def make_stream_docs(self, indices_written: int) -> Iterator[StreamAsset]:
+        # TODO: fail if we get dropped frames
+        if indices_written and not self._last_emitted:
+            for bundle in self._bundles:
+                yield "stream_resource", bundle.stream_resource_doc
 
-    def stream_data(self, indices_written: int) -> Iterator[StreamDatum]:
-        # Indices are relative to resource
         if indices_written > self._last_emitted:
             indices: StreamRange = {
                 "start": self._last_emitted,
@@ -92,4 +93,4 @@ class HDFDocumentComposer:
             }
             self._last_emitted = indices_written
             for bundle in self._bundles:
-                yield bundle.compose_stream_datum(indices)
+                yield "stream_datum", bundle.compose_stream_datum(indices)