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

ophyd_async/core/_signal_backend.py

@@ -7,17 +7,24 @@ from bluesky.protocols import Reading
 from event_model import DataKey, Dtype, Limits
 
 from ._table import Table
-from ._utils import Callback, StrictEnum, T
+from ._utils import Callback, StrictEnum, get_enum_cls
 
 DTypeScalar_co = TypeVar("DTypeScalar_co", covariant=True, bound=np.generic)
+"""A numpy dtype like [](#numpy.float64)."""
+
+
 # To be a 1D array shape should really be tuple[int], but np.array()
 # currently produces tuple[int, ...] even when it has 1D input args
 # https://github.com/numpy/numpy/issues/28077#issuecomment-2566485178
 Array1D = np.ndarray[tuple[int, ...], np.dtype[DTypeScalar_co]]
+"""A type alias for a 1D numpy array with a specific scalar data type.
+
+E.g. `Array1D[np.float64]` is a 1D numpy array of 64-bit floats."""
+
 Primitive = bool | int | float | str
-# NOTE: if you change this union then update the docs to match
 SignalDatatype = (
     Primitive
+    | StrictEnum
     | Array1D[np.bool_]
     | Array1D[np.int8]
     | Array1D[np.uint8]
@@ -30,23 +37,33 @@ SignalDatatype = (
     | Array1D[np.float32]
     | Array1D[np.float64]
     | np.ndarray
-    | StrictEnum
     | Sequence[str]
     | Sequence[StrictEnum]
     | Table
 )
+"""The supported [](#Signal) datatypes:
+
+- A python primitive [](#bool), [](#int), [](#float), [](#str)
+- A [](#StrictEnum) or [](#SubsetEnum) subclass
+- A fixed datatype [](#Array1D) of numpy bool, signed and unsigned integers or float
+- A [](#numpy.ndarray) which can change dimensions and datatype at runtime
+- A sequence of [](#str)
+- A sequence of [](#StrictEnum) or [](#SubsetEnum) subclass
+- A [](#Table) subclass
+"""
 # TODO: These typevars will not be needed when we drop python 3.11
 # as you can do MyConverter[SignalType: SignalTypeUnion]:
 # rather than MyConverter(Generic[SignalType])
 PrimitiveT = TypeVar("PrimitiveT", bound=Primitive)
 SignalDatatypeT = TypeVar("SignalDatatypeT", bound=SignalDatatype)
+"""A typevar for a [](#SignalDatatype)."""
 SignalDatatypeV = TypeVar("SignalDatatypeV", bound=SignalDatatype)
 EnumT = TypeVar("EnumT", bound=StrictEnum)
 TableT = TypeVar("TableT", bound=Table)
 
 
 class SignalBackend(Generic[SignalDatatypeT]):
-    """A read/write/monitor backend for a Signals"""
+    """A read/write/monitor backend for a Signals."""
 
     def __init__(self, datatype: type[SignalDatatypeT] | None):
         self.datatype = datatype
@@ -55,36 +72,37 @@ class SignalBackend(Generic[SignalDatatypeT]):
     def source(self, name: str, read: bool) -> str:
         """Return source of signal.
 
-        Signals may pass a name to the backend, which can be used or discarded.
+        :param name: The name of the signal, which can be used or discarded.
+        :param read: True if we want the source for reading, False if writing.
         """
 
     @abstractmethod
     async def connect(self, timeout: float):
-        """Connect to underlying hardware"""
+        """Connect to underlying hardware."""
 
     @abstractmethod
     async def put(self, value: SignalDatatypeT | None, wait: bool):
-        """Put a value to the PV, if wait then wait for completion"""
+        """Put a value to the PV, if wait then wait for completion."""
 
     @abstractmethod
     async def get_datakey(self, source: str) -> DataKey:
-        """Metadata like source, dtype, shape, precision, units"""
+        """Metadata like source, dtype, shape, precision, units."""
 
     @abstractmethod
     async def get_reading(self) -> Reading[SignalDatatypeT]:
-        """The current value, timestamp and severity"""
+        """Return the current value, timestamp and severity."""
 
     @abstractmethod
     async def get_value(self) -> SignalDatatypeT:
-        """The current value"""
+        """Return the current value."""
 
     @abstractmethod
     async def get_setpoint(self) -> SignalDatatypeT:
-        """The point that a signal was requested to move to."""
+        """Return the point that a signal was requested to move to."""
 
     @abstractmethod
-    def set_callback(self, callback: Callback[T] | None) -> None:
-        """Observe changes to the current value, timestamp and severity"""
+    def set_callback(self, callback: Callback[Reading[SignalDatatypeT]] | None) -> None:
+        """Observe changes to the current value, timestamp and severity."""
 
 
 _primitive_dtype: dict[type[Primitive], Dtype] = {
@@ -96,10 +114,19 @@ _primitive_dtype: dict[type[Primitive], Dtype] = {
 
 
 class SignalMetadata(TypedDict, total=False):
+    """Metadata for a signal. No field is required."""
+
     limits: Limits
+    """The control, display, warning and alarm limits for a numeric datatype."""
+
     choices: list[str]
+    """The choice of possible values for an enum datatype."""
+
     precision: int
+    """The number of digits after the decimal place to display for a float datatype."""
+
     units: str
+    """The engineering units of the value for a numeric datatype."""
 
 
 def _datakey_dtype(datatype: type[SignalDatatype]) -> Dtype:
@@ -156,6 +183,7 @@ def make_datakey(
     source: str,
     metadata: SignalMetadata,
 ) -> DataKey:
+    """Make a DataKey for a given datatype."""
     dtn = _datakey_dtype_numpy(datatype, value)
     return DataKey(
         dtype=_datakey_dtype(datatype),
@@ -165,3 +193,18 @@ def make_datakey(
         source=source,
         **metadata,
     )
+
+
+def make_metadata(
+    datatype: type[SignalDatatypeT] | None,
+    units: str | None = None,
+    precision: int | None = None,
+) -> SignalMetadata:
+    metadata: SignalMetadata = {}
+    if units is not None:
+        metadata["units"] = units
+    if precision is not None:
+        metadata["precision"] = precision
+    if enum_cls := get_enum_cls(datatype):
+        metadata["choices"] = [v.value for v in enum_cls]
+    return metadata

ophyd_async/core/_soft_signal_backend.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import time
+import typing
 from abc import abstractmethod
 from collections.abc import Sequence
 from dataclasses import dataclass
@@ -19,9 +20,9 @@ from ._signal_backend import (
     SignalBackend,
     SignalDatatype,
     SignalDatatypeT,
-    SignalMetadata,
     TableT,
     make_datakey,
+    make_metadata,
 )
 from ._table import Table
 from ._utils import Callback, get_dtype, get_enum_cls
@@ -94,9 +95,9 @@ class TableSoftConverter(SoftConverter[TableT]):
 @lru_cache
 def make_converter(datatype: type[SignalDatatype]) -> SoftConverter:
     enum_cls = get_enum_cls(datatype)
-    if datatype == Sequence[str]:
+    if datatype in (Sequence[str], typing.Sequence[str]):
         return SequenceStrSoftConverter()
-    elif get_origin(datatype) == Sequence and enum_cls:
+    elif get_origin(datatype) in (Sequence, typing.Sequence) and enum_cls:
         return SequenceEnumSoftConverter(enum_cls)
     elif datatype is np.ndarray:
         return NDArraySoftConverter()
@@ -114,7 +115,16 @@ def make_converter(datatype: type[SignalDatatype]) -> SoftConverter:
 
 
 class SoftSignalBackend(SignalBackend[SignalDatatypeT]):
-    """An backend to a soft Signal, for test signals see ``MockSignalBackend``."""
+    """An backend to a soft Signal, for test signals see [](#MockSignalBackend).
+
+    :param datatype: The datatype of the signal, defaults to float if not given.
+    :param initial_value:
+        The initial value of the signal, defaults to the "empty", "zero" or
+        "default" value of the datatype if not given.
+    :param units: The units for numeric datatypes.
+    :param precision:
+        The number of digits after the decimal place to display for a float datatype.
+    """
 
     def __init__(
         self,
@@ -126,13 +136,7 @@ class SoftSignalBackend(SignalBackend[SignalDatatypeT]):
         # Create the right converter for the datatype
         self.converter = make_converter(datatype or float)
         # Add the extra static metadata to the dictionary
-        self.metadata: SignalMetadata = {}
-        if units is not None:
-            self.metadata["units"] = units
-        if precision is not None:
-            self.metadata["precision"] = precision
-        if enum_cls := get_enum_cls(datatype):
-            self.metadata["choices"] = [v.value for v in enum_cls]
+        self.metadata = make_metadata(datatype, units, precision)
         # Create and set the initial value
         self.initial_value = self.converter.write_value(initial_value)
         self.reading: Reading[SignalDatatypeT]
@@ -141,6 +145,7 @@ class SoftSignalBackend(SignalBackend[SignalDatatypeT]):
         super().__init__(datatype)
 
     def set_value(self, value: SignalDatatypeT):
+        """Set the current value, alarm and timestamp."""
         self.reading = Reading(
             value=self.converter.write_value(value),
             timestamp=time.monotonic(),

ophyd_async/core/_status.py

@@ -1,15 +1,13 @@
 """Equivalent of bluesky.protocols.Status for asynchronous tasks."""
 
+from __future__ import annotations
+
 import asyncio
 import functools
 import time
-from collections.abc import AsyncIterator, Callable, Coroutine
+from collections.abc import AsyncIterator, Awaitable, Callable, Coroutine
 from dataclasses import asdict, replace
-from typing import (
-    Generic,
-    TypeVar,
-    cast,
-)
+from typing import Generic
 
 from bluesky.protocols import Status
 
@@ -17,12 +15,9 @@ from ._device import Device
 from ._protocol import Watcher
 from ._utils import Callback, P, T, WatcherUpdate
 
-AS = TypeVar("AS", bound="AsyncStatus")
-WAS = TypeVar("WAS", bound="WatchableAsyncStatus")
-
 
-class AsyncStatusBase(Status):
-    """Convert asyncio awaitable to bluesky Status interface"""
+class AsyncStatusBase(Status, Awaitable[None]):
+    """Convert asyncio awaitable to bluesky Status interface."""
 
     def __init__(self, awaitable: Coroutine | asyncio.Task, name: str | None = None):
         if isinstance(awaitable, asyncio.Task):
@@ -47,6 +42,12 @@ class AsyncStatusBase(Status):
             callback(self)
 
     def exception(self, timeout: float | None = 0.0) -> BaseException | None:
+        """Return any exception raised by the task.
+
+        :param timeout:
+            Taken for compatibility with the Status interface, but must be 0.0 as we
+            cannot wait for an async function in a sync call.
+        """
         if timeout != 0.0:
             raise ValueError(
                 "cannot honour any timeout other than 0 in an asynchronous function"
@@ -88,27 +89,52 @@ class AsyncStatusBase(Status):
 
 
 class AsyncStatus(AsyncStatusBase):
-    """Convert asyncio awaitable to bluesky Status interface"""
+    """Convert an asyncio awaitable to bluesky Status interface.
+
+    :param awaitable: The coroutine or task to await.
+    :param name: The name of the device, if available.
+
+    For example:
+    ```python
+    status = AsyncStatus(asyncio.sleep(1))
+    assert not status.done
+    await status # waits for 1 second
+    assert status.done
+    ```
+    """
 
     @classmethod
-    def wrap(cls: type[AS], f: Callable[P, Coroutine]) -> Callable[P, AS]:
-        """Wrap an async function in an AsyncStatus."""
+    def wrap(cls, f: Callable[P, Coroutine]) -> Callable[P, AsyncStatus]:
+        """Wrap an async function in an AsyncStatus and return it.
+
+        Used to make an async function conform to a bluesky protocol.
+
+        For example:
+        ```python
+        class MyDevice(Device):
+            @AsyncStatus.wrap
+            async def trigger(self):
+                await asyncio.sleep(1)
+        ```
+        """
 
         @functools.wraps(f)
-        def wrap_f(*args: P.args, **kwargs: P.kwargs) -> AS:
+        def wrap_f(*args: P.args, **kwargs: P.kwargs) -> AsyncStatus:
             if args and isinstance(args[0], Device):
                 name = args[0].name
             else:
                 name = None
             return cls(f(*args, **kwargs), name=name)
 
-        # type is actually functools._Wrapped[P, Awaitable, P, AS]
-        # but functools._Wrapped is not necessarily available
-        return cast(Callable[P, AS], wrap_f)
+        return wrap_f
 
 
 class WatchableAsyncStatus(AsyncStatusBase, Generic[T]):
-    """Convert AsyncIterator of WatcherUpdates to bluesky Status interface."""
+    """Convert an asyncio async iterable to bluesky Status and Watcher interface.
+
+    :param iterator: The async iterable to await.
+    :param name: The name of the device, if available.
+    """
 
     def __init__(
         self, iterator: AsyncIterator[WatcherUpdate[T]], name: str | None = None
@@ -135,30 +161,52 @@ class WatchableAsyncStatus(AsyncStatusBase, Generic[T]):
         watcher(**vals)
 
     def watch(self, watcher: Watcher):
+        """Add a watcher to the status.
+
+        It is called:
+        - immediately if there has already been an update
+        - on every subsequent update
+        """
         self._watchers.append(watcher)
         if self._last_update:
             self._update_watcher(watcher, self._last_update)
 
     @classmethod
     def wrap(
-        cls: type[WAS],
+        cls,
         f: Callable[P, AsyncIterator[WatcherUpdate[T]]],
-    ) -> Callable[P, WAS]:
-        """Wrap an AsyncIterator in a WatchableAsyncStatus."""
+    ) -> Callable[P, WatchableAsyncStatus[T]]:
+        """Wrap an AsyncIterator in a WatchableAsyncStatus.
+
+        For example:
+        ```python
+        class MyDevice(Device):
+            @WatchableAsyncStatus.wrap
+            async def trigger(self):
+                # sleep for a second, updating on progress every 0.1 seconds
+                for i in range(10):
+                    yield WatcherUpdate(initial=0, current=i*0.1, target=1)
+                    await asyncio.sleep(0.1)
+        ```
+        """
 
         @functools.wraps(f)
-        def wrap_f(*args: P.args, **kwargs: P.kwargs) -> WAS:
+        def wrap_f(*args: P.args, **kwargs: P.kwargs) -> WatchableAsyncStatus[T]:
             if args and isinstance(args[0], Device):
                 name = args[0].name
             else:
                 name = None
             return cls(f(*args, **kwargs), name=name)
 
-        return cast(Callable[P, WAS], wrap_f)
+        return wrap_f
 
 
 @AsyncStatus.wrap
 async def completed_status(exception: Exception | None = None):
+    """Return a completed AsyncStatus.
+
+    :param exception: If given, then raise this exception when awaited.
+    """
     if exception:
         raise exception
     return None

ophyd_async/core/_table.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Callable, Sequence
-from typing import Annotated, Any, TypeVar, get_origin
+from typing import Annotated, Any, TypeVar, get_origin, get_type_hints
 
 import numpy as np
 from pydantic import BaseModel, ConfigDict, Field, model_validator
@@ -27,7 +27,30 @@ def _make_default_factory(dtype: np.dtype) -> Callable[[], np.ndarray]:
 
 
 class Table(BaseModel):
-    """An abstraction of a Table of str to numpy array."""
+    """An abstraction of a Table where each field is a column.
+
+    For example:
+    ```python
+    >>> from ophyd_async.core import Table, Array1D
+    >>> import numpy as np
+    >>> from collections.abc import Sequence
+    >>> class MyTable(Table):
+    ...     a: Array1D[np.int8]
+    ...     b: Sequence[str]
+    ...
+    >>> t = MyTable(a=[1, 2], b=["x", "y"])
+    >>> len(t)  # the length is the number of rows
+    2
+    >>> t2 = t + t  # adding tables together concatenates them
+    >>> t2.a
+    array([1, 2, 1, 2], dtype=int8)
+    >>> t2.b
+    ['x', 'y', 'x', 'y']
+    >>> t2[1]  # slice a row
+    array([(2, b'y')], dtype=[('a', 'i1'), ('b', 'S40')])
+
+    ```
+    """
 
     # You can use Table in 2 ways:
     # 1. Table(**whatever_pva_gives_us) when pvi adds a Signal to a Device that is not
@@ -40,16 +63,19 @@ class Table(BaseModel):
     model_config = ConfigDict(extra="allow")
 
     # Add an init method to match the above model config, otherwise the type
-    # checker will not think we can pass arbitrary kwargs into the base class init
+    # checker will not think we can pass arbitrary kwargs into the base class init...
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
 
     @classmethod
     def __init_subclass__(cls):
-        # But forbit extra in subclasses so it gets validated
+        # ...but forbid extra in subclasses so it gets validated
         cls.model_config = ConfigDict(validate_assignment=True, extra="forbid")
         # Change fields to have the correct annotations
-        for k, anno in cls.__annotations__.items():
+        # TODO: refactor so we don't need this to break circular imports
+        from ._signal_backend import Array1D
+
+        for k, anno in get_type_hints(cls, localns={"Array1D": Array1D}).items():
             if get_origin(anno) is np.ndarray:
                 dtype = get_dtype(anno)
                 new_anno = Annotated[
@@ -67,7 +93,6 @@ class Table(BaseModel):
 
     def __add__(self, right: TableSubclass) -> TableSubclass:
         """Concatenate the arrays in field values."""
-
         if type(right) is not type(self):
             raise RuntimeError(
                 f"{right} is not a `Table`, or is not the same "
@@ -84,6 +109,7 @@ class Table(BaseModel):
         )
 
     def numpy_dtype(self) -> np.dtype:
+        """Return a numpy dtype for a single row."""
         dtype = []
         for k, v in self:
             if isinstance(v, np.ndarray):
@@ -95,6 +121,7 @@ class Table(BaseModel):
         return np.dtype(dtype)
 
     def numpy_table(self, selection: slice | None = None) -> np.ndarray:
+        """Return a numpy array of the whole table."""
         array = None
         for k, v in self:
             if selection:
@@ -109,7 +136,9 @@ class Table(BaseModel):
 
     @model_validator(mode="before")
     @classmethod
-    def validate_array_dtypes(cls, data: Any) -> Any:
+    def _validate_array_dtypes(cls, data: Any) -> Any:
+        # Validates that array datatypes given in the table are of the
+        # correct format.
         if isinstance(data, dict):
             data_dict = data
         elif isinstance(data, Table):
@@ -137,7 +166,7 @@ class Table(BaseModel):
         return data_dict
 
     @model_validator(mode="after")
-    def validate_lengths(self) -> Table:
+    def _validate_lengths(self) -> Table:
         lengths: dict[int, set[str]] = {}
         for field_name, field_value in self:
             lengths.setdefault(len(field_value), set()).add(field_name)