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

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

ophyd_async/core/_readable.py

@@ -17,25 +17,34 @@ from ._utils import merge_gathered_dicts
 class StandardReadableFormat(Enum):
     """Declare how a `Device` should contribute to the `StandardReadable` verbs."""
 
-    #: Detect which verbs the child supports and contribute to:
-    #:
-    #: - ``read()``, ``describe()`` if it is `bluesky.protocols.Readable`
-    #: - ``read_configuration()``, ``describe_configuration()`` if it is
-    #:   `bluesky.protocols.Configurable`
-    #: - ``stage()``, ``unstage()`` if it is `bluesky.protocols.Stageable`
-    #: - ``hints`` if it `bluesky.protocols.HasHints`
     CHILD = "CHILD"
-    #: Contribute the `Signal` value to ``read_configuration()`` and
-    #: ``describe_configuration()``
+    """Detect which verbs the child supports and contribute to:
+
+    - `read()`, `describe()` if it is [](#bluesky.protocols.Readable)
+    - `read_configuration()`, `describe_configuration()` if it is
+      [](#bluesky.protocols.Configurable)
+    - `stage()`, `unstage()` if it is [](#bluesky.protocols.Stageable)
+    - `hints` if it [](#bluesky.protocols.HasHints)
+    """
+
     CONFIG_SIGNAL = "CONFIG_SIGNAL"
-    #: Contribute the monitored `Signal` value to ``read()`` and ``describe()``` and
-    #: put the signal name in ``hints``
+    """Contribute the `Signal` value to `read_configuration()` and
+    `describe_configuration()`
+    """
+
     HINTED_SIGNAL = "HINTED_SIGNAL"
-    #: Contribute the uncached `Signal` value to ``read()`` and ``describe()```
+    """Contribute the monitored `Signal` value to `read()` and `describe()` and
+    put the signal name in `hints`
+    """
+
     UNCACHED_SIGNAL = "UNCACHED_SIGNAL"
-    #: Contribute the uncached `Signal` value to ``read()`` and ``describe()``` and
-    #: put the signal name in ``hints``
+    """Contribute the uncached `Signal` value to `read()` and `describe()`
+    """
+
     HINTED_UNCACHED_SIGNAL = "HINTED_UNCACHED_SIGNAL"
+    """Contribute the uncached `Signal` value to `read()` and `describe()` and
+    put the signal name in `hints`
+    """
 
     def __call__(self, parent: Device, child: Device):
         if not isinstance(parent, StandardReadable):
