adding docstrings

src/ophyd_async/core/signal.py

@@ -3,12 +3,12 @@
 import asyncio
 import functools
 from typing import (
-    Any,
     AsyncGenerator,
     Awaitable,
     Callable,
     Dict,
     Generic,
+    Mapping,
     Optional,
     Union,
 )
@@ -258,11 +258,25 @@ def set_sim_callback(signal: Signal[T], callback: ReadingValueCallback[T]) -> No
 
 
 async def _verify_readings(
-    func: Callable[[], dict[str, Any] | Awaitable[dict[str, Any]]],
-    expectation: Dict[str, Any],
+    func: Callable[[], dict[str, Reading] | Awaitable[dict[str, Reading]]],
+    expectation: Mapping[str, Reading],
 ) -> None:
-    """Loop thorough dictionary and verify it against
-    a expected dictionary (readable)"""
+    """Take a read/read_configuration function that return a dictionary and
+      compare it with the expected result (expectation)
+
+    Parameters
+    ----------
+    func:
+        read/read_configuration function, call at the start
+        and results is validate with the expectation.
+    expectation:
+        The expected value from the readable/Configurable.
+
+    Notes
+    -----
+    Example usage::
+        await assert_reading(signal, value)
+    """
     if asyncio.iscoroutinefunction(func):
         result = await func()
     else:
@@ -274,36 +288,68 @@ async def _verify_readings(
 
 async def assert_value(signal: SignalR[T], value: T) -> None:
     """Assert a signal value
+
     Parameters
     ----------
     signal:
-        Call get_valueand and compare it with expected value.
+        Call signal.get_value and compare it with expected value.
     value:
-        the expected value from the signal.
+        The expected value from the signal.
 
     Notes
     -----
     Example usage::
-        await assert_reading(signal, value)
+        await _verify_readings(readable.read, reading)
+    Or::
+        await _verify_readings(configurable.read_configuration, configuration)
 
 
     """
     assert await signal.get_value() == value
 
 
-async def assert_reading(
-    readable: Readable, reading: Dict[str, Reading] | dict[str, dict[str, Any]]
-) -> None:
-    """Assert readable by calling_verify_readings"""
+async def assert_reading(readable: Readable, reading: Mapping[str, Reading]) -> None:
+    """Assert readable by calling_verify_readings
+
+    Parameters
+    ----------
+    readable:
+        Call readable.read and compare it with expected reading.
+
+    reading:
+        The expected readings from the readable.
+
+    Notes
+    -----
+    Example usage::
+        await assert_reading(readable, reading)
+
+    """
     await _verify_readings(readable.read, reading)
 
 
 async def assert_configuration(
     configurable: Configurable,
-    configuration: Dict[str, Reading] | dict[str, dict[str, Any]],
+    configuration: Dict[str, Reading],
 ) -> None:
-    """Assert readable generated by configurable.read_configuration
-    using _verify_readings"""
+    """
+    Assert configurable generated by configurable.read_configuration by
+    using _verify_readings
+
+    Parameters
+    ----------
+    configurable:
+        Call configurable.read_configuration and compare it with expected configuration.
+
+    configuration:
+        The expected readings from the configurable.
+
+    Notes
+    -----
+    Example usage::
+        await assert_configuration(configurable configuration)
+
+    """
     await _verify_readings(configurable.read_configuration, configuration)
 
 

tests/core/test_signal.py

@@ -4,6 +4,7 @@
 from unittest.mock import ANY
 
 import pytest
+from bluesky.protocols import Reading
 
 from ophyd_async.core import (
     DeviceCollector,
@@ -144,13 +145,13 @@ async def test_assert_value(sim_signal: SignalRW):
 async def test_assert_reaading(sim_signal: SignalRW):
     set_sim_value(sim_signal, 888)
     dummy_reading = {
-        "sim_signal": {"alarm_severity": 0, "timestamp": ANY, "value": 888}
+        "sim_signal": Reading({"alarm_severity": 0, "timestamp": ANY, "value": 888})
     }
     await assert_reading(sim_signal, dummy_reading)
 
 
 class DummyReadable(StandardReadable):
-    """A demo sensor that produces a scalar value based on X and Y Movers"""
+    """A demo Readable to produce read and config signal"""
 
     def __init__(self, prefix: str, name="") -> None:
         # Define some signals
@@ -179,25 +180,29 @@ async def test_assert_configuration(sim_readable: DummyReadable):
     set_sim_value(sim_readable.mode, "super mode")
     set_sim_value(sim_readable.mode2, "slow mode")
     dummy_config_reading = {
-        "sim_readable-mode": {
-            "alarm_severity": 0,
-            "timestamp": ANY,
-            "value": "super mode",
-        },
-        "sim_readable-mode2": {
-            "alarm_severity": 0,
-            "timestamp": ANY,
-            "value": "slow mode",
-        },
+        "sim_readable-mode": Reading(
+            {
+                "alarm_severity": 0,
+                "timestamp": ANY,
+                "value": "super mode",
+            }
+        ),
+        "sim_readable-mode2": Reading(
+            {
+                "alarm_severity": 0,
+                "timestamp": ANY,
+                "value": "slow mode",
+            }
+        ),
     }
     await assert_configuration(sim_readable, dummy_config_reading)
     # test for none awaitable part of verify
     from ophyd.sim import DetWithConf
 
     something = DetWithConf(name="det")
     dummy_config_reading1 = {
-        "det_c": {"value": 3, "timestamp": ANY},
-        "det_d": {"value": 4, "timestamp": ANY},
+        "det_c": Reading({"value": 3, "timestamp": ANY}),
+        "det_d": Reading({"value": 4, "timestamp": ANY}),
     }
 
     await assert_configuration(something, dummy_config_reading1)