From c9e73aa1ce36ed753cc210ec09d947fd0a945231 Mon Sep 17 00:00:00 2001 From: Relm-Arrowny Date: Wed, 17 Apr 2024 15:42:57 +0000 Subject: [PATCH] adding docstrings --- src/ophyd_async/core/signal.py | 76 +++++++++++++++++++++++++++------- tests/core/test_signal.py | 33 ++++++++------- 2 files changed, 80 insertions(+), 29 deletions(-) diff --git a/src/ophyd_async/core/signal.py b/src/ophyd_async/core/signal.py index 567694425e..6944fdb9e0 100644 --- a/src/ophyd_async/core/signal.py +++ b/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) diff --git a/tests/core/test_signal.py b/tests/core/test_signal.py index f0d5559553..9567fe4223 100644 --- a/tests/core/test_signal.py +++ b/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,16 +180,20 @@ 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 @@ -196,8 +201,8 @@ async def test_assert_configuration(sim_readable: DummyReadable): 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)