ophyd-async 0.8.0a2__tar.gz → 0.8.0a4__tar.gz

{ophyd_async-0.8.0a2 → ophyd_async-0.8.0a4}/.copier-answers.yml

@@ -1,5 +1,5 @@
 # Changes here will be overwritten by Copier
-_commit: 2.4.0
+_commit: 2.5.0
 _src_path: gh:DiamondLightSource/python-copier-template
 author_email: tom.cobb@diamond.ac.uk
 author_name: Tom Cobb

{ophyd_async-0.8.0a2 → ophyd_async-0.8.0a4}/.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/2.4.0/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/2.5.0/how-to.html).

{ophyd_async-0.8.0a2 → ophyd_async-0.8.0a4}/.github/workflows/_pypi.yml

@@ -16,4 +16,4 @@ jobs:
       - name: Publish to PyPI using trusted publishing
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
-          attestations: false          
+          attestations: false

{ophyd_async-0.8.0a2 → ophyd_async-0.8.0a4}/.github/workflows/_release.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Create GitHub Release
         # We pin to the SHA, not the tag, for security reasons.
         # https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
-        uses: softprops/action-gh-release@c062e08bd532815e2082a85e87e3ef29c3e6d191 # v2.0.8
+        uses: softprops/action-gh-release@e7a8f85e1c67a31e6ed99a94b41bd0b71bbee6b8 # v2.0.9
         with:
           prerelease: ${{ contains(github.ref_name, 'a') || contains(github.ref_name, 'b') || contains(github.ref_name, 'rc') }}
           files: "*"

{ophyd_async-0.8.0a2 → ophyd_async-0.8.0a4}/.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
     if: needs.check.outputs.branch-pr == ''
     strategy:
       matrix:
-        runs-on: ["ubuntu-latest"] # can add windows-latest, macos-latest
+        runs-on: ["ubuntu-latest", "windows-latest"] # can add macos-latest
         python-version: ["3.10","3.11"] # 3.12 should be added when p4p is updated
         include:
           # Include one that runs in the dev environment

{ophyd_async-0.8.0a2 → ophyd_async-0.8.0a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ophyd-async
-Version: 0.8.0a2
+Version: 0.8.0a4
 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.8.0a2 → ophyd_async-0.8.0a4}/docs/examples/foo_detector.py

@@ -10,7 +10,7 @@ from ophyd_async.core import (
     StandardDetector,
 )
 from ophyd_async.epics import adcore
-from ophyd_async.epics.signal import epics_signal_rw_rbv
+from ophyd_async.epics.core import epics_signal_rw_rbv
 
 
 class FooDriver(adcore.ADBaseIO):

ophyd_async-0.8.0a4/docs/explanations/decisions/0009-procedural-vs-declarative-devices.md

