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

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: ...

ophyd_async/core/_providers.py

@@ -10,8 +10,7 @@ from typing import Protocol
 
 @dataclass
 class PathInfo:
-    """
-    Information about where and how to write a file.
+    """Information about where and how to write a file.
 
     :param directory_path: Directory into which files should be written
     :param filename: Base filename to use generated by FilenameProvider, w/o extension
@@ -25,18 +24,24 @@ class PathInfo:
 
 
 class FilenameProvider(Protocol):
+    """Base class for callable classes providing filenames."""
+
     @abstractmethod
     def __call__(self, device_name: str | None = None) -> str:
-        """Get a filename to use for output data, w/o extension"""
+        """Get a filename to use for output data, w/o extension."""
 
 
 class PathProvider(Protocol):
+    """Abstract class that tells a detector where to write its data."""
+
     @abstractmethod
     def __call__(self, device_name: str | None = None) -> PathInfo:
-        """Get the current directory to write files into"""
+        """Get the current directory to write files into."""
 
 
 class StaticFilenameProvider(FilenameProvider):
+    """Provides a constant filename on every call."""
+
     def __init__(self, filename: str):
         self._static_filename = filename
 
@@ -45,6 +50,8 @@ class StaticFilenameProvider(FilenameProvider):
 
 
 class UUIDFilenameProvider(FilenameProvider):
+    """Files will have a UUID as a filename."""
+
     def __init__(
         self,
         uuid_call_func: Callable = uuid.uuid4,
@@ -68,6 +75,8 @@ class UUIDFilenameProvider(FilenameProvider):
 
 
 class AutoIncrementFilenameProvider(FilenameProvider):
+    """Provides a new numerically incremented filename on each call."""
+
     def __init__(
         self,
         base_filename: str = "",
@@ -98,14 +107,16 @@ class AutoIncrementFilenameProvider(FilenameProvider):
 
 
 class StaticPathProvider(PathProvider):
+    """All files will be within a static directory."""
+
     def __init__(
         self,
         filename_provider: FilenameProvider,
-        directory_path: Path,
+        directory_path: Path | str,
         create_dir_depth: int = 0,
     ) -> None:
         self._filename_provider = filename_provider
-        self._directory_path = directory_path
+        self._directory_path = Path(directory_path)
         self._create_dir_depth = create_dir_depth
 
     def __call__(self, device_name: str | None = None) -> PathInfo:
@@ -119,6 +130,8 @@ class StaticPathProvider(PathProvider):
 
 
 class AutoIncrementingPathProvider(PathProvider):
+    """Provides a new numerically incremented path on each call."""
+
     def __init__(
         self,
         filename_provider: FilenameProvider,
@@ -169,6 +182,8 @@ class AutoIncrementingPathProvider(PathProvider):
 
 
 class YMDPathProvider(PathProvider):
+    """Provides a path with the date included in the directory name."""
+
     def __init__(
         self,
         filename_provider: FilenameProvider,
@@ -206,16 +221,20 @@ class YMDPathProvider(PathProvider):
 
 
 class NameProvider(Protocol):
+    """Base class for callable classes providing data keys."""
+
     @abstractmethod
     def __call__(self) -> str:
-        """Get the name to be used as a data_key in the descriptor document"""
+        """Get the name to be used as a data_key in the descriptor document."""
 
 
 class DatasetDescriber(Protocol):
+    """For describing datasets in file writing."""
+
     @abstractmethod
     async def np_datatype(self) -> str:
-        """Represents the numpy datatype"""
+        """Return the numpy datatype for this dataset."""
 
     @abstractmethod
     async def shape(self) -> tuple[int, ...]:
-        """Get the shape of the data collection"""
+        """Get the shape of the data collection."""