ophyd-async 0.9.0a2__py3-none-any.whl → 0.10.0a2__py3-none-any.whl

ophyd_async/__init__.py

@@ -1,12 +1,9 @@
-"""Top level API.
-
-.. data:: __version__
-    :type: str
-
-    Version number as calculated by https://github.com/pypa/setuptools_scm
-"""
+"""Top level API."""
 
 from . import core
-from ._version import __version__
+from ._version import version
+
+__version__ = version
+"""Version number as calculated by https://github.com/pypa/setuptools_scm"""
 
 __all__ = ["__version__", "core"]

ophyd_async/_docs_parser.py

@@ -0,0 +1,12 @@
+import re
+
+from autodoc2.render.myst_ import MystRenderer
+
+DOTTED_MODULE = re.compile(r"((?:[a-zA-Z_][a-zA-Z_0-9]+\.)+)")
+
+
+class ShortenedNamesRenderer(MystRenderer):
+    def format_annotation(self, annotation):
+        if annotation:
+            annotation = DOTTED_MODULE.sub(r"~\1", annotation)
+        return super().format_annotation(annotation)

ophyd_async/_version.py

@@ -1,8 +1,13 @@
-# file generated by setuptools_scm
+# file generated by setuptools-scm
 # don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
 TYPE_CHECKING = False
 if TYPE_CHECKING:
-    from typing import Tuple, Union
+    from typing import Tuple
+    from typing import Union
+
     VERSION_TUPLE = Tuple[Union[int, str], ...]
 else:
     VERSION_TUPLE = object
@@ -12,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.9.0a2'
-__version_tuple__ = version_tuple = (0, 9, 0)
+__version__ = version = '0.10.0a2'
+__version_tuple__ = version_tuple = (0, 10, 0)

ophyd_async/core/__init__.py

