ophyd-async 0.4.0__py3-none-any.whl → 0.5.1__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.4.0'
-__version_tuple__ = version_tuple = (0, 4, 0)
+__version__ = version = '0.5.1'
+__version_tuple__ = version_tuple = (0, 5, 1)

ophyd_async/core/__init__.py

@@ -1,26 +1,13 @@
-from ._providers import (
-    AutoIncrementFilenameProvider,
-    AutoIncrementingPathProvider,
-    FilenameProvider,
-    NameProvider,
-    PathInfo,
-    PathProvider,
-    ShapeProvider,
-    StaticFilenameProvider,
-    StaticPathProvider,
-    UUIDFilenameProvider,
-    YMDPathProvider,
-)
-from .async_status import AsyncStatus, WatchableAsyncStatus
-from .detector import (
+from ._detector import (
     DetectorControl,
     DetectorTrigger,
     DetectorWriter,
     StandardDetector,
     TriggerInfo,
 )
-from .device import Device, DeviceCollector, DeviceVector
-from .device_save_loader import (
+from ._device import Device, DeviceCollector, DeviceVector
+from ._device_save_loader import (
+    all_at_once,
     get_signal_values,
     load_device,
     load_from_yaml,
@@ -29,9 +16,11 @@ from .device_save_loader import (
     set_signal_values,
     walk_rw_signals,
 )
-from .flyer import HardwareTriggeredFlyable, TriggerLogic
-from .mock_signal_backend import MockSignalBackend
-from .mock_signal_utils import (
+from ._flyer import StandardFlyer, TriggerLogic
+from ._hdf_dataset import HDFDataset, HDFFile
+from ._log import config_ophyd_async_logging
+from ._mock_signal_backend import MockSignalBackend
+from ._mock_signal_utils import (
     callback_on_mock_put,
     get_mock_put,
     mock_puts_blocked,
@@ -40,7 +29,22 @@ from .mock_signal_utils import (
     set_mock_value,
     set_mock_values,
 )
-from .signal import (
+from ._protocol import AsyncConfigurable, AsyncReadable, AsyncStageable
+from ._providers import (
+    AutoIncrementFilenameProvider,
+    AutoIncrementingPathProvider,
+    FilenameProvider,
+    NameProvider,
+    PathInfo,
+    PathProvider,
+    ShapeProvider,
+    StaticFilenameProvider,
+    StaticPathProvider,
+    UUIDFilenameProvider,
+    YMDPathProvider,
+)
+from ._readable import ConfigSignal, HintedSignal, StandardReadable
+from ._signal import (
     Signal,
     SignalR,
     SignalRW,
@@ -51,98 +55,107 @@ from .signal import (
     assert_reading,
     assert_value,
     observe_value,
+    set_and_wait_for_other_value,
     set_and_wait_for_value,
     soft_signal_r_and_setter,
     soft_signal_rw,
     wait_for_value,
 )
-from .signal_backend import RuntimeSubsetEnum, SignalBackend, SubsetEnum
-from .soft_signal_backend import SoftSignalBackend
-from .standard_readable import ConfigSignal, HintedSignal, StandardReadable
-from .utils import (
+from ._signal_backend import RuntimeSubsetEnum, SignalBackend, SubsetEnum
+from ._soft_signal_backend import SignalMetadata, SoftSignalBackend
+from ._status import AsyncStatus, WatchableAsyncStatus
+from ._utils import (
     DEFAULT_TIMEOUT,
     CalculatableTimeout,
     CalculateTimeout,
-    Callback,
     NotConnected,
     ReadingValueCallback,
     T,
+    WatcherUpdate,
     get_dtype,
     get_unique,
-    merge_gathered_dicts,
+    in_micros,
     wait_for_connection,
 )
 
 __all__ = [
-    "AsyncStatus",
-    "AutoIncrementFilenameProvider",
-    "AutoIncrementingPathProvider",
-    "CalculatableTimeout",
-    "CalculateTimeout",
-    "Callback",
-    "ConfigSignal",
-    "DEFAULT_TIMEOUT",
     "DetectorControl",
     "DetectorTrigger",
     "DetectorWriter",
+    "StandardDetector",
+    "TriggerInfo",
     "Device",
     "DeviceCollector",
     "DeviceVector",
-    "FilenameProvider",
-    "HardwareTriggeredFlyable",
-    "HintedSignal",
+    "all_at_once",
+    "get_signal_values",
+    "load_device",
+    "load_from_yaml",
+    "save_device",
+    "save_to_yaml",
+    "set_signal_values",
+    "walk_rw_signals",
+    "StandardFlyer",
+    "TriggerLogic",
+    "HDFDataset",
+    "HDFFile",
+    "config_ophyd_async_logging",
     "MockSignalBackend",
+    "callback_on_mock_put",
+    "get_mock_put",
+    "mock_puts_blocked",
+    "reset_mock_put_calls",
+    "set_mock_put_proceeds",
+    "set_mock_value",
+    "set_mock_values",
+    "AsyncConfigurable",
+    "AsyncReadable",
+    "AsyncStageable",
+    "AutoIncrementFilenameProvider",
+    "AutoIncrementingPathProvider",
+    "FilenameProvider",
     "NameProvider",
-    "NotConnected",
     "PathInfo",
     "PathProvider",
-    "ReadingValueCallback",
-    "RuntimeSubsetEnum",
     "ShapeProvider",
+    "StaticFilenameProvider",
+    "StaticPathProvider",
+    "UUIDFilenameProvider",
+    "YMDPathProvider",
+    "ConfigSignal",
+    "HintedSignal",
+    "StandardReadable",
     "Signal",
-    "SignalBackend",
     "SignalR",
     "SignalRW",
     "SignalW",
     "SignalX",
-    "SoftSignalBackend",
-    "StandardDetector",
-    "StandardReadable",
-    "StaticFilenameProvider",
-    "StaticPathProvider",
-    "SubsetEnum",
-    "T",
-    "TriggerInfo",
-    "TriggerLogic",
-    "UUIDFilenameProvider",
-    "WatchableAsyncStatus",
-    "YMDPathProvider",
-    # Lower-cased imports
     "assert_configuration",
     "assert_emitted",
     "assert_reading",
     "assert_value",
-    "callback_on_mock_put",
-    "get_dtype",
-    "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",
+    "set_and_wait_for_other_value",
     "soft_signal_r_and_setter",
     "soft_signal_rw",
-    "wait_for_connection",
     "wait_for_value",
-    "walk_rw_signals",
+    "RuntimeSubsetEnum",
+    "SignalBackend",
+    "SubsetEnum",
+    "SignalMetadata",
+    "SoftSignalBackend",
+    "AsyncStatus",
+    "WatchableAsyncStatus",
+    "DEFAULT_TIMEOUT",
+    "CalculatableTimeout",
+    "CalculateTimeout",
+    "NotConnected",
+    "ReadingValueCallback",
+    "T",
+    "WatcherUpdate",
+    "get_dtype",
+    "get_unique",
+    "in_micros",
+    "wait_for_connection",
 ]

ophyd_async/core/{detector.py → _detector.py}

@@ -13,7 +13,6 @@ from typing import (
     List,
     Optional,
     Sequence,
-    TypeVar,
 )
 
 from bluesky.protocols import (
@@ -29,13 +28,10 @@ from bluesky.protocols import (
 )
 from pydantic import BaseModel, Field
 
-from ophyd_async.protocols import AsyncConfigurable, AsyncReadable
-
-from .async_status import AsyncStatus, WatchableAsyncStatus
-from .device import Device
-from .utils import DEFAULT_TIMEOUT, WatcherUpdate, merge_gathered_dicts
-
-T = TypeVar("T")
+from ._device import Device
+from ._protocol import AsyncConfigurable, AsyncReadable
+from ._status import AsyncStatus, WatchableAsyncStatus
+from ._utils import DEFAULT_TIMEOUT, T, WatcherUpdate, merge_gathered_dicts
 
 
 class DetectorTrigger(str, Enum):
@@ -59,11 +55,16 @@ class TriggerInfo(BaseModel):
     #: Sort of triggers that will be sent
     trigger: DetectorTrigger = Field()
     #: What is the minimum deadtime between triggers
-    deadtime: float = Field(ge=0)
+    deadtime: float | None = Field(ge=0)
     #: What is the maximum high time of the triggers
-    livetime: float = Field(ge=0)
+    livetime: float | None = Field(ge=0)
     #: What is the maximum timeout on waiting for a frame
     frame_timeout: float | None = Field(None, gt=0)
+    #: How many triggers make up a single StreamDatum index, to allow multiple frames
+    #: from a faster detector to be zipped with a single frame from a slow detector
+    #: e.g. if num=10 and multiplier=5 then the detector will take 10 frames,
+    #: but publish 2 indices, and describe() will show a shape of (5, h, w)
+    multiplier: int = 1
 
 
 class DetectorControl(ABC):
@@ -73,7 +74,7 @@ class DetectorControl(ABC):
     """
 
     @abstractmethod
-    def get_deadtime(self, exposure: float) -> float:
+    def get_deadtime(self, exposure: float | None) -> float:
         """For a given exposure, how long should the time between exposures be"""
 
     @abstractmethod
@@ -200,10 +201,10 @@ class StandardDetector(
 
     @AsyncStatus.wrap
     async def stage(self) -> None:
-        # Disarm the detector, stop filewriting, and open file for writing.
+        # Disarm the detector, stop filewriting.
         await self._check_config_sigs()
         await asyncio.gather(self.writer.close(), self.controller.disarm())
-        self._describe = await self.writer.open()
+        self._trigger_info = None
 
     async def _check_config_sigs(self):
         """Checks configuration signals are named and connected."""
@@ -216,7 +217,7 @@ class StandardDetector(
                 await signal.get_value()
             except NotImplementedError:
                 raise Exception(
-                    f"config signal {signal._name} must be connected before it is "
+                    f"config signal {signal.name} must be connected before it is "
                     + "passed to the detector"
                 )
 
@@ -240,10 +241,15 @@ class StandardDetector(
 
     @AsyncStatus.wrap
     async def trigger(self) -> None:
-        # set default trigger_info
-        self._trigger_info = TriggerInfo(
-            number=1, trigger=DetectorTrigger.internal, deadtime=0.0, livetime=0.0
-        )
+        if self._trigger_info is None:
+            await self.prepare(
+                TriggerInfo(
+                    number=1,
+                    trigger=DetectorTrigger.internal,
+                    deadtime=None,
+                    livetime=None,
+                )
+            )
         # Arm the detector and wait for it to finish.
         indices_written = await self.writer.get_indices_written()
         written_status = await self.controller.arm(
@@ -254,19 +260,15 @@ class StandardDetector(
         end_observation = indices_written + 1
 
         async for index in self.writer.observe_indices_written(
-            DEFAULT_TIMEOUT + self._trigger_info.livetime + self._trigger_info.deadtime
+            DEFAULT_TIMEOUT
+            + (self._trigger_info.livetime or 0)
+            + (self._trigger_info.deadtime or 0)
         ):
             if index >= end_observation:
                 break
 
-    def prepare(
-        self,
-        value: T,
-    ) -> AsyncStatus:
-        # Just arm detector for the time being
-        return AsyncStatus(self._prepare(value))
-
-    async def _prepare(self, value: T) -> None:
+    @AsyncStatus.wrap
+    async def prepare(self, value: TriggerInfo) -> None:
         """
         Arm detector.
 
@@ -281,22 +283,26 @@ class StandardDetector(
         Args:
             value: TriggerInfo describing how to trigger the detector
         """
-        assert type(value) is TriggerInfo
         self._trigger_info = value
+        if value.trigger != DetectorTrigger.internal:
+            assert (
+                value.deadtime
+            ), "Deadtime must be supplied when in externally triggered mode"
+        if value.deadtime:
+            required = self.controller.get_deadtime(self._trigger_info.livetime)
+            assert required <= value.deadtime, (
+                f"Detector {self.controller} needs at least {required}s deadtime, "
+                f"but trigger logic provides only {value.deadtime}s"
+            )
         self._initial_frame = await self.writer.get_indices_written()
         self._last_frame = self._initial_frame + self._trigger_info.number
-
-        required = self.controller.get_deadtime(self._trigger_info.livetime)
-        assert required <= self._trigger_info.deadtime, (
-            f"Detector {self.controller} needs at least {required}s deadtime, "
-            f"but trigger logic provides only {self._trigger_info.deadtime}s"
-        )
         self._arm_status = await self.controller.arm(
             num=self._trigger_info.number,
             trigger=self._trigger_info.trigger,
             exposure=self._trigger_info.livetime,
         )
         self._fly_start = time.monotonic()
+        self._describe = await self.writer.open(value.multiplier)
 
     @AsyncStatus.wrap
     async def kickoff(self):
@@ -311,8 +317,8 @@ class StandardDetector(
             self._trigger_info.frame_timeout
             or (
                 DEFAULT_TIMEOUT
-                + self._trigger_info.livetime
-                + self._trigger_info.deadtime
+                + (self._trigger_info.livetime or 0)
+                + (self._trigger_info.deadtime or 0)
             )
         ):
             yield WatcherUpdate(

ophyd_async/core/{device.py → _device.py}

@@ -19,7 +19,7 @@ from typing import (
 from bluesky.protocols import HasName
 from bluesky.run_engine import call_in_bluesky_event_loop
 
-from .utils import DEFAULT_TIMEOUT, NotConnected, wait_for_connection
+from ._utils import DEFAULT_TIMEOUT, NotConnected, wait_for_connection
 
 
 class Device(HasName):

ophyd_async/core/{device_save_loader.py → _device_save_loader.py}

@@ -8,8 +8,8 @@ from bluesky.plan_stubs import abs_set, wait
 from bluesky.protocols import Location
 from bluesky.utils import Msg
 
-from .device import Device
-from .signal import SignalRW
+from ._device import Device
+from ._signal import SignalRW
 
 
 def ndarray_representer(dumper: yaml.Dumper, array: npt.NDArray[Any]) -> yaml.Node:
@@ -241,7 +241,7 @@ def save_device(
     Therefore, users should consider the order of device loading and write their
     own sorter algorithms accordingly.
 
-    See :func:`ophyd_async.panda.phase_sorter` for a valid implementation of the
+    See :func:`ophyd_async.fastcs.panda.phase_sorter` for a valid implementation of the
     sorter.
 
     Parameters

ophyd_async/core/{flyer.py → _flyer.py}

@@ -1,14 +1,12 @@
 from abc import ABC, abstractmethod
-from typing import Dict, Generic, Sequence, TypeVar
+from typing import Dict, Generic, Sequence
 
 from bluesky.protocols import DataKey, Flyable, Preparable, Reading, Stageable
 
-from .async_status import AsyncStatus
-from .device import Device
-from .signal import SignalR
-from .utils import merge_gathered_dicts
-
-T = TypeVar("T")
+from ._device import Device
+from ._signal import SignalR
+from ._status import AsyncStatus
+from ._utils import T, merge_gathered_dicts
 
 
 class TriggerLogic(ABC, Generic[T]):
@@ -29,7 +27,7 @@ class TriggerLogic(ABC, Generic[T]):
         """Stop flying and wait everything to be stopped"""
 
 
-class HardwareTriggeredFlyable(
+class StandardFlyer(
     Device,
     Stageable,
     Preparable,

ophyd_async/{epics/areadetector/writers/general_hdffile.py → core/_hdf_dataset.py}

@@ -10,11 +10,9 @@ from event_model import (
     StreamResource,
 )
 
-from ophyd_async.core import PathInfo
-
 
 @dataclass
-class _HDFDataset:
+class HDFDataset:
     data_key: str
     dataset: str
     shape: Sequence[int] = field(default_factory=tuple)
@@ -26,18 +24,16 @@ class _HDFDataset:
 SLICE_NAME = "AD_HDF5_SWMR_SLICE"
 
 
-class _HDFFile:
+class HDFFile:
     """
-    :param directory_info: Contains information about how to construct a StreamResource
     :param full_file_name: Absolute path to the file to be written
     :param datasets: Datasets to write into the file
     """
 
     def __init__(
         self,
-        path_info: PathInfo,
         full_file_name: Path,
-        datasets: List[_HDFDataset],
+        datasets: List[HDFDataset],
         hostname: str = "localhost",
     ) -> None:
         self._last_emitted = 0
@@ -53,7 +49,7 @@ class _HDFFile:
             (
                 "file",
                 self._hostname,
-                str((path_info.root / full_file_name).absolute()),
+                str(full_file_name.absolute()),
                 "",
                 "",
                 None,

ophyd_async/{log.py → core/_log.py}

@@ -34,9 +34,7 @@ class ColoredFormatterWithDeviceName(colorlog.ColoredFormatter):
 
 
 def _validate_level(level) -> int:
-    """
-    Return an int for level comparison
-    """
+    """Return an int for level comparison."""
     if isinstance(level, int):
         levelno = level
     elif isinstance(level, str):
@@ -80,21 +78,31 @@ def config_ophyd_async_logging(
     level : str or int
         Python logging level, given as string or corresponding integer.
         Default is 'WARNING'.
+
     Returns
     -------
     handler : logging.Handler
         The handler, which has already been added to the 'ophyd_async' logger.
+
     Examples
     --------
     Log to a file.
+
         config_ophyd_async_logging(file='/tmp/what_is_happening.txt')
+
     Include the date along with the time. (The log messages will always include
     microseconds, which are configured separately, not as part of 'datefmt'.)
+
         config_ophyd_async_logging(datefmt="%Y-%m-%d %H:%M:%S")
+
     Turn off ANSI color codes.
+
         config_ophyd_async_logging(color=False)
+
     Increase verbosity: show level DEBUG or higher.
+
         config_ophyd_async_logging(level='DEBUG')
+
     """
     global current_handler
 

ophyd_async/core/{mock_signal_backend.py → _mock_signal_backend.py}

@@ -5,9 +5,9 @@ from unittest.mock import Mock
 
 from bluesky.protocols import Descriptor, Reading
 
-from ophyd_async.core.signal_backend import SignalBackend
-from ophyd_async.core.soft_signal_backend import SoftSignalBackend
-from ophyd_async.core.utils import DEFAULT_TIMEOUT, ReadingValueCallback, T
+from ._signal_backend import SignalBackend
+from ._soft_signal_backend import SoftSignalBackend
+from ._utils import DEFAULT_TIMEOUT, ReadingValueCallback, T
 
 
 class MockSignalBackend(SignalBackend[T]):

ophyd_async/core/{mock_signal_utils.py → _mock_signal_utils.py}

@@ -2,18 +2,18 @@ from contextlib import asynccontextmanager, contextmanager
 from typing import Any, Callable, Iterable
 from unittest.mock import Mock
 
-from ophyd_async.core.signal import Signal
-from ophyd_async.core.utils import T
-
-from .mock_signal_backend import MockSignalBackend
+from ._mock_signal_backend import MockSignalBackend
+from ._signal import Signal
+from ._utils import T
 
 
 def _get_mock_signal_backend(signal: Signal) -> MockSignalBackend:
-    assert isinstance(signal._backend, MockSignalBackend), (
+    backend = signal._backend  # noqa:SLF001
+    assert isinstance(backend, MockSignalBackend), (
         "Expected to receive a `MockSignalBackend`, instead "
-        f" received {type(signal._backend)}. "
+        f" received {type(backend)}. "
     )
-    return signal._backend
+    return backend
 
 
 def set_mock_value(signal: Signal[T], value: T):

ophyd_async/{protocols.py → core/_protocol.py}

@@ -14,7 +14,7 @@ from typing import (
 from bluesky.protocols import DataKey, HasName, Reading
 
 if TYPE_CHECKING:
-    from ophyd_async.core.async_status import AsyncStatus
+    from ._status import AsyncStatus
 
 
 @runtime_checkable