@@ -74,11 +83,15 @@ HintedSignal.uncached = _compat_format(
 class StandardReadable(
     Device, AsyncReadable, AsyncConfigurable, AsyncStageable, HasHints
 ):
-    """Device that owns its children and provides useful default behavior.
+    """Device that provides selected child Device values in `read()`.
 
-    - When its name is set it renames child Devices
-    - Signals can be registered for read() and read_configuration()
-    - These signals will be subscribed for read() between stage() and unstage()
+    Provides the ability for children to be registered to:
+    - Participate in `stage()` and `unstage()`
+    - Provide their value in `read()` and `describe()
+    - Provide their value in `read_configuration()` and `describe_configuration()
+    - Select a value to appear in `hints`
+
+    The behavior is customized with a [](#StandardReadableFormat)
     """
 
     # These must be immutable types to avoid accidental sharing between
@@ -119,7 +132,7 @@ class StandardReadable(
         hints: Hints = {}
         for new_hint in self._has_hints:
             # Merge the existing and new hints, based on the type of the value.
-            # This avoids default dict merge behaviour that overrides the values;
+            # This avoids default dict merge behavior that overrides the values;
             # we want to combine them when they are Sequences, and ensure they are
             # identical when string values.
             for key, value in new_hint.hints.items():
@@ -156,13 +169,12 @@ class StandardReadable(
         self,
         format: StandardReadableFormat = StandardReadableFormat.CHILD,
     ) -> Generator[None, None, None]:
-        """Context manager that calls `add_readables` on child Devices added within.
+        """Context manager that calls [](#add_readables) on child Devices added within.
 
-        Scans ``self.children()`` on entry and exit to context manager, and calls
-        `add_readables` on any that are added with the provided
+        Scans `self.children()` on entry and exit to context manager, and calls
+        `add_readables()` on any that are added with the provided
         `StandardReadableFormat`.
         """
-
         dict_copy = dict(self.children())
 
         yield
@@ -192,18 +204,15 @@ class StandardReadable(
         Use output from the given devices to contribute to the verbs of the following
         interfaces:
 
-        - `bluesky.protocols.Readable`
-        - `bluesky.protocols.Configurable`
-        - `bluesky.protocols.Stageable`
-        - `bluesky.protocols.HasHints`
-
-        Parameters
-        ----------
-        devices:
-            The devices to be added
-        format:
-            Determines which of the devices functions are added to which verb as per the
-            `StandardReadableFormat` documentation
+        - [](#bluesky.protocols.Readable)
+        - [](#bluesky.protocols.Configurable)
+        - [](#bluesky.protocols.Stageable)
+        - [](#bluesky.protocols.HasHints)
+
+        :param devices: The devices to be added
+        :param format:
+            Determines which of the devices functions are added to which verb as
+            per the [](#StandardReadableFormat) documentation
         """
 
         def assert_device_is_signalr(device: Device) -> SignalR:

ophyd_async/core/_settings.py

@@ -10,6 +10,28 @@ from ._signal_backend import SignalDatatypeT
 
 
 class Settings(MutableMapping[SignalRW[Any], Any], Generic[DeviceT]):
+    """Used for supplying settings to signals.
+
+    :param device: The device that the settings are for.
+    :param settings: A dictionary of settings to start with.
+
+    :example:
+    ```python
+    # Settings are created from a dict of signals to values
+    settings1 = Settings(device, {device.sig1: 1, device.sig2: 2})
+    settings2 = Settings(device, {device.sig1: 10, device.sig3: 3})
+    # They act like a dictionaries
+    assert settings1[device.sig1] == 1
+    # Including the ability to "or" two settings together
+    settings = settings1 | settings2
+    assert dict(settings) == {
+        device.sig1: 10,
+        device.sig2: 2,
+        device.sig3: 3,
+    }
+    ```
+    """
+
     def __init__(
         self, device: DeviceT, settings: MutableMapping[SignalRW, Any] | None = None
     ):
@@ -48,19 +70,7 @@ class Settings(MutableMapping[SignalRW[Any], Any], Generic[DeviceT]):
         return len(self._settings)
 
     def __or__(self, other: MutableMapping[SignalRW, Any]) -> Settings[DeviceT]:
-        """Create a new Settings that is the union of self overridden by other.
-
-        For example::
-
-            settings1 = Settings(device, {device.sig1: 1, device.sig2: 2})
-            settings2 = Settings(device, {device.sig1: 10, device.sig3: 3})
-            settings = settings1 | settings2
-            assert dict(settings) == {
-                device.sig1: 10,
-                device.sig2: 2,
-                device.sig3: 3,
-            }
-        """
+        """Create a new Settings that is the union of self overridden by other."""
         if isinstance(other, Settings) and not self._is_in_device(other.device):
             raise ValueError(f"{other.device} is not a child of {self.device}")
         return Settings(self.device, self._settings | dict(other))
@@ -70,20 +80,19 @@ class Settings(MutableMapping[SignalRW[Any], Any], Generic[DeviceT]):
     ) -> tuple[Settings[DeviceT], Settings[DeviceT]]:
         """Partition into two Settings based on a predicate.
 
-        Parameters
-        ----------
-        predicate
+        :param predicate:
             Callable that takes each signal, and returns a boolean to say if it
             should be in the first returned Settings
-
-        Returns
-        -------
-            (where_true, where_false)
-
-        For example::
-
-            settings = Settings(device, {device.special: 1, device.sig: 2})
-            specials, others = settings.partition(lambda sig: "special" in sig.name)
+        :returns:
+            `(where_true, where_false)` where each is a Settings object.
+            The first contains the signals for which the predicate returned True,
+            and the second contains the signals for which the predicate returned False.
+
+        :example:
+        ```python
+        settings = Settings(device, {device.special: 1, device.sig: 2})
+        specials, others = settings.partition(lambda sig: "special" in sig.name)
+        ```
         """
         where_true, where_false = Settings(self.device), Settings(self.device)
         for signal, value in self.items():
@@ -93,12 +102,12 @@ class Settings(MutableMapping[SignalRW[Any], Any], Generic[DeviceT]):
 
 
 class SettingsProvider:
+    """Base class for providing settings."""
+
     @abstractmethod
     async def store(self, name: str, data: dict[str, Any]):
         """Store the data, associating it with the given name."""
-        ...
 
     @abstractmethod
     async def retrieve(self, name: str) -> dict[str, Any]:
         """Retrieve the data associated with the given name."""
-        ...