ophyd-async 0.14.2__py3-none-any.whl → 0.15__py3-none-any.whl

ophyd_async/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.14.2'
-__version_tuple__ = version_tuple = (0, 14, 2)
+__version__ = version = '0.15'
+__version_tuple__ = version_tuple = (0, 15)
 
 __commit_id__ = commit_id = None

ophyd_async/core/__init__.py

@@ -1,5 +1,6 @@
 """The building blocks for making devices."""
 
+from ._datatypes import Array1D, DTypeScalar_co, Table, TableSubclass
 from ._derived_signal import (
     DerivedSignalFactory,
     derived_signal_r,
@@ -23,7 +24,7 @@ from ._device import (
     default_mock_class,
     init_devices,
 )
-from ._device_filler import DeviceFiller
+from ._device_filler import DeviceAnnotation, DeviceFiller
 from ._enums import (
     EnabledDisabled,
     EnableDisable,
@@ -44,7 +45,15 @@ from ._mock_signal_utils import (
     set_mock_value,
     set_mock_values,
 )
-from ._protocol import AsyncConfigurable, AsyncReadable, AsyncStageable, Watcher
+from ._protocol import (
+    AsyncConfigurable,
+    AsyncLocatable,
+    AsyncMovable,
+    AsyncPausable,
+    AsyncReadable,
+    AsyncStageable,
+    Watcher,
+)
 from ._providers import (
     AutoIncrementFilenameProvider,
     AutoIncrementingPathProvider,
@@ -86,8 +95,6 @@ from ._signal import (
     walk_signal_sources,
 )
 from ._signal_backend import (
-    Array1D,
-    DTypeScalar_co,
     Primitive,
     SignalBackend,
     SignalDatatype,
@@ -97,7 +104,6 @@ from ._signal_backend import (
 )
 from ._soft_signal_backend import SoftSignalBackend
 from ._status import AsyncStatus, WatchableAsyncStatus, completed_status
-from ._table import Table, TableSubclass
 from ._utils import (
     CALCULATE_TIMEOUT,
     DEFAULT_TIMEOUT,
@@ -117,6 +123,7 @@ from ._utils import (
     get_enum_cls,
     get_unique,
     in_micros,
+    non_zero,
     wait_for_connection,
 )
 from ._yaml_settings import YamlSettingsProvider
@@ -146,11 +153,15 @@ __all__ = [
     "Device",
     "DeviceConnector",
     "DeviceFiller",
+    "DeviceAnnotation",
     "DeviceVector",
     "init_devices",
     # Protocols
     "AsyncReadable",
     "AsyncConfigurable",
+    "AsyncLocatable",
+    "AsyncMovable",
+    "AsyncPausable",
     "AsyncStageable",
     "Watcher",
     # Status
@@ -255,6 +266,7 @@ __all__ = [
     "make_datakey",
     "wait_for_connection",
     "Ignore",
+    "non_zero",
     # Derived signal
     "derived_signal_r",
     "derived_signal_rw",

ophyd_async/core/{_table.py → _datatypes.py}

@@ -1,13 +1,25 @@
 from __future__ import annotations
 
 from collections.abc import Callable, Sequence
-from typing import Annotated, Any, TypeVar, get_origin, get_type_hints
+from typing import Annotated, Any, TypeVar
 
 import numpy as np
 from pydantic import ConfigDict, Field, model_validator
 from pydantic_numpy.helper.annotation import NpArrayPydanticAnnotation
 
-from ._utils import ConfinedModel, get_dtype
+from ._utils import ConfinedModel, cached_get_origin, cached_get_type_hints, get_dtype
+
+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."""
 
 TableSubclass = TypeVar("TableSubclass", bound="Table")
 
@@ -75,11 +87,8 @@ class Table(ConfinedModel):
         # ...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
-        # 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:
+        for k, anno in cached_get_type_hints(cls).items():
+            if cached_get_origin(anno) is np.ndarray:
                 dtype = get_dtype(anno)
                 new_anno = Annotated[
                     anno,
@@ -88,7 +97,7 @@ class Table(ConfinedModel):
                     ),
                     Field(default_factory=_make_default_factory(dtype)),
                 ]
-            elif get_origin(anno) is Sequence:
+            elif cached_get_origin(anno) is Sequence:
                 new_anno = Annotated[anno, Field(default_factory=list)]
             else:
                 raise TypeError(f"Cannot use annotation {anno} in a Table")
@@ -156,7 +165,7 @@ class Table(ConfinedModel):
             raise AssertionError(f"Cannot construct Table from {data}")
         for field_name, field_value in cls.model_fields.items():
             if (
-                get_origin(field_value.annotation) is np.ndarray
+                cached_get_origin(field_value.annotation) is np.ndarray
                 and field_value.annotation
                 and field_name in data_dict
             ):

ophyd_async/core/_derived_signal.py

@@ -7,7 +7,6 @@ from typing import (
     TypeVar,
     get_args,
     get_origin,
-    get_type_hints,
     is_typeddict,
 )
 
@@ -22,6 +21,7 @@ from ._derived_signal_backend import (
 from ._device import Device
 from ._signal import Signal, SignalR, SignalRW, SignalT, SignalW
 from ._signal_backend import Primitive, SignalDatatypeT
+from ._utils import cached_get_type_hints
 
 
 class DerivedSignalFactory(Generic[TransformT]):
@@ -208,7 +208,7 @@ class DerivedSignalFactory(Generic[TransformT]):
 
 
 def _get_return_datatype(func: Callable[..., SignalDatatypeT]) -> type[SignalDatatypeT]:
-    args = get_type_hints(func)
+    args = cached_get_type_hints(func)
     if "return" not in args:
         msg = f"{func} does not have a type hint for it's return value"
         raise TypeError(msg)

ophyd_async/core/_derived_signal_backend.py

@@ -291,11 +291,7 @@ class DerivedSignalBackend(SignalBackend[SignalDatatypeT]):
         )
         raise RuntimeError(msg)
 
-    async def put(self, value: SignalDatatypeT | None, wait: bool) -> None:
-        if wait is False:
-            msg = "Cannot put with wait=False"
-            raise RuntimeError(msg)
-
+    async def put(self, value: SignalDatatypeT | None) -> None:
         value = error_if_none(
             value,
             "Must be given a value to put",

ophyd_async/core/_device_filler.py

@@ -13,15 +13,13 @@ from typing import (
     Union,
     cast,
     get_args,
-    get_origin,
-    get_type_hints,
     runtime_checkable,
 )
 
 from ._device import Device, DeviceConnector, DeviceVector
 from ._signal import Ignore, Signal, SignalX
 from ._signal_backend import SignalBackend, SignalDatatype
-from ._utils import get_origin_class
+from ._utils import cached_get_origin, cached_get_type_hints, get_origin_class
 
 SignalBackendT = TypeVar("SignalBackendT", bound=SignalBackend)
 DeviceConnectorT = TypeVar("DeviceConnectorT", bound=DeviceConnector)
@@ -117,9 +115,9 @@ class DeviceFiller(Generic[SignalBackendT, DeviceConnectorT]):
         # https://github.com/python/cpython/issues/124840
         cls = type(self._device)
         # Get hints without Annotated for determining types
-        hints = get_type_hints(cls)
+        hints = cached_get_type_hints(cls)
         # Get hints with Annotated for wrapping signals and backends
-        extra_hints = get_type_hints(cls, include_extras=True)
+        extra_hints = cached_get_type_hints(cls, include_extras=True)
         for attr_name, annotation in hints.items():
             if annotation is Ignore:
                 self.ignored_signals.add(attr_name)
@@ -128,7 +126,7 @@ class DeviceFiller(Generic[SignalBackendT, DeviceConnectorT]):
             args = get_args(annotation)
 
             if (
-                get_origin(annotation) is Union
+                cached_get_origin(annotation) is Union
                 and types.NoneType in args
                 and len(args) == 2
             ):

ophyd_async/core/_mock_signal_backend.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Callable
+from collections.abc import Awaitable, Callable
 from functools import cached_property
 from typing import TYPE_CHECKING
 from unittest.mock import AsyncMock
@@ -17,6 +17,11 @@ from ._utils import Callback
 if TYPE_CHECKING:
     from ._device import LazyMock
 
+MockPutCallback = (
+    Callable[[SignalDatatypeT], SignalDatatypeT | None]
+    | Callable[[SignalDatatypeT], Awaitable[SignalDatatypeT | None]]
+)
+
 
 class MockSignalBackend(SignalBackend[SignalDatatypeT]):
     """Signal backend for testing, created by ``Device.connect(mock=True)``."""
@@ -42,13 +47,27 @@ class MockSignalBackend(SignalBackend[SignalDatatypeT]):
 
         # use existing Mock if provided
         self.mock = mock
+        self._mock_put_callback: MockPutCallback | None = None
         super().__init__(datatype=self.initial_backend.datatype)
 
+    def set_mock_put_callback(self, callback: MockPutCallback | None):
+        if "put_mock" in self.__dict__:
+            # put_mock cached property exists, so set the side effect on it
+            self.put_mock.side_effect = callback
+        else:
+            # put_mock doesn't exist, don't create it as that would be slow
+            # so just keep it internally
+            self._mock_put_callback = callback
+
     @cached_property
     def put_mock(self) -> AsyncMock:
         """Return the mock that will track calls to `put()`."""
         put_mock = AsyncMock(
-            name="put", spec=Callable, side_effect=lambda *_, **__: None
+            name="put",
+            spec=Callable,
+            side_effect=self._mock_put_callback
+            if self._mock_put_callback
+            else lambda v: None,
         )
         self.mock().attach_mock(put_mock, "put")
         return put_mock
@@ -73,13 +92,12 @@ class MockSignalBackend(SignalBackend[SignalDatatypeT]):
         put_proceeds.set()
         return put_proceeds
 
-    async def put(self, value: SignalDatatypeT | None, wait: bool):
-        new_value = await self.put_mock(value, wait=wait)
+    async def put(self, value: SignalDatatypeT | None):
+        new_value = await self.put_mock(value)
         if new_value is None:
             new_value = value
-        await self.soft_backend.put(new_value, wait=wait)
-        if wait:
-            await self.put_proceeds.wait()
+        await self.soft_backend.put(new_value)
+        await self.put_proceeds.wait()
 
     async def get_reading(self) -> Reading:
         return await self.soft_backend.get_reading()

ophyd_async/core/_mock_signal_utils.py

@@ -1,9 +1,9 @@
-from collections.abc import Awaitable, Callable, Iterable, Iterator
+from collections.abc import Iterable, Iterator
 from contextlib import contextmanager
 from unittest.mock import AsyncMock, Mock
 
 from ._device import Device, DeviceMock
-from ._mock_signal_backend import MockSignalBackend
+from ._mock_signal_backend import MockPutCallback, MockSignalBackend
 from ._signal import Signal, SignalConnector, SignalR
 from ._signal_backend import SignalDatatypeT
 
@@ -109,16 +109,12 @@ def set_mock_values(
 
 
 @contextmanager
-def _unset_side_effect_cm(put_mock: AsyncMock):
+def _unset_side_effect_cm(backend: MockSignalBackend):
     yield
-    put_mock.side_effect = None
+    backend.set_mock_put_callback(None)
 
 
-def callback_on_mock_put(
-    signal: Signal[SignalDatatypeT],
-    callback: Callable[[SignalDatatypeT, bool], SignalDatatypeT | None]
-    | Callable[[SignalDatatypeT, bool], Awaitable[SignalDatatypeT | None]],
-):
+def callback_on_mock_put(signal: Signal[SignalDatatypeT], callback: MockPutCallback):
     """For setting a callback when a backend is put to.
 
     Can either be used in a context, with the callback being unset on exit, or
@@ -132,8 +128,8 @@ def callback_on_mock_put(
         context.
     """
     backend = _get_mock_signal_backend(signal)
-    backend.put_mock.side_effect = callback
-    return _unset_side_effect_cm(backend.put_mock)
+    backend.set_mock_put_callback(callback)
+    return _unset_side_effect_cm(backend)
 
 
 def set_mock_put_proceeds(signal: Signal, proceeds: bool):

ophyd_async/core/_signal.py

@@ -279,13 +279,11 @@ class SignalW(Signal[SignalDatatypeT], Movable):
     async def set(
         self,
         value: SignalDatatypeT,
-        wait=True,
         timeout: CalculatableTimeout = CALCULATE_TIMEOUT,
     ) -> None:
         """Set the value and return a status saying when it's done.
 
         :param value: The value to set.
-        :param wait: If True, wait for the set to complete.
         :param timeout: The timeout for the set.
         """
         if timeout == CALCULATE_TIMEOUT:
@@ -299,9 +297,7 @@ class SignalW(Signal[SignalDatatypeT], Movable):
             wait_jitter=0,
         ):
             with attempt:
-                await _wait_for(
-                    self._connector.backend.put(value, wait=wait), timeout, source
-                )
+                await _wait_for(self._connector.backend.put(value), timeout, source)
         self.log.debug(f"Successfully put value {value} to backend at source {source}")
 
 
@@ -321,19 +317,16 @@ class SignalX(Signal):
     """Signal that puts the default value."""
 
     @AsyncStatus.wrap
-    async def trigger(
-        self, wait=True, timeout: CalculatableTimeout = CALCULATE_TIMEOUT
-    ) -> None:
+    async def trigger(self, timeout: CalculatableTimeout = CALCULATE_TIMEOUT) -> None:
         """Trigger the action and return a status saying when it's done.
 
-        :param wait: If True, wait for the trigger to complete.
         :param timeout: The timeout for the trigger.
         """
         if timeout == CALCULATE_TIMEOUT:
             timeout = self._timeout
         source = self._connector.backend.source(self.name, read=False)
         self.log.debug(f"Putting default value to backend at source {source}")
-        await _wait_for(self._connector.backend.put(None, wait=wait), timeout, source)
+        await _wait_for(self._connector.backend.put(None), timeout, source)
         self.log.debug(f"Successfully put default value to backend at source {source}")
 
 
@@ -508,6 +501,12 @@ async def observe_signals_value(
                     f"{[signal.source for signal in signals]}. "
                     f"Last observed signal and value were {last_item}"
                 ) from exc
+            except asyncio.CancelledError as exc:
+                raise asyncio.CancelledError(
+                    f"Cancelled Error while waiting {iteration_timeout}s to update "
+                    f"{[signal.source for signal in signals]}. "
+                    f"Last observed signal and value were {last_item}"
+                ) from exc
             if done_status and item is done_status:
                 if exc := done_status.exception():
                     raise exc
@@ -679,7 +678,8 @@ async def set_and_wait_for_value(
     await set_and_wait_for_value(device.parameter, 1)
     ```
     For busy record, or other Signals with pattern:
-      - Set Signal with `wait=True` and stash the Status
+      - Set `wait=non_zero` when creating the signal
+      - Set Signal and stash the Status
       - Read the same Signal to check the operation has started
       - Return the Status so calling code can wait for operation to complete
     ```python

ophyd_async/core/_signal_backend.py

@@ -1,34 +1,22 @@
 from abc import abstractmethod
 from collections.abc import Sequence
-from typing import Generic, TypedDict, TypeVar, get_origin
+from typing import Generic, TypedDict, TypeVar
 
 import numpy as np
 from bluesky.protocols import Reading
 from event_model import DataKey, Dtype, Limits
 
-from ophyd_async.core._utils import (
+from ._datatypes import Array1D, Table
+from ._utils import (
     Callback,
     EnumTypes,
     StrictEnum,
     SubsetEnum,
     SupersetEnum,
+    cached_get_origin,
     get_enum_cls,
 )
 
-from ._table import Table
-
-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
 SignalDatatype = (
     Primitive
@@ -91,7 +79,7 @@ class SignalBackend(Generic[SignalDatatypeT]):
         """Connect to underlying hardware."""
 
     @abstractmethod
-    async def put(self, value: SignalDatatypeT | None, wait: bool):
+    async def put(self, value: SignalDatatypeT | None):
         """Put a value to the PV, if wait then wait for completion."""
 
     @abstractmethod
@@ -142,7 +130,7 @@ class SignalMetadata(TypedDict, total=False):
 def _datakey_dtype(datatype: type[SignalDatatype]) -> Dtype:
     if (
         datatype is np.ndarray
-        or get_origin(datatype) in (Sequence, np.ndarray)
+        or cached_get_origin(datatype) in (Sequence, np.ndarray)
         or issubclass(datatype, Table)
     ):
         return "array"
@@ -161,7 +149,7 @@ def _datakey_dtype_numpy(
         # The value already has a dtype, use that
         return value.dtype
     elif (
-        get_origin(datatype) is Sequence
+        cached_get_origin(datatype) is Sequence
         or datatype is str
         or issubclass(datatype, EnumTypes)
     ):

ophyd_async/core/_soft_signal_backend.py

@@ -6,12 +6,13 @@ from abc import abstractmethod
 from collections.abc import Sequence
 from dataclasses import dataclass
 from functools import lru_cache
-from typing import Any, Generic, get_args, get_origin
+from typing import Any, Generic, get_args
 
 import numpy as np
 from bluesky.protocols import Reading
 from event_model import DataKey
 
+from ._datatypes import Table
 from ._signal_backend import (
     Array1D,
     EnumT,
@@ -24,8 +25,7 @@ from ._signal_backend import (
     make_datakey,
     make_metadata,
 )
-from ._table import Table
-from ._utils import Callback, get_dtype, get_enum_cls
+from ._utils import Callback, cached_get_origin, get_dtype, get_enum_cls
 
 
 class SoftConverter(Generic[SignalDatatypeT]):
@@ -97,11 +97,11 @@ def make_converter(datatype: type[SignalDatatype]) -> SoftConverter:
     enum_cls = get_enum_cls(datatype)
     if datatype in (Sequence[str], typing.Sequence[str]):
         return SequenceStrSoftConverter()
-    elif get_origin(datatype) in (Sequence, typing.Sequence) and enum_cls:
+    elif cached_get_origin(datatype) in (Sequence, typing.Sequence) and enum_cls:
         return SequenceEnumSoftConverter(enum_cls)
     elif datatype is np.ndarray:
         return NDArraySoftConverter()
-    elif get_origin(datatype) == np.ndarray:
+    elif cached_get_origin(datatype) == np.ndarray:
         if datatype not in get_args(SignalDatatype):
             raise TypeError(f"Expected Array1D[dtype], got {datatype}")
         return NDArraySoftConverter(get_dtype(datatype))
@@ -160,7 +160,7 @@ class SoftSignalBackend(SignalBackend[SignalDatatypeT]):
     async def connect(self, timeout: float):
         pass
 
-    async def put(self, value: SignalDatatypeT | None, wait: bool) -> None:
+    async def put(self, value: SignalDatatypeT | None) -> None:
         write_value = self.initial_value if value is None else value
         self.set_value(write_value)
 

ophyd_async/core/_status.py

@@ -3,8 +3,10 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import functools
 import time
+from asyncio import CancelledError
 from collections.abc import AsyncIterator, Awaitable, Callable, Coroutine
 from dataclasses import asdict, replace
 from typing import Generic
@@ -17,16 +19,37 @@ from ._utils import Callback, P, T, WatcherUpdate
 
 
 class AsyncStatusBase(Status, Awaitable[None]):
-    """Convert asyncio awaitable to bluesky Status interface."""
+    """Convert asyncio awaitable to bluesky Status interface.
+
+    Can be used as an async context manager to automatically cancel the calling
+    task when the status completes. This is useful for bounding loop execution:
+    when the status completes, the calling task is cancelled, causing the loop
+    to exit. If the loop completes first, the status task is automatically cancelled.
+    """
 
     def __init__(self, awaitable: Coroutine | asyncio.Task, name: str | None = None):
         if isinstance(awaitable, asyncio.Task):
             self.task = awaitable
         else:
-            self.task = asyncio.create_task(awaitable)
+
+            async def wait_with_error_message(awaitable):
+                try:
+                    await awaitable
+                except CancelledError as e:
+                    raise CancelledError(
+                        f"CancelledError while awaiting {awaitable} on {name}"
+                    ) from e
+
+            self.task = asyncio.create_task(wait_with_error_message(awaitable))
+            # There is a small chance we could be cancelled before
+            # wait_with_error_message starts.
+            # Avoid complaints about awaitable not awaited if task is
+            # pre-emptively cancelled, by ensuring it is always disposed
+            self.task.add_done_callback(lambda _: awaitable.close())
         self.task.add_done_callback(self._run_callbacks)
         self._callbacks: list[Callback[Status]] = []
         self._name = name
+        self._cancelled_error_ok = False
 
     def __await__(self):
         return self.task.__await__()
@@ -85,6 +108,36 @@ class AsyncStatusBase(Status, Awaitable[None]):
             f"task: {self.task.get_coro()}, {status}>"
         )
 
+    async def __aenter__(self):
+        # Grab the calling task, the one that is doing `with status``
+        calling_task = asyncio.current_task()
+        if calling_task is None:
+            raise RuntimeError("Can only use in a context manager inside a task")
+
+        def _cancel_calling_task(task: asyncio.Task, calling_task=calling_task):
+            # If no-one cancelled our child task, then it is expected
+            # that we want to break out of the calling task with block
+            # so mark that the CancelledError should be suppressed on exit
+            self._cancelled_error_ok = not task.cancelled()
+            calling_task.cancel()
+
+        # When our child task is done, then cancel the calling task
+        self.task.add_done_callback(_cancel_calling_task)
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        self.task.cancel()
+        # Need to await the task to suppress teardown warnings, but
+        # we know it will raise CancelledError as we just cancelled it
+        with contextlib.suppress(CancelledError):
+            await self.task
+        if exc_type is CancelledError and self._cancelled_error_ok:
+            # Suppress error as we cancelled it in _cancel_calling_task
+            return True
+        else:
+            # Raise error as we didn't cause it
+            return False
+
     __str__ = __repr__
 
 
@@ -94,13 +147,37 @@ class AsyncStatus(AsyncStatusBase):
     :param awaitable: The coroutine or task to await.
     :param name: The name of the device, if available.
 
-    For example:
+    Can be awaited like a standard Task:
+
     ```python
     status = AsyncStatus(asyncio.sleep(1))
     assert not status.done
-    await status # waits for 1 second
+    await status  # waits for 1 second
     assert status.done
     ```
+
+    Can also be used as a context manager to bound loop execution. When the status
+    completes, the calling task is cancelled, causing loops to exit:
+
+    ```python
+    async with motor.set(target_position):
+        async for value in observe_value(detector):
+            process_reading(value)
+            # Loop exits automatically when motor reaches position
+    ```
+
+    If the loop completes before the status, the status task is cancelled:
+
+    ```python
+    async with AsyncStatus(long_operation()):
+        for i in range(3):
+            await process_step(i)
+        # Loop completes, long_operation() is cancelled
+    ```
+
+    Note that the body of the with statement will only break at a suspension
+    point like `async for` or `await`, so body code without these suspension
+    points will continue even if the status completes.
     """
 
     @classmethod