@@ -1,6 +1,14 @@
+"""The building blocks for making devices."""
+
+from ._derived_signal import (
+    DerivedSignalFactory,
+    derived_signal_r,
+    derived_signal_rw,
+    derived_signal_w,
+)
+from ._derived_signal_backend import Transform
 from ._detector import (
     DetectorController,
-    DetectorControllerT,
     DetectorTrigger,
     DetectorWriter,
     StandardDetector,
@@ -9,10 +17,10 @@ from ._detector import (
 from ._device import Device, DeviceConnector, DeviceVector, init_devices
 from ._device_filler import DeviceFiller
 from ._flyer import FlyerController, StandardFlyer
-from ._hdf_dataset import HDFDataset, HDFFile
+from ._hdf_dataset import HDFDatasetDescription, HDFDocumentComposer
 from ._log import config_ophyd_async_logging
 from ._mock_signal_backend import MockSignalBackend
-from ._protocol import AsyncConfigurable, AsyncReadable, AsyncStageable
+from ._protocol import AsyncConfigurable, AsyncReadable, AsyncStageable, Watcher
 from ._providers import (
     AutoIncrementFilenameProvider,
     AutoIncrementingPathProvider,
@@ -34,6 +42,7 @@ from ._readable import (
 )
 from ._settings import Settings, SettingsProvider
 from ._signal import (
+    Ignore,
     Signal,
     SignalConnector,
     SignalR,
@@ -47,6 +56,7 @@ from ._signal import (
     soft_signal_r_and_setter,
     soft_signal_rw,
     wait_for_value,
+    walk_config_signals,
     walk_rw_signals,
 )
 from ._signal_backend import (
@@ -55,9 +65,10 @@ from ._signal_backend import (
     SignalBackend,
     SignalDatatype,
     SignalDatatypeT,
+    SignalMetadata,
     make_datakey,
 )
-from ._soft_signal_backend import SignalMetadata, SoftSignalBackend
+from ._soft_signal_backend import SoftSignalBackend
 from ._status import AsyncStatus, WatchableAsyncStatus, completed_status
 from ._table import Table
 from ._utils import (
@@ -70,8 +81,8 @@ from ._utils import (
     Reference,
     StrictEnum,
     SubsetEnum,
-    T,
     WatcherUpdate,
+    gather_dict,
     get_dtype,
     get_enum_cls,
     get_unique,
@@ -81,84 +92,108 @@ from ._utils import (
 from ._yaml_settings import YamlSettingsProvider
 
 __all__ = [
-    "DetectorController",
-    "DetectorControllerT",
-    "DetectorTrigger",
-    "DetectorWriter",
-    "StandardDetector",
-    "TriggerInfo",
+    # Device
     "Device",
     "DeviceConnector",
-    "init_devices",
-    "DeviceVector",
     "DeviceFiller",
-    "StandardFlyer",
-    "FlyerController",
-    "HDFDataset",
-    "HDFFile",
-    "config_ophyd_async_logging",
-    "MockSignalBackend",
-    "AsyncConfigurable",
+    "DeviceVector",
+    "init_devices",
+    # Protocols
     "AsyncReadable",
+    "AsyncConfigurable",
     "AsyncStageable",
-    "AutoIncrementFilenameProvider",
-    "AutoIncrementingPathProvider",
-    "FilenameProvider",
-    "NameProvider",
-    "PathInfo",
-    "PathProvider",
-    "DatasetDescriber",
-    "StaticFilenameProvider",
-    "StaticPathProvider",
-    "UUIDFilenameProvider",
-    "YMDPathProvider",
-    "ConfigSignal",
-    "HintedSignal",
-    "StandardReadable",
-    "StandardReadableFormat",
-    "Settings",
-    "SettingsProvider",
+    "Watcher",
+    # Status
+    "AsyncStatus",
+    "WatchableAsyncStatus",
+    "WatcherUpdate",
+    "completed_status",
+    # Signal
     "Signal",
-    "SignalConnector",
     "SignalR",
-    "SignalRW",
     "SignalW",
+    "SignalRW",
     "SignalX",
-    "observe_value",
-    "observe_signals_value",
-    "set_and_wait_for_value",
-    "set_and_wait_for_other_value",
-    "soft_signal_r_and_setter",
-    "soft_signal_rw",
-    "wait_for_value",
-    "walk_rw_signals",
-    "Array1D",
-    "DTypeScalar_co",
     "SignalBackend",
-    "make_datakey",
-    "StrictEnum",
-    "SubsetEnum",
+    "SignalConnector",
+    # Signal Types
     "SignalDatatype",
     "SignalDatatypeT",
+    "DTypeScalar_co",
+    "Array1D",
+    "StrictEnum",
+    "SubsetEnum",
+    "Table",
     "SignalMetadata",
+    # Soft signal
     "SoftSignalBackend",
-    "AsyncStatus",
-    "WatchableAsyncStatus",
-    "DEFAULT_TIMEOUT",
-    "CalculatableTimeout",
-    "Callback",
+    "soft_signal_r_and_setter",
+    "soft_signal_rw",
+    # Mock signal
     "LazyMock",
+    "MockSignalBackend",
+    # Signal utilities
+    "observe_value",
+    "observe_signals_value",
+    "wait_for_value",
+    "set_and_wait_for_value",
+    "set_and_wait_for_other_value",
+    "walk_rw_signals",
+    "walk_config_signals",
+    # Readable
+    "StandardReadable",
+    "StandardReadableFormat",
+    # Detector
+    "StandardDetector",
+    "TriggerInfo",
+    "DetectorTrigger",
+    "DetectorController",
+    "DetectorWriter",
+    # Path
+    "PathInfo",
+    "PathProvider",
+    "StaticPathProvider",
+    "AutoIncrementingPathProvider",
+    "YMDPathProvider",
+    "FilenameProvider",
+    "StaticFilenameProvider",
+    "AutoIncrementFilenameProvider",
+    "UUIDFilenameProvider",
+    # Datatset
+    "NameProvider",
+    "DatasetDescriber",
+    "HDFDatasetDescription",
+    "HDFDocumentComposer",
+    # Flyer
+    "StandardFlyer",
+    "FlyerController",
+    # Settings
+    "Settings",
+    "SettingsProvider",
+    "YamlSettingsProvider",
+    # Utils
+    "config_ophyd_async_logging",
     "CALCULATE_TIMEOUT",
+    "CalculatableTimeout",
+    "DEFAULT_TIMEOUT",
+    "Callback",
     "NotConnected",
     "Reference",
-    "Table",
-    "T",
-    "WatcherUpdate",
+    "gather_dict",
     "get_dtype",
     "get_enum_cls",
     "get_unique",
     "in_micros",
+    "make_datakey",
     "wait_for_connection",
-    "completed_status",
-    "YamlSettingsProvider",
+    "Ignore",
+    # Derived signal
+    "derived_signal_r",
+    "derived_signal_rw",
+    "derived_signal_w",
+    "Transform",
+    "DerivedSignalFactory",
+    # Back compat - delete before 1.0
+    "ConfigSignal",
+    "HintedSignal",
 ]

ophyd_async/core/_derived_signal.py

@@ -0,0 +1,271 @@
+from collections.abc import Awaitable, Callable
+from typing import Any, Generic, get_type_hints
+
+from ._derived_signal_backend import (
+    DerivedSignalBackend,
+    SignalTransformer,
+    Transform,
+    TransformT,
+)
+from ._device import Device
+from ._signal import SignalR, SignalRW, SignalT, SignalW
+from ._signal_backend import SignalDatatypeT
+
+
+class DerivedSignalFactory(Generic[TransformT]):
+    """A factory that makes Derived Signals using a many-many Transform.
+
+    :param transform_cls:
+        The Transform subclass that will be filled in with parameters in order to
+        transform raw to derived and derived to raw.
+    :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`.
+    """
+
+    def __init__(
+        self,
+        transform_cls: type[TransformT],
+        set_derived: Callable[..., Awaitable[None]] | None = None,
+        **raw_and_transform_devices,
+    ):
+        self._set_derived = set_derived
+        # Check the raw and transform devices match the input arguments of the Transform
+        if transform_cls is not Transform:
+            expected = list(transform_cls.model_fields) + [
+                x
+                for x in get_type_hints(transform_cls.raw_to_derived)
+                if x not in ["self", "return"]
+            ]
+            if set(expected) != set(raw_and_transform_devices):
+                msg = (
+                    f"Expected devices to be passed as keyword arguments {expected}, "
+                    f"got {list(raw_and_transform_devices)}"
+                )
+                raise TypeError(msg)
+        set_derived_datatype = (
+            _get_first_arg_datatype(set_derived) if set_derived else None
+        )
+        self._transformer = SignalTransformer(
+            transform_cls,
+            set_derived,
+            set_derived_datatype,
+            **raw_and_transform_devices,
+        )
+
+    def _make_signal(
+        self,
+        signal_cls: type[SignalT],
+        datatype: type[SignalDatatypeT],
+        name: str,
+        units: str | None = None,
+        precision: int | None = None,
+    ) -> SignalT:
+        # Check up front the raw_devices are of the right type for what the signal_cls
+        # supports
+        if issubclass(signal_cls, SignalR):
+            self._transformer.raw_and_transform_readables  # noqa: B018
+            self._transformer.raw_and_transform_subscribables  # noqa: B018
+        if issubclass(signal_cls, SignalW) and not self._set_derived:
+            msg = (
+                f"Must define a set_derived method to support derived "
+                f"{signal_cls.__name__}s"
+            )
+            raise ValueError(msg)
+        if issubclass(signal_cls, SignalRW):
+            self._transformer.raw_locatables  # noqa: B018
+        backend = DerivedSignalBackend(
+            datatype, name, self._transformer, units, precision
+        )
+        return signal_cls(backend)
+
+    def derived_signal_r(
+        self,
+        datatype: type[SignalDatatypeT],
+        name: str,
+        units: str | None = None,
+        precision: int | None = None,
+    ) -> SignalR[SignalDatatypeT]:
+        """Create a read only derived signal.
+
+        :param datatype: The datatype of the derived signal value
+        :param name:
+            The name of the derived signal. Should be a key within the
+            return value of `transform_cls.raw_to_derived()`.
+        :param units: Engineering units for the derived signal
+        :param precision: Number of digits after the decimal place to display
+        """
+        return self._make_signal(SignalR, datatype, name, units, precision)
+
+    def derived_signal_w(
+        self,
+        datatype: type[SignalDatatypeT],
+        name: str,
+        units: str | None = None,
+        precision: int | None = None,
+    ) -> SignalW[SignalDatatypeT]:
+        """Create a write only derived signal.
+
+        :param datatype: The datatype of the derived signal value
+        :param name:
+            The name of the derived signal. Should be a key within the
+            return value of `transform_cls.raw_to_derived()`.
+        :param units: Engineering units for the derived signal
+        :param precision: Number of digits after the decimal place to display
+        """
+        return self._make_signal(SignalW, datatype, name, units, precision)
+
+    def derived_signal_rw(
+        self,
+        datatype: type[SignalDatatypeT],
+        name: str,
+        units: str | None = None,
+        precision: int | None = None,
+    ) -> SignalRW[SignalDatatypeT]:
+        """Create a read-write derived signal.
+
+        :param datatype: The datatype of the derived signal value
+        :param name:
+            The name of the derived signal. Should be a key within the
+            return value of `transform_cls.raw_to_derived()`.
+        :param units: Engineering units for the derived signal
+        :param precision: Number of digits after the decimal place to display
+        """
+        return self._make_signal(SignalRW, datatype, name, units, precision)
+
+    async def transform(self) -> TransformT:
+        """Return an instance of `transform_cls` with all the parameters filled in."""
+        return await self._transformer.get_transform()
+
+
+def _get_return_datatype(func: Callable[..., SignalDatatypeT]) -> type[SignalDatatypeT]:
+    args = get_type_hints(func)
+    if "return" not in args:
+        msg = f"{func} does not have a type hint for it's return value"
+        raise TypeError(msg)
+    return args["return"]
+
+
+def _get_first_arg_datatype(
+    func: Callable[[SignalDatatypeT], Any],
+) -> type[SignalDatatypeT]:
+    args = get_type_hints(func)
+    args.pop("return", None)
+    if not args:
+        msg = f"{func} does not have a type hinted argument"
+        raise TypeError(msg)
+    return list(args.values())[0]
+
+
+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,
+) -> DerivedSignalFactory:
+    if raw_to_derived:
+
+        class DerivedTransform(Transform):
+            def raw_to_derived(self, **kwargs) -> dict[str, SignalDatatypeT]:
+                return {"value": raw_to_derived(**kwargs)}
+
+        # Update the signature for raw_to_derived to match what we are passed as this
+        # will be checked in DerivedSignalFactory
+        DerivedTransform.raw_to_derived.__annotations__ = get_type_hints(raw_to_derived)
+
+        return DerivedSignalFactory(
+            DerivedTransform, set_derived=set_derived, **(raw_devices or {})
+        )
+    else:
+        return DerivedSignalFactory(Transform, set_derived=set_derived)
+
+
+def derived_signal_r(
+    raw_to_derived: Callable[..., SignalDatatypeT],
+    derived_units: str | None = None,
+    derived_precision: int | None = None,
+    **raw_devices: Device,
+) -> SignalR[SignalDatatypeT]:
+    """Create a read only derived signal.
+
+    :param raw_to_derived:
+        A function that takes the raw values as individual keyword arguments and
+        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.
+    """
+    factory = _make_factory(raw_to_derived=raw_to_derived, raw_devices=raw_devices)
+    return factory.derived_signal_r(
+        datatype=_get_return_datatype(raw_to_derived),
+        name="value",
+        units=derived_units,
+        precision=derived_precision,
+    )
+
+
+def derived_signal_rw(
+    raw_to_derived: Callable[..., SignalDatatypeT],
+    set_derived: Callable[[SignalDatatypeT], Awaitable[None]],
+    derived_units: str | None = None,
+    derived_precision: int | None = None,
+    **raw_devices: Device,
+) -> SignalRW[SignalDatatypeT]:
+    """Create a read-write derived signal.
+
+    :param raw_to_derived:
+        A function that takes the raw values as individual keyword arguments and
+        returns the derived value.
+    :param set_derived:
+        A function that takes the derived value and sets the raw signals. It can
+        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.
+    """
+    raw_to_derived_datatype = _get_return_datatype(raw_to_derived)
+    set_derived_datatype = _get_first_arg_datatype(set_derived)
+    if raw_to_derived_datatype != set_derived_datatype:
+        msg = (
+            f"{raw_to_derived} has datatype {raw_to_derived_datatype} "
+            f"!= {set_derived_datatype} dataype {set_derived_datatype}"
+        )
+        raise TypeError(msg)
+
+    factory = _make_factory(
+        raw_to_derived=raw_to_derived, set_derived=set_derived, raw_devices=raw_devices
+    )
+    return factory.derived_signal_rw(
+        datatype=raw_to_derived_datatype,
+        name="value",
+        units=derived_units,
+        precision=derived_precision,
+    )
+
+
+def derived_signal_w(
+    set_derived: Callable[[SignalDatatypeT], Awaitable[None]],
+    derived_units: str | None = None,
+    derived_precision: int | None = None,
+) -> SignalW[SignalDatatypeT]:
+    """Create a write only derived signal.
+
+    :param set_derived:
+        A function that takes the derived value and sets the raw signals. It can
+        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
+    """
+    factory = _make_factory(set_derived=set_derived)
+    return factory.derived_signal_w(
+        datatype=_get_first_arg_datatype(set_derived),
+        name="value",
+        units=derived_units,
+        precision=derived_precision,
+    )