@@ -0,0 +1,140 @@
+# 9. Procedural vs Declarative Devices
+
+Date: 01/10/24
+
+## Status
+
+Accepted
+
+## Context
+
+In [](./0006-procedural-device-definitions.rst) we decided we preferred the procedural approach to devices, because of the issue of applying structure like `DeviceVector`. Since then we have `FastCS` and `Tango` support which use a declarative approach. We need to decide whether we are happy with this situation, or whether we should go all in one way or the other. A suitable test Device would be:
+
+```python
+class EpicsProceduralDevice(StandardReadable):
+    def __init__(self, prefix: str, num_values: int, name="") -> None:
+        with self.add_children_as_readables():
+            self.value = DeviceVector(
+                {
+                    i: epics_signal_r(float, f"{prefix}Value{i}")
+                    for i in range(1, num_values + 1)
+                }
+            )
+        with self.add_children_as_readables(ConfigSignal):
+            self.mode = epics_signal_rw(EnergyMode, prefix + "Mode")
+        super().__init__(name=name)
+```
+
+and a Tango/FastCS procedural equivalent would be (if we add support to StandardReadable for Format.HINTED_SIGNAL and Format.CONFIG_SIGNAL annotations):
+```python
+class TangoDeclarativeDevice(StandardReadable, TangoDevice):
+    value: Annotated[DeviceVector[SignalR[float]], Format.HINTED_SIGNAL]
+    mode: Annotated[SignalRW[EnergyMode], Format.CONFIG_SIGNAL]
+```
+
+But we could specify the Tango one procedurally (with some slight ugliness around the DeviceVector):
+```python
+class TangoProceduralDevice(StandardReadable):
+    def __init__(self, prefix: str, name="") -> None:
+        with self.add_children_as_readables():
+            self.value = DeviceVector({0: tango_signal_r(float)})
+        with self.add_children_as_readables(ConfigSignal):
+            self.mode = tango_signal_rw(EnergyMode)
+        super().__init__(name=name, connector=TangoConnector(prefix))
+```
+
+or the EPICS one could be declarative:
+```python
+class EpicsDeclarativeDevice(StandardReadable, EpicsDevice):
+    value: Annotated[
+        DeviceVector[SignalR[float]], Format.HINTED_SIGNAL, EpicsSuffix("Value%d", "num_values")
+    ]
+    mode: Annotated[SignalRW[EnergyMode], Format.CONFIG_SIGNAL, EpicsSuffix("Mode")]
+```
+
+Which do we prefer?
+
+## Decision
+
+We decided that the declarative approach is to be preferred until we need to write formatted strings. At that point we should drop to an `__init__` method and a for loop. This is not a step towards only supporting the declarative approach and there are no plans to drop the procedural approach.
+
+The two approaches now look like:
+
+```python
+class Sensor(StandardReadable, EpicsDevice):
+    """A demo sensor that produces a scalar value based on X and Y Movers"""
+
+    value: A[SignalR[float], PvSuffix("Value"), Format.HINTED_SIGNAL]
+    mode: A[SignalRW[EnergyMode], PvSuffix("Mode"), Format.CONFIG_SIGNAL]
+
+
+class SensorGroup(StandardReadable):
+    def __init__(self, prefix: str, name: str = "", sensor_count: int = 3) -> None:
+        with self.add_children_as_readables():
+            self.sensors = DeviceVector(
+                {i: Sensor(f"{prefix}{i}:") for i in range(1, sensor_count + 1)}
+            )
+        super().__init__(name)
+```
+
+## Consequences
+
+We need to:
+- Add support for reading annotations and `PvSuffix` in an `ophyd_async.epics.core.EpicsDevice` baseclass
+- Do the `Format.HINTED_SIGNAL` and `Format.CONFIG_SIGNAL` flags in annotations for `StandardReadable`
+- Ensure we can always drop to `__init__`
+
+
+## pvi structure changes
+Structure read from `.value` now includes `DeviceVector` support. Requires at least PandABlocks-ioc 0.11.2
+
+## Epics `signal` module moves
+`ophyd_async.epics.signal` moves to `ophyd_async.epics.core` with a backwards compat module that emits deprecation warning.
+```python
+# old
+from ophyd_async.epics.signal import epics_signal_rw
+# new
+from ophyd_async.epics.core import epics_signal_rw
+```
+
+## `StandardReadable` wrappers change to `StandardReadableFormat`
+`StandardReadable` wrappers change to enum members of `StandardReadableFormat` (normally imported as `Format`)
+```python
+# old
+from ophyd_async.core import ConfigSignal, HintedSignal
+class MyDevice(StandardReadable):
+    def __init__(self):
+        self.add_readables([sig1], ConfigSignal)
+        self.add_readables([sig2], HintedSignal)
+        self.add_readables([sig3], HintedSignal.uncached)
+# new
+from ophyd_async.core import StandardReadableFormat as Format
+class MyDevice(StandardReadable):
+    def __init__(self):
+        self.add_readables([sig1], Format.CONFIG_SIGNAL)
+        self.add_readables([sig2], Format.HINTED_SIGNAL)
+        self.add_readables([sig3], Format.HINTED_UNCACHED_SIGNAL
+```
+
+## Declarative Devices are now available
+```python
+# old
+from ophyd_async.core import ConfigSignal, HintedSignal
+from ophyd_async.epics.signal import epics_signal_r, epics_signal_rw
+
+class Sensor(StandardReadable):
+    def __init__(self, prefix: str, name="") -> None:
+        with self.add_children_as_readables(HintedSignal):
+            self.value = epics_signal_r(float, prefix + "Value")
+        with self.add_children_as_readables(ConfigSignal):
+            self.mode = epics_signal_rw(EnergyMode, prefix + "Mode")
+        super().__init__(name=name)
+# new
+from typing import Annotated as A
+from ophyd_async.core import StandardReadableFormat as Format
+from ophyd_async.epics.core import EpicsDevice, PvSuffix, epics_signal_r, epics_signal_rw
+
+class Sensor(StandardReadable, EpicsDevice):
+    value: A[SignalR[float], PvSuffix("Value"), Format.HINTED_SIGNAL]
+    mode: A[SignalRW[EnergyMode], PvSuffix("Mode"), Format.CONFIG_SIGNAL]
+```

{ophyd_async-0.8.0a2 → ophyd_async-0.8.0a4}/pyproject.toml

