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

ophyd_async/core/_device_filler.py

@@ -16,7 +16,7 @@ from typing import (
 )
 
 from ._device import Device, DeviceConnector, DeviceVector
-from ._signal import Signal, SignalX
+from ._signal import Ignore, Signal, SignalX
 from ._signal_backend import SignalBackend, SignalDatatype
 from ._utils import get_origin_class
 
@@ -33,6 +33,7 @@ def _get_datatype(annotation: Any) -> type | None:
     args = get_args(annotation)
     if len(args) == 1 and get_origin_class(args[0]):
         return args[0]
+    return None
 
 
 def _logical(name: UniqueName) -> LogicalName:
@@ -53,6 +54,13 @@ class DeviceAnnotation(Protocol):
 
 
 class DeviceFiller(Generic[SignalBackendT, DeviceConnectorT]):
+    """For filling signals on introspected devices.
+
+    :param device: The device to fill.
+    :param signal_backend_factory: A callable that returns a SignalBackend.
+    :param device_connector_factory: A callable that returns a DeviceConnector.
+    """
+
     def __init__(
         self,
         device: Device,
@@ -68,6 +76,7 @@ class DeviceFiller(Generic[SignalBackendT, DeviceConnectorT]):
         self._extras: dict[UniqueName, Sequence[Any]] = {}
         self._signal_datatype: dict[LogicalName, type | None] = {}
         self._vector_device_type: dict[LogicalName, type[Device] | None] = {}
+        self.ignored_signals: set[str] = set()
         # Backends and Connectors stored ready for the connection phase
         self._unfilled_backends: dict[
             LogicalName, tuple[SignalBackendT, type[Signal]]
@@ -108,6 +117,8 @@ class DeviceFiller(Generic[SignalBackendT, DeviceConnectorT]):
         # Get hints with Annotated for wrapping signals and backends
         extra_hints = get_type_hints(cls, include_extras=True)
         for attr_name, annotation in hints.items():
+            if annotation is Ignore:
+                self.ignored_signals.add(attr_name)
             name = UniqueName(attr_name)
             origin = get_origin_class(annotation)
             if (
@@ -138,6 +149,7 @@ class DeviceFiller(Generic[SignalBackendT, DeviceConnectorT]):
                 self._uncreated_devices[name] = origin
 
     def check_created(self):
+        """Check that all Signals and Devices declared in annotations are created."""
         uncreated = sorted(set(self._uncreated_signals).union(self._uncreated_devices))
         if uncreated:
             raise RuntimeError(
@@ -148,6 +160,21 @@ class DeviceFiller(Generic[SignalBackendT, DeviceConnectorT]):
         self,
         filled=True,
     ) -> Iterator[tuple[SignalBackendT, list[Any]]]:
+        """Create all Signals from annotations.
+
+        :param filled:
+            If True then the Signals created should be considered already filled
+            with connection data. If False then `fill_child_signal` needs
+            calling at device connection time before the signal can be
+            connected.
+        :yields: `(backend, extras)`
+            The `SignalBackend` that has been created for this Signal, and the
+            list of extra annotations that could be used to customize it. For
+            example an `EpicsDeviceConnector` consumes `PvSuffix` extras to set the
+            write_pv of the backend. Any unhandled extras should be left on the
+            list so this class can handle them, e.g. `StandardReadableFormat`
+            instances.
+        """
         for name in list(self._uncreated_signals):
             child_type = self._uncreated_signals.pop(name)
             backend = self._signal_backend_factory(
@@ -167,6 +194,17 @@ class DeviceFiller(Generic[SignalBackendT, DeviceConnectorT]):
         self,
         filled=True,
     ) -> Iterator[tuple[DeviceConnectorT, list[Any]]]:
+        """Create all Signals from annotations.
+
+        :param filled:
+            If True then the Devices created should be considered already filled
+            with connection data. If False then `fill_child_device` needs
+            calling at parent device connection time before the child Device can
+            be connected.
+        :yields: `(connector, extras)`
+            The `DeviceConnector` that has been created for this Signal, and the list of
+            extra annotations that could be used to customize it.
+        """
         for name in list(self._uncreated_devices):
             child_type = self._uncreated_devices.pop(name)
             connector = self._device_connector_factory()
@@ -181,6 +219,10 @@ class DeviceFiller(Generic[SignalBackendT, DeviceConnectorT]):
             dest[_logical(name)] = connector
 
     def create_device_vector_entries_to_mock(self, num: int):
+        """Create num entries for each `DeviceVector`.
+
+        This is used when the Device is being connected in mock mode.
+        """
         for name, cls in self._vector_device_type.items():
             if not cls:
                 msg = "Malformed device vector"
@@ -194,6 +236,11 @@ class DeviceFiller(Generic[SignalBackendT, DeviceConnectorT]):
                     self._raise(name, f"Can't make {cls}")
 
     def check_filled(self, source: str):
+        """Check that all the created Signals and Devices are filled.
+
+        :param source: The source of the data that should have done the filling, for
+                       reporting as an error message
+        """
         unfilled = sorted(set(self._unfilled_connectors).union(self._unfilled_backends))
         if unfilled:
             raise RuntimeError(
@@ -216,6 +263,15 @@ class DeviceFiller(Generic[SignalBackendT, DeviceConnectorT]):
         signal_type: type[Signal],
         vector_index: int | None = None,
     ) -> SignalBackendT:
+        """Mark a Signal as filled, and return its backend for filling.
+
+        :param name:
+            The name without trailing underscore, the name in the control system
+        :param signal_type:
+            One of the types `SignalR`, `SignalW`, `SignalRW` or `SignalX`
+        :param vector_index: If the child is in a `DeviceVector` then what index is it
+        :return: The SignalBackend for the filled Signal.
+        """
         name = cast(LogicalName, name)
         if name in self._unfilled_backends:
             # We made it above
@@ -251,6 +307,14 @@ class DeviceFiller(Generic[SignalBackendT, DeviceConnectorT]):
         device_type: type[Device] = Device,
         vector_index: int | None = None,
     ) -> DeviceConnectorT:
+        """Mark a Device as filled, and return its connector for filling.
+
+        :param name:
+            The name without trailing underscore, the name in the control system
+        :param device_type: The `Device` subclass to be created
+        :param vector_index: If the child is in a `DeviceVector` then what index is it
+        :return: The DeviceConnector for the filled Device.
+        """
         name = cast(LogicalName, name)
         if name in self._unfilled_connectors:
             # We made it above

ophyd_async/core/_flyer.py

@@ -9,21 +9,26 @@ from ._utils import T
 
 
 class FlyerController(ABC, Generic[T]):
+    """Base class for controlling 'flyable' devices.
+
+    [`bluesky.protocols.Flyable`](#bluesky.protocols.Flyable).
+    """
+
     @abstractmethod
     async def prepare(self, value: T) -> Any:
-        """Move to the start of the flyscan"""
+        """Move to the start of the flyscan."""
 
     @abstractmethod
     async def kickoff(self):
-        """Start the flyscan"""
+        """Start the flyscan."""
 
     @abstractmethod
     async def complete(self):
-        """Block until the flyscan is done"""
+        """Block until the flyscan is done."""
 
     @abstractmethod
     async def stop(self):
-        """Stop flying and wait everything to be stopped"""
+        """Stop flying and wait everything to be stopped."""
 
 
 class StandardFlyer(
@@ -33,6 +38,11 @@ class StandardFlyer(
     Flyable,
     Generic[T],
 ):
+    """Base class for 'flyable' devices.
+
+    [`bluesky.protocols.Flyable`](#bluesky.protocols.Flyable).
+    """
+
     def __init__(
         self,
         trigger_logic: FlyerController[T],
@@ -54,7 +64,6 @@ class StandardFlyer(
         await self._trigger_logic.stop()
 
     def prepare(self, value: T) -> AsyncStatus:
-        """Setup trajectories"""
         return AsyncStatus(self._prepare(value))
 
     async def _prepare(self, value: T) -> None:

ophyd_async/core/_hdf_dataset.py

@@ -1,5 +1,4 @@
-from collections.abc import Iterator, Sequence
-from dataclasses import dataclass, field
+from collections.abc import Iterator
 from pathlib import Path
 from urllib.parse import urlunparse
 
@@ -10,44 +9,53 @@ from event_model import (
     StreamRange,
     StreamResource,
 )
+from pydantic import BaseModel, Field
 
 
-@dataclass
-class HDFDataset:
+class HDFDatasetDescription(BaseModel):
+    """A description of the type and shape of a dataset in an HDF file."""
+
     data_key: str
+    """The data_key that will appear in the event descriptor,
+    e.g. det or det.data"""
+
     dataset: str
-    shape: Sequence[int] = field(default_factory=tuple)
+    """The dataset name within the HDF file,
+    e.g. /entry/data/data or /entry/instrument/NDAttributes/sum"""
+
+    shape: tuple[int, ...] = Field(default_factory=tuple)
+    """The shape of a single event's data in the HDF file,
+    e.g. (1, 768, 1024) for arrays or () for scalars"""
+
     dtype_numpy: str = ""
+    """The numpy dtype for this field,
+    e.g. <i2 or <f8"""
+
+    chunk_shape: tuple[int, ...]
+    """The explicit chunk size written to disk"""
+
     multiplier: int = 1
-    swmr: bool = False
-    # Represents explicit chunk size written to disk.
-    chunk_shape: tuple[int, ...] = ()
+    """Won't be used soon."""
 
 
 SLICE_NAME = "AD_HDF5_SWMR_SLICE"
 
 
-class HDFFile:
-    """
-    :param full_file_name: Absolute path to the file to be written
-    :param datasets: Datasets to write into the file
+class HDFDocumentComposer:
+    """A helper class to make stream resource and datums for HDF datasets.
+
+    :param full_file_name: Absolute path to the file that has been written
+    :param datasets: Descriptions of each of the datasets that will appear in the file
     """
 
     def __init__(
         self,
         full_file_name: Path,
-        datasets: list[HDFDataset],
+        datasets: list[HDFDatasetDescription],
         hostname: str = "localhost",
     ) -> None:
         self._last_emitted = 0
         self._hostname = hostname
-
-        if len(datasets) == 0:
-            self._bundles = []
-            return None
-
-        bundler_composer = ComposeStreamResource()
-
         uri = urlunparse(
             (
                 "file",
@@ -58,7 +66,7 @@ class HDFFile:
                 None,
             )
         )
-
+        bundler_composer = ComposeStreamResource()
         self._bundles: list[ComposeStreamResourceBundle] = [
             bundler_composer(
                 mimetype="application/x-hdf5",
@@ -66,7 +74,6 @@ class HDFFile:
                 data_key=ds.data_key,
                 parameters={
                     "dataset": ds.dataset,
-                    "swmr": ds.swmr,
                     "multiplier": ds.multiplier,
                     "chunk_shape": ds.chunk_shape,
                 },

ophyd_async/core/_log.py

@@ -63,31 +63,23 @@ def config_ophyd_async_logging(
     color=True,
     level="WARNING",
 ):
-    """
-    Set a new handler on the ``logging.getLogger('ophyd_async')`` logger.
+    """Set a new handler on the ``logging.getLogger('ophyd_async')`` logger.
+
     If this is called more than once, the handler from the previous invocation
     is removed (if still present) and replaced.
 
-    Parameters
-    ----------
-    file : object with ``write`` method or filename string
-        Default is ``sys.stdout``.
-    fmt : Overall logging format
-    datefmt : string
-        Date format. Default is ``'%H:%M:%S'``.
-    color : boolean
-        Use ANSI color codes. True by default.
-    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
-    --------
+
+    :param file:
+        object with ``write`` method or filename string. Default is `sys.stdout`.
+    :param fmt: str Overall logging format
+    :param datefmt: str Date format. Default is `'%H:%M:%S'`.
+    :param color: bool Use ANSI color codes. True by default.
+    :param level: str or int Python logging level, given as string or
+        corresponding integer. Default is 'WARNING'.
+
+    :returns: 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')
@@ -104,7 +96,6 @@ def config_ophyd_async_logging(
     Increase verbosity: show level DEBUG or higher.
 
         config_ophyd_async_logging(level='DEBUG')
-
     """
     global current_handler
 

ophyd_async/core/_mock_signal_backend.py

@@ -3,8 +3,10 @@ from collections.abc import Callable
 from functools import cached_property
 from unittest.mock import AsyncMock
 
-from bluesky.protocols import Descriptor, Reading
+from bluesky.protocols import Reading
+from event_model import DataKey
 
+from ._derived_signal_backend import DerivedSignalBackend
 from ._signal_backend import SignalBackend, SignalDatatypeT
 from ._soft_signal_backend import SoftSignalBackend
 from ._utils import Callback, LazyMock
@@ -23,7 +25,7 @@ class MockSignalBackend(SignalBackend[SignalDatatypeT]):
 
         self.initial_backend = initial_backend
 
-        if isinstance(self.initial_backend, SoftSignalBackend):
+        if isinstance(self.initial_backend, SoftSignalBackend | DerivedSignalBackend):
             # Backend is already a SoftSignalBackend, so use it
             self.soft_backend = self.initial_backend
         else:
@@ -38,11 +40,13 @@ class MockSignalBackend(SignalBackend[SignalDatatypeT]):
 
     @cached_property
     def put_mock(self) -> AsyncMock:
+        """Return the mock that will track calls to `put()`."""
         put_mock = AsyncMock(name="put", spec=Callable)
         self.mock().attach_mock(put_mock, "put")
         return put_mock
 
     def set_value(self, value: SignalDatatypeT):
+        """Set the value of the signal."""
         self.soft_backend.set_value(value)
 
     def source(self, name: str, read: bool) -> str:
@@ -53,6 +57,10 @@ class MockSignalBackend(SignalBackend[SignalDatatypeT]):
 
     @cached_property
     def put_proceeds(self) -> asyncio.Event:
+        """Return an Event that will block `put()` until set.
+
+        The Event is initially set, but can be unset to block `put()`.
+        """
         put_proceeds = asyncio.Event()
         put_proceeds.set()
         return put_proceeds
@@ -72,7 +80,7 @@ class MockSignalBackend(SignalBackend[SignalDatatypeT]):
     async def get_setpoint(self) -> SignalDatatypeT:
         return await self.soft_backend.get_setpoint()
 
-    async def get_datakey(self, source: str) -> Descriptor:
+    async def get_datakey(self, source: str) -> DataKey:
         return await self.soft_backend.get_datakey(source)
 
     def set_callback(self, callback: Callback[Reading[SignalDatatypeT]] | None) -> None:

ophyd_async/core/_protocol.py

@@ -10,67 +10,66 @@ from typing import (
     runtime_checkable,
 )
 
-from bluesky.protocols import HasName, Reading
+from bluesky.protocols import HasName, Location, Reading, T_co
 from event_model import DataKey
 
+from ._utils import T
+
 if TYPE_CHECKING:
     from ._status import AsyncStatus
 
 
 @runtime_checkable
 class AsyncReadable(HasName, Protocol):
+    """Async implementations of the sync [](#bluesky.protocols.Readable)."""
+
     @abstractmethod
     async def read(self) -> dict[str, Reading]:
-        """Return an OrderedDict mapping string field name(s) to dictionaries
-        of values and timestamps and optional per-point metadata.
-
-        Example return value:
+        """Return value, timestamp, optional per-point metadata for each field name.
 
-        .. code-block:: python
+        For example:
 
-            OrderedDict(('channel1',
-                         {'value': 5, 'timestamp': 1472493713.271991}),
-                         ('channel2',
-                         {'value': 16, 'timestamp': 1472493713.539238}))
+            {
+                "channel1": {"value": 5, "timestamp": 1472493713.271991},
+                "channel2": {"value": 16, "timestamp": 1472493713.539238},
+            }
         """
 
     @abstractmethod
     async def describe(self) -> dict[str, DataKey]:
-        """Return an OrderedDict with exactly the same keys as the ``read``
-        method, here mapped to per-scan metadata about each field.
+        """Return per-scan metadata for each field name in `read()`.
 
-        Example return value:
+        For example:
 
-        .. code-block:: python
-
-            OrderedDict(('channel1',
-                         {'source': 'XF23-ID:SOME_PV_NAME',
-                          'dtype': 'number',
-                          'shape': []}),
-                        ('channel2',
-                         {'source': 'XF23-ID:SOME_PV_NAME',
-                          'dtype': 'number',
-                          'shape': []}))
+            {
+                "channel1": {"source": "SOME_PV1", "dtype": "number", "shape": []},
+                "channel2": {"source": "SOME_PV2", "dtype": "number", "shape": []},
+            }
         """
 
 
 @runtime_checkable
 class AsyncConfigurable(HasName, Protocol):
+    """Async implementation of the sync [](#bluesky.protocols.Configurable)."""
+
     @abstractmethod
     async def read_configuration(self) -> dict[str, Reading]:
-        """Same API as ``read`` but for slow-changing fields related to configuration.
-        e.g., exposure time. These will typically be read only once per run.
+        """Return value, timestamp, optional per-point metadata for each field name.
+
+        Same API as [](#AsyncReadable.read) but for slow-changing fields related to
+        configuration. e.g., exposure time. These will typically be read only
+        once per run.
         """
 
     @abstractmethod
     async def describe_configuration(self) -> dict[str, DataKey]:
-        """Same API as ``describe``, but corresponding to the keys in
-        ``read_configuration``.
-        """
+        """Return per-scan metadata for each field name in `read_configuration()`."""
 
 
 @runtime_checkable
 class AsyncPausable(Protocol):
+    """Async implementation of the sync [](#bluesky.protocols.Pausable)."""
+
     @abstractmethod
     async def pause(self) -> None:
         """Perform device-specific work when the RunEngine pauses."""
@@ -82,20 +81,40 @@ class AsyncPausable(Protocol):
 
 @runtime_checkable
 class AsyncStageable(Protocol):
+    """Async implementation of the sync [](#bluesky.protocols.Stageable)."""
+
     @abstractmethod
     def stage(self) -> AsyncStatus:
-        """An optional hook for "setting up" the device for acquisition.
+        """Set up the device for acquisition.
 
-        It should return a ``Status`` that is marked done when the device is
-        done staging.
+        :return: An `AsyncStatus` that is marked done when the device is done staging.
         """
 
     @abstractmethod
     def unstage(self) -> AsyncStatus:
-        """A hook for "cleaning up" the device after acquisition.
+        """Clean up the device after acquisition.
+
+        :return: An `AsyncStatus` that is marked done when the device is done unstaging.
+        """
+
+
+@runtime_checkable
+class AsyncMovable(Protocol[T_co]):
+    @abstractmethod
+    def set(self, value: T_co) -> AsyncStatus:
+        """Return a ``Status`` that is marked done when the device is done moving."""
 
-        It should return a ``Status`` that is marked done when the device is finished
-        unstaging.
+
+@runtime_checkable
+class AsyncLocatable(AsyncMovable[T], Protocol):
+    @abstractmethod
+    async def locate(self) -> Location[T]:
+        """Return the current location of a Device.
+
+        While a ``Readable`` reports many values, a ``Movable`` will have the
+        concept of location. This is where the Device currently is, and where it
+        was last requested to move to. This protocol formalizes how to get the
+        location from a ``Movable``.
         """
 
 
@@ -103,16 +122,17 @@ C = TypeVar("C", contravariant=True)
 
 
 class Watcher(Protocol, Generic[C]):
-    @staticmethod
+    """Protocol for watching changes in values."""
+
     def __call__(
-        *,
-        current: C,
-        initial: C,
-        target: C,
-        name: str | None,
-        unit: str | None,
-        precision: float | None,
-        fraction: float | None,
-        time_elapsed: float | None,
-        time_remaining: float | None,
+        self,
+        current: C | None = None,
+        initial: C | None = None,
+        target: C | None = None,
+        name: str | None = None,
+        unit: str | None = None,
+        precision: int | None = None,
+        fraction: float | None = None,
+        time_elapsed: float | None = None,
+        time_remaining: float | None = None,
     ) -> Any: ...