ophyd-async 0.13.7__tar.gz → 0.14.0__tar.gz

{ophyd_async-0.13.7 → ophyd_async-0.14.0}/.copier-answers.yml

@@ -1,5 +1,5 @@
 # Changes here will be overwritten by Copier
-_commit: 5.0.0a4
+_commit: 5.0.0a5
 _src_path: https://github.com/DiamondLightSource/python-copier-template
 author_email: tom.cobb@diamond.ac.uk
 author_name: Tom Cobb

{ophyd_async-0.13.7 → ophyd_async-0.14.0}/.devcontainer/devcontainer.json

@@ -34,6 +34,9 @@
                 "python.terminal.shellIntegration.enabled": false,
                 "python.testing.unittestEnabled": false,
                 "python.testing.pytestEnabled": true,
+                "python.testing.pytestArgs": [
+                    "tests"
+                ],
                 "editor.formatOnSave": true,
                 "editor.codeActionsOnSave": {
                     "source.organizeImports": "explicit"

{ophyd_async-0.13.7 → ophyd_async-0.14.0}/.github/CONTRIBUTING.md

@@ -24,4 +24,4 @@ It is recommended that developers use a [vscode devcontainer](https://code.visua
 
 This project was created using the [Diamond Light Source Copier Template](https://github.com/DiamondLightSource/python-copier-template) for Python projects.
 
-For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the template's [How-to guides](https://diamondlightsource.github.io/python-copier-template/5.0.0a4/how-to.html).
+For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the template's [How-to guides](https://diamondlightsource.github.io/python-copier-template/5.0.0a5/how-to.html).

{ophyd_async-0.13.7 → ophyd_async-0.14.0}/.github/workflows/ci.yml

@@ -31,6 +31,8 @@ jobs:
 
   docs:
     uses: ./.github/workflows/_docs.yml
+    permissions:
+      contents: write
 
   dist:
     uses: ./.github/workflows/_dist.yml

{ophyd_async-0.13.7/src/ophyd_async.egg-info → ophyd_async-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ophyd-async
-Version: 0.13.7
+Version: 0.14.0
 Summary: Asynchronous Bluesky hardware abstraction code, compatible with control systems like EPICS and Tango
 Author-email: Tom Cobb <tom.cobb@diamond.ac.uk>
 License: BSD 3-Clause License

{ophyd_async-0.13.7 → ophyd_async-0.14.0}/docs/tutorials/writing-tests-for-devices.md

@@ -87,6 +87,47 @@ There are a few other things we may wish to do in tests:
 - [](#set_mock_put_proceeds) to block or unblock `Signal.set(..., wait=True)` from completing
 - [](#mock_puts_blocked) a context manager that blocks put proceeds at the start, and unblocks at the end
 
+### Automatic mock behavior injection
+
+If you find yourself repeatedly using [](#callback_on_mock_put) to set up the same mock behavior for a Device type across many tests, you can define a [](#DeviceMock) subclass to automatically inject that behavior when the Device is connected in mock mode. This is especially useful for defining standard mock behavior alongside your Device definitions, making it easier to switch between hardware and mock modes.
+
+For example, if you have a device that needs automatic mock behavior, you can define:
+
+```{literalinclude} ../../src/ophyd_async/epics/motor.py
+:language: python
+:pyobject: InstantMotorMock
+```
+
+Then decorate the original class with [](#default_mock_class) so it is automatically used when connected in mock mode:
+
+```{literalinclude} ../../src/ophyd_async/epics/motor.py
+:language: python
+:start-at: default_mock_class(
+:end-at: class Motor
+```
+
+Now whenever a Motor is connected in mock mode using [](#init_devices)`(mock=True)`, it will automatically use `InstantMotorMock` and have this behavior:
+
+```python
+async with init_devices(mock=True):
+    motor = Motor("BLxxI-MO-TABLE-01:X")
+
+# No manual callback setup needed - the mock behavior is already active
+await motor.user_setpoint.set(50.0)
+assert await motor.user_readback.get_value() == 50.0
+```
+
+You can still override the automatic mock for specific tests by passing an explicit [](#DeviceMock) instance:
+
+```python
+# Use a plain DeviceMock without the automatic behavior
+custom_mock = DeviceMock()
+motor = Motor("TEST:MOTOR")
+await motor.connect(mock=custom_mock)
+```
+
+This approach keeps your mock logic close to your Device definition, reduces duplication across tests, and makes it easier to maintain consistent mock behavior.
+
 ## Tests that execute a bluesky plan
 
 If we need to check that our Device performs correctly within a plan that calls multiple verbs, it is best to test it under an actual RunEngine. This allows you to check that when the verbs are called in the order that they are in the plan, the correct behavior occurs.

{ophyd_async-0.13.7 → ophyd_async-0.14.0}/pyproject.toml

@@ -96,7 +96,7 @@ addopts = """
     --ignore=docs/examples --ignore=src/ophyd_async/epics/signal.py
     """
 # https://iscinumpy.gitlab.io/post/bound-version-constraints/#watch-for-warnings
-filterwarnings = "error"
+filterwarnings = ["error"]
 # Doctest python code in docs, python code in src docstrings, test functions in tests
 testpaths = "docs src tests/unit_tests"
 log_format = "%(asctime)s,%(msecs)03d %(levelname)s (%(threadName)s) %(message)s"

{ophyd_async-0.13.7/.github → ophyd_async-0.14.0}/renovate.json

@@ -6,7 +6,7 @@
   "lockFileMaintenance": {
     "description": "Keep uv.lock up to date, merging if tests pass",
     "enabled": true,
-    "automerge": true    
+    "automerge": true
   },
   "packageRules": [
     {
@@ -20,34 +20,18 @@
       "description": "Disable github actions that are managed by python-copier-template",
       "matchPackageNames": [
         "actions/checkout",
-        "actions/download-artifact",
-        "actions/setup-python",
-        "actions/upload-artifact",
         "astral-sh/setup-uv",
+        "actions/upload-artifact",
+        "actions/download-artifact",
+        "softprops/action-gh-release",
         "codecov/codecov-action",
-        "docker/build-push-action",
-        "docker/login-action",
-        "docker/metadata-action",
-        "docker/setup-buildx-action",
-        "peaceiris/actions-gh-pages",
         "pypa/gh-action-pypi-publish",
-        "softprops/action-gh-release"
+        "peaceiris/actions-gh-pages"
       ],
       "matchManagers": [
         "github-actions"
       ],
       "enabled": false
-    },
-    {
-      "description": "Group non-major github action updates",
-      "groupName": "GitHub Actions",
-      "matchUpdateTypes": [
-        "patch",
-        "minor"
-      ],
-      "matchManagers": [
-        "github-actions"
-      ]
     }
   ]
 }

{ophyd_async-0.13.7 → ophyd_async-0.14.0}/src/ophyd_async/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.13.7'
-__version_tuple__ = version_tuple = (0, 13, 7)
+__version__ = version = '0.14.0'
+__version_tuple__ = version_tuple = (0, 14, 0)
 
-__commit_id__ = commit_id = 'g80ae4488a'
+__commit_id__ = commit_id = 'g3da44d6fb'

{ophyd_async-0.13.7 → ophyd_async-0.14.0}/src/ophyd_async/core/__init__.py

@@ -14,7 +14,15 @@ from ._detector import (
     StandardDetector,
     TriggerInfo,
 )
-from ._device import Device, DeviceConnector, DeviceVector, init_devices
+from ._device import (
+    Device,
+    DeviceConnector,
+    DeviceMock,
+    DeviceVector,
+    LazyMock,
+    default_mock_class,
+    init_devices,
+)
 from ._device_filler import DeviceFiller
 from ._enums import (
     EnabledDisabled,
@@ -27,6 +35,15 @@ from ._flyer import FlyerController, FlyMotorInfo, StandardFlyer
 from ._hdf_dataset import HDFDatasetDescription, HDFDocumentComposer
 from ._log import config_ophyd_async_logging
 from ._mock_signal_backend import MockSignalBackend
+from ._mock_signal_utils import (
+    callback_on_mock_put,
+    get_mock,
+    get_mock_put,
+    mock_puts_blocked,
+    set_mock_put_proceeds,
+    set_mock_value,
+    set_mock_values,
+)
 from ._protocol import AsyncConfigurable, AsyncReadable, AsyncStageable, Watcher
 from ._providers import (
     AutoIncrementFilenameProvider,
@@ -87,7 +104,6 @@ from ._utils import (
     Callback,
     ConfinedModel,
     EnumTypes,
-    LazyMock,
     NotConnectedError,
     Reference,
     StrictEnum,
@@ -166,8 +182,18 @@ __all__ = [
     "soft_signal_r_and_setter",
     "soft_signal_rw",
     # Mock signal
+    "DeviceMock",
     "LazyMock",
     "MockSignalBackend",
+    "default_mock_class",
+    # Mocking utilities
+    "get_mock",
+    "set_mock_value",
+    "set_mock_values",
+    "get_mock_put",
+    "callback_on_mock_put",
+    "mock_puts_blocked",
+    "set_mock_put_proceeds",
     # Signal utilities
     "observe_value",
     "observe_signals_value",

{ophyd_async-0.13.7 → ophyd_async-0.14.0}/src/ophyd_async/core/_device.py

@@ -5,19 +5,71 @@ import sys
 from collections.abc import Awaitable, Callable, Iterator, Mapping, MutableMapping
 from functools import cached_property
 from logging import LoggerAdapter, getLogger
-from typing import Any, TypeVar
+from typing import Any, Generic, TypeVar
+from unittest.mock import Mock
 
 from bluesky.protocols import HasName
 from bluesky.run_engine import call_in_bluesky_event_loop, in_bluesky_event_loop
 
 from ._utils import (
     DEFAULT_TIMEOUT,
-    LazyMock,
     NotConnectedError,
     error_if_none,
     wait_for_connection,
 )
 
+DeviceT = TypeVar("DeviceT", bound="Device")
+
+
+class DeviceMock(Generic[DeviceT]):
+    """A lazily created Mock to be used when connecting in mock mode.
+
+    Creating Mocks is reasonably expensive when each Device (and Signal)
+    requires its own, and the tree is only used when ``Signal.set()`` is
+    called. This class allows a tree of lazily connected Mocks to be
+    constructed so that when the leaf is created, so are its parents.
+    Any calls to the child are then accessible from the parent mock.
+
+    Subclasses can override the `connect()` method to inject custom logic
+    when mock devices are connected.
+
+    ```python
+    >>> parent = DeviceMock()
+    >>> child = DeviceMock("child", parent)
+    >>> child_mock = child()
+    >>> child_mock()  # doctest: +ELLIPSIS
+    <Mock name='mock.child()' id='...'>
+    >>> parent_mock = parent()
+    >>> parent_mock.mock_calls
+    [call.child()]
+
+    ```
+    """
+
+    def __init__(self, name: str = "", parent: DeviceMock | None = None) -> None:
+        self.name = name
+        self.parent = parent
+        self._mock: Mock | None = None
+
+    def __call__(self) -> Mock:
+        if self._mock is None:
+            self._mock = Mock(spec=object)
+            if self.parent is not None:
+                self.parent().attach_mock(self._mock, self.name)
+        return self._mock
+
+    async def connect(self, device: DeviceT) -> None:
+        """Will be called when the device is connected in mock mode.
+
+        This allows mock values to be set and callbacks to be added
+        to the mock device so it behaves more like the real device.
+        """
+
+
+# Keep LazyMock as an alias for backwards compatibility
+# Remove for ophyd-async 1.0
+LazyMock = DeviceMock
+
 
 class DeviceConnector:
     """Defines how a `Device` should be connected and type hints processed."""
@@ -40,7 +92,7 @@ class DeviceConnector:
         during `__init__`.
         """
 
-    async def connect_mock(self, device: Device, mock: LazyMock):
+    async def connect_mock(self, device: Device, mock: DeviceMock):
         """Use during [](#Device.connect) with `mock=True`.
 
         This is called when there is no cached connect done in `mock=True`
@@ -50,12 +102,16 @@ class DeviceConnector:
         exceptions: dict[str, Exception] = {}
         for name, child_device in device.children():
             try:
-                await child_device.connect(mock=mock.child(name))
+                child_mock_class = child_device._mock_class  # noqa: SLF001
+                await child_device.connect(mock=child_mock_class(name, mock))
             except Exception as exc:
                 exceptions[name] = exc
         if exceptions:
             raise NotConnectedError.with_other_exceptions_logged(exceptions)
 
+        # Call the DeviceMock's connect method to inject custom logic
+        await mock.connect(device)
+
     async def connect_real(self, device: Device, timeout: float, force_reconnect: bool):
         """Use during [](#Device.connect) with `mock=False`.
 
@@ -82,8 +138,10 @@ class Device(HasName):
     _name: str = ""
     # None if connect hasn't started, a Task if it has
     _connect_task: asyncio.Task | None = None
+    # The mock class to be used if we connect in mock mode
+    _mock_class: type[DeviceMock] = DeviceMock
     # The mock if we have connected in mock mode
-    _mock: LazyMock | None = None
+    _mock: DeviceMock | None = None
     # The separator to use when making child names
     _child_name_separator: str = "-"
 
@@ -163,7 +221,7 @@ class Device(HasName):
 
     async def connect(
         self,
-        mock: bool | LazyMock = False,
+        mock: bool | DeviceMock = False,
         timeout: float = DEFAULT_TIMEOUT,
         force_reconnect: bool = False,
     ) -> None:
@@ -175,25 +233,26 @@ class Device(HasName):
 
         :param mock:
             If True then use [](#MockSignalBackend) for all Signals. If passed a
-            [](#LazyMock) then pass this down for use within the Signals,
-            otherwise create one.
+            [](#DeviceMock) then pass this down for use within the Signals,
+            otherwise create one using the registered default mock for this device
+            type, or a plain [](#DeviceMock) if no default is registered.
         :param timeout: Time to wait before failing with a TimeoutError.
         :param force_reconnect:
             If True, force a reconnect even if the last connect succeeded.
         """
-        connector = error_if_none(
+        connector: DeviceConnector = error_if_none(
             getattr(self, "_connector", None),
             f"{self}: doesn't have attribute `_connector`,"
             f" did you call `super().__init__` in your `__init__` method?",
         )
         if mock:
             # Always connect in mock mode serially
-            if isinstance(mock, LazyMock):
-                # Use the provided mock
+            if isinstance(mock, DeviceMock):
+                # Use the user supplied mock
                 self._mock = mock
             elif not self._mock:
-                # Make one
-                self._mock = LazyMock()
+                # Make a new mock of the registered type
+                self._mock = self._mock_class()
             await connector.connect_mock(self, self._mock)
         else:
             # Try to cache the connect in real mode
@@ -223,9 +282,6 @@ _not_device_attrs = {
 }
 
 
-DeviceT = TypeVar("DeviceT", bound=Device)
-
-
 class DeviceVector(MutableMapping[int, DeviceT], Device):
     """Defines a dictionary of Device children with arbitrary integer keys.
 
@@ -396,3 +452,23 @@ def init_devices(
             await wait_for_connection(**coros)
 
     return DeviceProcessor(process_devices)
+
+
+def default_mock_class(
+    mock_cls: type[DeviceMock],
+) -> Callable[[type[DeviceT]], type[DeviceT]]:
+    """Register a DeviceMock subclass as the default mock for a Device class.
+
+    This decorator allows automatic injection of mock logic when devices are
+    connected in mock mode. The decorated DeviceMock class should override
+    the `connect()` method to define custom mock behavior.
+
+    :param mock_cls: A DeviceMock subclass to register.
+    :returns: A decorator that registers the mock class for a Device subclass.
+    """
+
+    def wrapper(device_cls: type[DeviceT]) -> type[DeviceT]:
+        device_cls._mock_class = mock_cls  # noqa: SLF001
+        return device_cls
+
+    return wrapper

{ophyd_async-0.13.7 → ophyd_async-0.14.0}/src/ophyd_async/core/_mock_signal_backend.py

@@ -1,6 +1,9 @@
+from __future__ import annotations
+
 import asyncio
 from collections.abc import Callable
 from functools import cached_property
+from typing import TYPE_CHECKING
 from unittest.mock import AsyncMock
 
 from bluesky.protocols import Reading
@@ -9,7 +12,10 @@ 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
+from ._utils import Callback
+
+if TYPE_CHECKING:
+    from ._device import LazyMock
 
 
 class MockSignalBackend(SignalBackend[SignalDatatypeT]):

{ophyd_async-0.13.7/src/ophyd_async/testing → ophyd_async-0.14.0/src/ophyd_async/core}/_mock_signal_utils.py

@@ -2,15 +2,10 @@ from collections.abc import Awaitable, Callable, Iterable, Iterator
 from contextlib import contextmanager
 from unittest.mock import AsyncMock, Mock
 
-from ophyd_async.core import (
-    Device,
-    LazyMock,
-    MockSignalBackend,
-    Signal,
-    SignalConnector,
-    SignalDatatypeT,
-    SignalR,
-)
+from ._device import Device, DeviceMock
+from ._mock_signal_backend import MockSignalBackend
+from ._signal import Signal, SignalConnector, SignalR
+from ._signal_backend import SignalDatatypeT
 
 
 def get_mock(device: Device | Signal) -> Mock:
@@ -19,16 +14,18 @@ def get_mock(device: Device | Signal) -> Mock:
     The device must have been connected in mock mode.
     """
     mock = device._mock  # noqa: SLF001
-    assert isinstance(mock, LazyMock), f"Device {device} not connected in mock mode"
+    if not isinstance(mock, DeviceMock):
+        msg = f"Device {device} not connected in mock mode"
+        raise RuntimeError(msg)
     return mock()
 
 
 def _get_mock_signal_backend(signal: Signal) -> MockSignalBackend:
     connector = signal._connector  # noqa: SLF001
-    assert isinstance(connector, SignalConnector), f"Expected Signal, got {signal}"
-    assert isinstance(connector.backend, MockSignalBackend), (
-        f"Signal {signal} not connected in mock mode"
-    )
+    if not isinstance(connector, SignalConnector):
+        raise TypeError(f"Expected Signal, got {signal}")
+    if not isinstance(connector.backend, MockSignalBackend):
+        raise RuntimeError(f"Signal {signal} not connected in mock mode")
     return connector.backend
 
 

{ophyd_async-0.13.7 → ophyd_async-0.14.0}/src/ophyd_async/core/_signal.py

@@ -19,7 +19,7 @@ from bluesky.protocols import (
 from event_model import DataKey
 from stamina import retry_context
 
-from ._device import Device, DeviceConnector
+from ._device import Device, DeviceConnector, LazyMock
 from ._mock_signal_backend import MockSignalBackend
 from ._protocol import AsyncReadable, AsyncStageable
 from ._signal_backend import SignalBackend, SignalDatatypeT, SignalDatatypeV
@@ -30,7 +30,6 @@ from ._utils import (
     DEFAULT_TIMEOUT,
     CalculatableTimeout,
     Callback,
-    LazyMock,
     T,
     error_if_none,
 )

{ophyd_async-0.13.7 → ophyd_async-0.14.0}/src/ophyd_async/core/_utils.py

@@ -14,7 +14,6 @@ from typing import (
     get_args,
     get_origin,
 )
-from unittest.mock import Mock
 
 import numpy as np
 from pydantic import BaseModel, ConfigDict
@@ -342,45 +341,6 @@ class Reference(Generic[T]):
         return self._obj
 
 
-class LazyMock:
-    """A lazily created Mock to be used when connecting in mock mode.
-
-    Creating Mocks is reasonably expensive when each Device (and Signal)
-    requires its own, and the tree is only used when ``Signal.set()`` is
-    called. This class allows a tree of lazily connected Mocks to be
-    constructed so that when the leaf is created, so are its parents.
-    Any calls to the child are then accessible from the parent mock.
-
-    ```python
-    >>> parent = LazyMock()
-    >>> child = parent.child("child")
-    >>> child_mock = child()
-    >>> child_mock()  # doctest: +ELLIPSIS
-    <Mock name='mock.child()' id='...'>
-    >>> parent_mock = parent()
-    >>> parent_mock.mock_calls
-    [call.child()]
-
-    ```
-    """
-
-    def __init__(self, name: str = "", parent: LazyMock | None = None) -> None:
-        self.parent = parent
-        self.name = name
-        self._mock: Mock | None = None
-
-    def child(self, name: str) -> LazyMock:
-        """Return a child of this LazyMock with the given name."""
-        return LazyMock(name, self)
-
-    def __call__(self) -> Mock:
-        if self._mock is None:
-            self._mock = Mock(spec=object)
-            if self.parent is not None:
-                self.parent().attach_mock(self._mock, self.name)
-        return self._mock
-
-
 class ConfinedModel(BaseModel):
     """A base class confined to explicitly defined fields in the model schema."""
 

{ophyd_async-0.13.7 → ophyd_async-0.14.0}/src/ophyd_async/epics/motor.py

@@ -3,6 +3,8 @@
 https://github.com/epics-modules/motor
 """
 
+from __future__ import annotations
+
 import asyncio
 
 from bluesky.protocols import (
@@ -21,18 +23,22 @@ from ophyd_async.core import (
     AsyncStatus,
     CalculatableTimeout,
     Callback,
+    DeviceMock,
     FlyMotorInfo,
     StandardReadable,
     StrictEnum,
     WatchableAsyncStatus,
     WatcherUpdate,
+    callback_on_mock_put,
+    default_mock_class,
     error_if_none,
     observe_value,
+    set_mock_value,
 )
 from ophyd_async.core import StandardReadableFormat as Format
 from ophyd_async.epics.core import epics_signal_r, epics_signal_rw, epics_signal_w
 
-__all__ = ["MotorLimitsError", "Motor"]
+__all__ = ["MotorLimitsError", "Motor", "InstantMotorMock", "OffsetMode", "UseSetMode"]
 
 
 class MotorLimitsError(Exception):
@@ -61,15 +67,45 @@ def __getattr__(name):
 
 
 class OffsetMode(StrictEnum):
+    """In Set mode, determine what to do when the motor setpoint is written."""
+
     VARIABLE = "Variable"
+    """Change the offset so the readback matches the setpoint."""
     FROZEN = "Frozen"
+    """Tell the controller to change the readback without changing the offset."""
 
 
 class UseSetMode(StrictEnum):
+    """Determine what to do when the motor setpoint is written."""
+
     USE = "Use"
+    """Tell the controller to move to the setpoint."""
     SET = "Set"
+    """Change offset (in record or in controller) when setpoint is written."""
+
+
+class InstantMotorMock(DeviceMock["Motor"]):
+    """Mock behaviour that instantly moves readback to setpoint."""
+
+    async def connect(self, device: Motor) -> None:
+        """Mock signals to do an instant move on setpoint write."""
+        # Set sensible defaults to avoid runtime errors
+        set_mock_value(device.velocity, 1000)  # Prevent ZeroDivisionError
+        set_mock_value(device.max_velocity, 1000)  # Prevent ZeroDivisionError
+
+        # Motor starts in "done" state (not moving)
+        set_mock_value(device.motor_done_move, 1)
+
+        # When setpoint is written to, immediately update readback and done flag
+        def _instant_move(value, wait):
+            set_mock_value(device.motor_done_move, 0)  # Moving
+            set_mock_value(device.user_readback, value)  # Arrive instantly
+            set_mock_value(device.motor_done_move, 1)  # Done
+
+        callback_on_mock_put(device.user_setpoint, _instant_move)
 
 
+@default_mock_class(InstantMotorMock)
 class Motor(
     StandardReadable,
     Locatable[float],