@@ -94,7 +94,8 @@ reportMissingImports = false  # Ignore missing stubs in imported modules
 # Run pytest with all our checkers, and don't spam us with massive tracebacks on error
 addopts = """
     --tb=native -vv --strict-markers --doctest-modules
-    --doctest-glob="*.rst" --doctest-glob="*.md" --ignore=docs/examples
+    --doctest-glob="*.rst" --doctest-glob="*.md"
+    --ignore=docs/examples --ignore=src/ophyd_async/epics/signal.py
     """
 # https://iscinumpy.gitlab.io/post/bound-version-constraints/#watch-for-warnings
 filterwarnings = "error"

{ophyd_async-0.8.0a2 → ophyd_async-0.8.0a4}/src/ophyd_async/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.8.0a2'
+__version__ = version = '0.8.0a4'
 __version_tuple__ = version_tuple = (0, 8, 0)

{ophyd_async-0.8.0a2 → ophyd_async-0.8.0a4}/src/ophyd_async/core/__init__.py

@@ -45,7 +45,12 @@ from ._providers import (
     UUIDFilenameProvider,
     YMDPathProvider,
 )
-from ._readable import ConfigSignal, HintedSignal, StandardReadable
+from ._readable import (
+    ConfigSignal,
+    HintedSignal,
+    StandardReadable,
+    StandardReadableFormat,
+)
 from ._signal import (
     Signal,
     SignalR,
@@ -78,6 +83,7 @@ from ._utils import (
     DEFAULT_TIMEOUT,
     CalculatableTimeout,
     Callback,
+    LazyMock,
     NotConnected,
     Reference,
     StrictEnum,
@@ -141,6 +147,7 @@ __all__ = [
     "ConfigSignal",
     "HintedSignal",
     "StandardReadable",
+    "StandardReadableFormat",
     "Signal",
     "SignalR",
     "SignalRW",
@@ -170,6 +177,7 @@ __all__ = [
     "DEFAULT_TIMEOUT",
     "CalculatableTimeout",
     "Callback",
+    "LazyMock",
     "CALCULATE_TIMEOUT",
     "NotConnected",
     "Reference",

{ophyd_async-0.8.0a2 → ophyd_async-0.8.0a4}/src/ophyd_async/core/_device.py

@@ -3,17 +3,15 @@ from __future__ import annotations
 import asyncio
 import sys
 from collections.abc import Coroutine, Iterator, Mapping, MutableMapping
+from functools import cached_property
 from logging import LoggerAdapter, getLogger
 from typing import Any, 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 ._protocol import Connectable
-from ._utils import DEFAULT_TIMEOUT, NotConnected, wait_for_connection
-
-_device_mocks: dict[Device, Mock] = {}
+from ._utils import DEFAULT_TIMEOUT, LazyMock, NotConnected, wait_for_connection
 
 
 class DeviceConnector:
@@ -37,25 +35,23 @@ class DeviceConnector:
         during ``__init__``.
         """
 
-    async def connect(
-        self,
-        device: Device,
-        mock: bool | Mock,
-        timeout: float,
-        force_reconnect: bool,
-    ):
+    async def connect_mock(self, device: Device, mock: LazyMock):
+        # Connect serially, no errors to gather up as in mock mode
+        for name, child_device in device.children():
+            await child_device.connect(mock=mock.child(name))
+
+    async def connect_real(self, device: Device, timeout: float, force_reconnect: bool):
         """Used during ``Device.connect``.
 
         This is called when a previous connect has not been done, or has been
         done in a different mock more. It should connect the Device and all its
         children.
         """
-        coros = {}
-        for name, child_device in device.children():
-            child_mock = getattr(mock, name) if mock else mock  # Mock() or False
-            coros[name] = child_device.connect(
-                mock=child_mock, timeout=timeout, force_reconnect=force_reconnect
-            )
+        # Connect in parallel, gathering up NotConnected errors
+        coros = {
+            name: child_device.connect(timeout=timeout, force_reconnect=force_reconnect)
+            for name, child_device in device.children()
+        }
         await wait_for_connection(**coros)
 
 
@@ -67,14 +63,14 @@ class Device(HasName, Connectable):
     parent: Device | None = None
     # None if connect hasn't started, a Task if it has
     _connect_task: asyncio.Task | None = None
-    # If not None, then this is the mock arg of the previous connect
-    # to let us know if we can reuse an existing connection
-    _connect_mock_arg: bool | None = None
+    # The mock if we have connected in mock mode
+    _mock: LazyMock | None = None
 
     def __init__(
         self, name: str = "", connector: DeviceConnector | None = None
     ) -> None:
         self._connector = connector or DeviceConnector()
+        self._connector.create_children_from_annotations(self)
         self.set_name(name)
 
     @property
@@ -82,10 +78,18 @@ class Device(HasName, Connectable):
         """Return the name of the Device"""
         return self._name
 
+    @cached_property
+    def _child_devices(self) -> dict[str, Device]:
+        return {}
+
     def children(self) -> Iterator[tuple[str, Device]]:
-        for attr_name, attr in self.__dict__.items():
-            if attr_name != "parent" and isinstance(attr, Device):
-                yield attr_name, attr
+        yield from self._child_devices.items()
+
+    @cached_property
+    def log(self) -> LoggerAdapter:
+        return LoggerAdapter(
+            getLogger("ophyd_async.devices"), {"ophyd_async_device_name": self.name}
+        )
 
     def set_name(self, name: str):
         """Set ``self.name=name`` and each ``self.child.name=name+"-child"``.
@@ -96,28 +100,33 @@ class Device(HasName, Connectable):
             New name to set
         """
         self._name = name
-        # Ensure self.log is recreated after a name change
-        self.log = LoggerAdapter(
-            getLogger("ophyd_async.devices"), {"ophyd_async_device_name": self.name}
-        )
+        # Ensure logger is recreated after a name change
+        if "log" in self.__dict__:
+            del self.log
         for child_name, child in self.children():
             child_name = f"{self.name}-{child_name.strip('_')}" if self.name else ""
             child.set_name(child_name)
 
     def __setattr__(self, name: str, value: Any) -> None:
+        # Bear in mind that this function is called *a lot*, so
+        # we need to make sure nothing expensive happens in it...
         if name == "parent":
             if self.parent not in (value, None):
                 raise TypeError(
                     f"Cannot set the parent of {self} to be {value}: "
                     f"it is already a child of {self.parent}"
                 )
-        elif isinstance(value, Device):
+        # ...hence not doing an isinstance check for attributes we
+        # know not to be Devices
+        elif name not in _not_device_attrs and isinstance(value, Device):
             value.parent = self
-        return super().__setattr__(name, value)
+            self._child_devices[name] = value
+        # ...and avoiding the super call as we know it resolves to `object`
+        return object.__setattr__(self, name, value)
 
     async def connect(
         self,
-        mock: bool | Mock = False,
+        mock: bool | LazyMock = False,
         timeout: float = DEFAULT_TIMEOUT,
         force_reconnect: bool = False,
     ) -> None:
@@ -132,26 +141,39 @@ class Device(HasName, Connectable):
         timeout:
             Time to wait before failing with a TimeoutError.
         """
-        uses_mock = bool(mock)
-        can_use_previous_connect = (
-            uses_mock is self._connect_mock_arg
-            and self._connect_task
-            and not (self._connect_task.done() and self._connect_task.exception())
-        )
-        if mock is True:
-            mock = Mock()  # create a new Mock if one not provided
-        if force_reconnect or not can_use_previous_connect:
-            self._connect_mock_arg = uses_mock
-            if self._connect_mock_arg:
-                _device_mocks[self] = mock
-            coro = self._connector.connect(
-                device=self, mock=mock, timeout=timeout, force_reconnect=force_reconnect
+        if mock:
+            # Always connect in mock mode serially
+            if isinstance(mock, LazyMock):
+                # Use the provided mock
+                self._mock = mock
+            elif not self._mock:
+                # Make one
+                self._mock = LazyMock()
+            await self._connector.connect_mock(self, self._mock)
+        else:
+            # Try to cache the connect in real mode
+            can_use_previous_connect = (
+                self._mock is None
+                and self._connect_task
+                and not (self._connect_task.done() and self._connect_task.exception())
             )
-            self._connect_task = asyncio.create_task(coro)
-
-        assert self._connect_task, "Connect task not created, this shouldn't happen"
-        # Wait for it to complete
-        await self._connect_task
+            if force_reconnect or not can_use_previous_connect:
+                self._mock = None
+                coro = self._connector.connect_real(self, timeout, force_reconnect)
+                self._connect_task = asyncio.create_task(coro)
+            assert self._connect_task, "Connect task not created, this shouldn't happen"
+            # Wait for it to complete
+            await self._connect_task
+
+
+_not_device_attrs = {
+    "_name",
+    "_children",
+    "_connector",
+    "_timeout",
+    "_mock",
+    "_connect_task",
+}
 
 
 DeviceT = TypeVar("DeviceT", bound=Device)