ophyd-async 0.9.0a2__py3-none-any.whl → 0.10.0a2__py3-none-any.whl

ophyd_async/tango/core/_tango_transport.py

@@ -1,13 +1,15 @@
 import asyncio
 import functools
+import logging
 import time
 from abc import abstractmethod
 from collections.abc import Callable, Coroutine
 from enum import Enum
-from typing import Any, TypeVar, cast
+from typing import Any, ParamSpec, TypeVar, cast
 
 import numpy as np
-from bluesky.protocols import Descriptor, Reading
+from bluesky.protocols import Reading
+from event_model import DataKey
 
 from ophyd_async.core import (
     AsyncStatus,
@@ -15,6 +17,7 @@ from ophyd_async.core import (
     NotConnected,
     SignalBackend,
     SignalDatatypeT,
+    StrictEnum,
     get_dtype,
     get_unique,
     wait_for_connection,
@@ -37,26 +40,41 @@ from tango.asyncio_executor import (
 )
 from tango.utils import is_array, is_binary, is_bool, is_float, is_int, is_str
 
+from ._converters import (
+    TangoConverter,
+    TangoDevStateArrayConverter,
+    TangoDevStateConverter,
+    TangoEnumArrayConverter,
+    TangoEnumConverter,
+)
+from ._utils import DevStateEnum, get_device_trl_and_attr
+
+logger = logging.getLogger("ophyd_async")
+
 # time constant to wait for timeout
 A_BIT = 1e-5
 
+P = ParamSpec("P")
 R = TypeVar("R")
 
 
 def ensure_proper_executor(
-    func: Callable[..., Coroutine[Any, Any, R]],
-) -> Callable[..., Coroutine[Any, Any, R]]:
+    func: Callable[P, Coroutine[Any, Any, R]],
+) -> Callable[P, Coroutine[Any, Any, R]]:
+    """Ensure decorated method has a proper asyncio executor."""
+
     @functools.wraps(func)
-    async def wrapper(self: Any, *args: Any, **kwargs: Any) -> R:
+    async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
         current_executor: AsyncioExecutor = get_global_executor()  # type: ignore
         if not current_executor.in_executor_context():  # type: ignore
             set_global_executor(AsyncioExecutor())
-        return await func(self, *args, **kwargs)
+        return await func(*args, **kwargs)
 
-    return cast(Callable[..., Coroutine[Any, Any, R]], wrapper)
+    return wrapper
 
 
 def get_python_type(tango_type: CmdArgType) -> tuple[bool, object, str]:
+    """For converting between recieved tango types and python primatives."""
     array = is_array(tango_type)
     if is_int(tango_type, True):
         return array, int, "integer"
@@ -83,48 +101,51 @@ class TangoProxy:
     support_events: bool = True
     _proxy: DeviceProxy
     _name: str
+    _converter: TangoConverter = TangoConverter()
 
     def __init__(self, device_proxy: DeviceProxy, name: str):
         self._proxy = device_proxy
         self._name = name
 
     async def connect(self) -> None:
-        """perform actions after proxy is connected, e.g. checks if signal
-        can be subscribed"""
+        """Perform actions after proxy is connected.
+
+        e.g. check if signal can be subscribed.
+        """
 
     @abstractmethod
     async def get(self) -> object:
-        """Get value from TRL"""
+        """Get value from TRL."""
 
     @abstractmethod
     async def get_w_value(self) -> object:
-        """Get last written value from TRL"""
+        """Get last written value from TRL."""
 
     @abstractmethod
     async def put(
         self, value: object | None, wait: bool = True, timeout: float | None = None
     ) -> AsyncStatus | None:
-        """Put value to TRL"""
+        """Put value to TRL."""
 
     @abstractmethod
     async def get_config(self) -> AttributeInfoEx | CommandInfo:
-        """Get TRL config async"""
+        """Get TRL config async."""
 
     @abstractmethod
     async def get_reading(self) -> Reading:
-        """Get reading from TRL"""
+        """Get reading from TRL."""
 
     @abstractmethod
     def has_subscription(self) -> bool:
-        """indicates, that this trl already subscribed"""
+        """Indicate that this trl already subscribed."""
 
     @abstractmethod
     def subscribe_callback(self, callback: Callback | None):
-        """subscribe tango CHANGE event to callback"""
+        """Subscribe tango CHANGE event to callback."""
 
     @abstractmethod
     def unsubscribe_callback(self):
-        """delete CHANGE event subscription"""
+        """Delete CHANGE event subscription."""
 
     @abstractmethod
     def set_polling(
@@ -134,10 +155,15 @@ class TangoProxy:
         abs_change=None,
         rel_change=None,
     ):
-        """Set polling parameters"""
+        """Set polling parameters."""
+
+    def set_converter(self, converter: "TangoConverter"):
+        self._converter = converter
 
 
 class AttributeProxy(TangoProxy):
+    """Used by the tango transport."""
+
     _callback: Callback | None = None
     _eid: int | None = None
     _poll_task: asyncio.Task | None = None
@@ -163,20 +189,21 @@ class AttributeProxy(TangoProxy):
             pass
 
     @ensure_proper_executor
-    async def get(self) -> Coroutine[Any, Any, object]:
+    async def get(self) -> object:  # type: ignore
         attr = await self._proxy.read_attribute(self._name)
-        return attr.value
+        return self._converter.value(attr.value)
 
     @ensure_proper_executor
-    async def get_w_value(self) -> object:
+    async def get_w_value(self) -> object:  # type: ignore
         attr = await self._proxy.read_attribute(self._name)
-        return attr.w_value
+        return self._converter.value(attr.w_value)
 
     @ensure_proper_executor
-    async def put(
+    async def put(  # type: ignore
         self, value: object | None, wait: bool = True, timeout: float | None = None
     ) -> AsyncStatus | None:
         # TODO: remove the timeout from this as it is handled at the signal level
+        value = self._converter.write_value(value)
         if wait:
             try:
 
@@ -220,14 +247,16 @@ class AttributeProxy(TangoProxy):
             return AsyncStatus(wait_for_reply(rid, timeout))
 
     @ensure_proper_executor
-    async def get_config(self) -> AttributeInfoEx:
+    async def get_config(self) -> AttributeInfoEx:  # type: ignore
         return await self._proxy.get_attribute_config(self._name)
 
     @ensure_proper_executor
-    async def get_reading(self) -> Reading:
+    async def get_reading(self) -> Reading:  # type: ignore
         attr = await self._proxy.read_attribute(self._name)
         reading = Reading(
-            value=attr.value, timestamp=attr.time.totime(), alarm_severity=attr.quality
+            value=self._converter.value(attr.value),
+            timestamp=attr.time.totime(),
+            alarm_severity=attr.quality,
         )
         self._last_reading = reading
         return reading
@@ -290,7 +319,7 @@ class AttributeProxy(TangoProxy):
     def _event_processor(self, event):
         if not event.err:
             reading = Reading(
-                value=event.attr_value.value,
+                value=self._converter.value(event.attr_value.value),
                 timestamp=event.get_date().totime(),
                 alarm_severity=event.attr_value.quality,
             )
@@ -298,10 +327,11 @@ class AttributeProxy(TangoProxy):
                 self._callback(reading)
 
     async def poll(self):
-        """
-        Poll the attribute and call the callback if the value has changed by more
-        than the absolute or relative change. This function is used when an attribute
-        that does not support events is cached or a callback is passed to it.
+        """Poll the attribute and call the callback if the value has changed.
+
+        Only callback if value has changed by more than the absolute or relative
+        change. This function is used when an attribute that does not support
+        events is cached or a callback is passed to it.
         """
         try:
             last_reading = await self.get_reading()
@@ -376,9 +406,7 @@ class AttributeProxy(TangoProxy):
         abs_change: float | None = None,
         rel_change: float | None = 0.1,
     ):
-        """
-        Set the polling parameters.
-        """
+        """Set the polling parameters."""
         self._allow_polling = allow_polling
         self._polling_period = polling_period
         self._abs_change = abs_change
@@ -386,6 +414,8 @@ class AttributeProxy(TangoProxy):
 
 
 class CommandProxy(TangoProxy):
+    """Tango proxy for commands."""
+
     _last_reading: Reading = Reading(value=None, timestamp=0, alarm_severity=0)
 
     def subscribe_callback(self, callback: Callback | None) -> None:
@@ -404,9 +434,10 @@ class CommandProxy(TangoProxy):
         pass
 
     @ensure_proper_executor
-    async def put(
+    async def put(  # type: ignore
         self, value: object | None, wait: bool = True, timeout: float | None = None
     ) -> AsyncStatus | None:
+        value = self._converter.write_value(value)
         if wait:
             try:
 
@@ -416,7 +447,9 @@ class CommandProxy(TangoProxy):
                 task = asyncio.create_task(_put())
                 val = await asyncio.wait_for(task, timeout)
                 self._last_reading = Reading(
-                    value=val, timestamp=time.time(), alarm_severity=0
+                    value=self._converter.value(val),
+                    timestamp=time.time(),
+                    alarm_severity=0,
                 )
             except asyncio.TimeoutError as te:
                 raise TimeoutError(f"{self._name} command failed: Timeout") from te
@@ -432,7 +465,9 @@ class CommandProxy(TangoProxy):
                 start_time = time.time()
                 while True:
                     try:
-                        reply_value = self._proxy.command_inout_reply(rd)
+                        reply_value = self._converter.value(
+                            self._proxy.command_inout_reply(rd)
+                        )
                         self._last_reading = Reading(
                             value=reply_value, timestamp=time.time(), alarm_severity=0
                         )
@@ -452,7 +487,7 @@ class CommandProxy(TangoProxy):
             return AsyncStatus(wait_for_reply(rid, timeout))
 
     @ensure_proper_executor
-    async def get_config(self) -> CommandInfo:
+    async def get_config(self) -> CommandInfo:  # type: ignore
         return await self._proxy.get_command_config(self._name)
 
     async def get_reading(self) -> Reading:
@@ -474,10 +509,11 @@ class CommandProxy(TangoProxy):
 
 
 def get_dtype_extended(datatype) -> object | None:
+    """For converting tango types to numpy datatype formats."""
     # DevState tango type does not have numpy equivalents
     dtype = get_dtype(datatype)
     if dtype == np.object_:
-        if datatype.__args__[1].__args__[0] == DevState:
+        if datatype.__args__[1].__args__[0] in [DevStateEnum, DevState]:
             dtype = CmdArgType.DevState
     return dtype
 
@@ -486,7 +522,8 @@ def get_trl_descriptor(
     datatype: type | None,
     tango_resource: str,
     tr_configs: dict[str, AttributeInfoEx | CommandInfo],
-) -> Descriptor:
+) -> DataKey:
+    """Create a descriptor from a tango resource locator."""
     tr_dtype = {}
     for tr_name, config in tr_configs.items():
         if isinstance(config, AttributeInfoEx):
@@ -544,11 +581,9 @@ def get_trl_descriptor(
                 raise TypeError(f"{tango_resource} has type [{tr_dtype}] not [{dtype}]")
 
         if tr_format == AttrDataFormat.SPECTRUM:
-            return Descriptor(source=tango_resource, dtype="array", shape=[max_x])
+            return DataKey(source=tango_resource, dtype="array", shape=[max_x])
         elif tr_format == AttrDataFormat.IMAGE:
-            return Descriptor(
-                source=tango_resource, dtype="array", shape=[max_y, max_x]
-            )
+            return DataKey(source=tango_resource, dtype="array", shape=[max_y, max_x])
 
     else:
         if tr_dtype in (Enum, CmdArgType.DevState):
@@ -568,14 +603,14 @@ def get_trl_descriptor(
                 #                 f"{tango_resource} has choices {trl_choices} "
                 #                 f"not {choices}"
                 #             )
-            return Descriptor(source=tango_resource, dtype="string", shape=[])
+            return DataKey(source=tango_resource, dtype="string", shape=[])
         else:
             if datatype and not issubclass(tr_dtype, datatype):
                 raise TypeError(
                     f"{tango_resource} has type {tr_dtype.__name__} "
                     f"not {datatype.__name__}"
                 )
-            return Descriptor(source=tango_resource, dtype=tr_dtype_desc, shape=[])
+            return DataKey(source=tango_resource, dtype=tr_dtype_desc, shape=[])
 
     raise RuntimeError(f"Error getting descriptor for {tango_resource}")
 
@@ -583,9 +618,10 @@ def get_trl_descriptor(
 async def get_tango_trl(
     full_trl: str, device_proxy: DeviceProxy | TangoProxy | None, timeout: float
 ) -> TangoProxy:
+    """Get the tango resource locator."""
     if isinstance(device_proxy, TangoProxy):
         return device_proxy
-    device_trl, trl_name = full_trl.rsplit("/", 1)
+    device_trl, trl_name = get_device_trl_and_attr(full_trl)
     trl_name = trl_name.lower()
     if device_proxy is None:
         device_proxy = await AsyncDeviceProxy(device_trl, timeout=timeout)
@@ -607,17 +643,51 @@ async def get_tango_trl(
     if trl_name in all_cmds:
         return CommandProxy(device_proxy, trl_name)
 
-    # If version is below tango 9, then pipes are not supported
-    if device_proxy.info().server_version >= 9:
-        # all pipes can be always accessible with low register
-        all_pipes = [pipe_name.lower() for pipe_name in device_proxy.get_pipe_list()]
-        if trl_name in all_pipes:
-            raise NotImplementedError("Pipes are not supported")
-
     raise RuntimeError(f"{trl_name} cannot be found in {device_proxy.name()}")
 
 
+def make_converter(info: AttributeInfoEx | CommandInfo, datatype) -> TangoConverter:
+    if isinstance(info, AttributeInfoEx):
+        match info.data_type:
+            case CmdArgType.DevEnum:
+                if datatype and issubclass(datatype, StrictEnum):
+                    labels = [e.value for e in datatype]
+                else:  # get from enum_labels metadata
+                    labels = list(info.enum_labels)
+                if info.data_format == AttrDataFormat.SCALAR:
+                    return TangoEnumConverter(labels)
+                elif info.data_format in [
+                    AttrDataFormat.SPECTRUM,
+                    AttrDataFormat.IMAGE,
+                ]:
+                    return TangoEnumArrayConverter(labels)
+            case CmdArgType.DevState:
+                if info.data_format == AttrDataFormat.SCALAR:
+                    return TangoDevStateConverter()
+                elif info.data_format in [
+                    AttrDataFormat.SPECTRUM,
+                    AttrDataFormat.IMAGE,
+                ]:
+                    return TangoDevStateArrayConverter()
+    else:  # command info
+        match info.in_type:
+            case CmdArgType.DevState:
+                return TangoDevStateConverter()
+            case CmdArgType.DevEnum:
+                if datatype and issubclass(datatype, StrictEnum):
+                    labels = [e.value for e in datatype]
+                    return TangoEnumConverter(labels)
+                else:
+                    logger.warning(
+                        "No override enum class provided for Tango enum command"
+                    )
+    # default case return trivial converter
+    return TangoConverter()
+
+
 class TangoSignalBackend(SignalBackend[SignalDatatypeT]):
+    """Tango backend to connect signals over tango."""
+
     def __init__(
         self,
         datatype: type[SignalDatatypeT] | None,
@@ -633,7 +703,7 @@ class TangoSignalBackend(SignalBackend[SignalDatatypeT]):
             write_trl: self.device_proxy,
         }
         self.trl_configs: dict[str, AttributeInfoEx] = {}
-        self.descriptor: Descriptor = {}  # type: ignore
+        self.descriptor: DataKey = {}  # type: ignore
         self._polling: tuple[bool, float, float | None, float | None] = (
             False,
             0.1,
@@ -642,11 +712,12 @@ class TangoSignalBackend(SignalBackend[SignalDatatypeT]):
         )
         self.support_events: bool = True
         self.status: AsyncStatus | None = None
+        self.converter = TangoConverter()  # gets replaced at connect
         super().__init__(datatype)
 
     @classmethod
     def datatype_allowed(cls, dtype: Any) -> bool:
-        return dtype in (int, float, str, bool, np.ndarray, Enum, DevState)
+        return dtype in (int, float, str, bool, np.ndarray, StrictEnum)
 
     def set_trl(self, read_trl: str = "", write_trl: str = ""):
         self.read_trl = read_trl
@@ -687,6 +758,8 @@ class TangoSignalBackend(SignalBackend[SignalDatatypeT]):
             # The same, so only need to connect one
             await self._connect_and_store_config(self.read_trl, timeout)
         self.proxies[self.read_trl].set_polling(*self._polling)  # type: ignore
+        self.converter = make_converter(self.trl_configs[self.read_trl], self.datatype)
+        self.proxies[self.read_trl].set_converter(self.converter)  # type: ignore
         self.descriptor = get_trl_descriptor(
             self.datatype, self.read_trl, self.trl_configs
         )
@@ -698,13 +771,14 @@ class TangoSignalBackend(SignalBackend[SignalDatatypeT]):
         put_status = await self.proxies[self.write_trl].put(value, wait, timeout)  # type: ignore
         self.status = put_status
 
-    async def get_datakey(self, source: str) -> Descriptor:
+    async def get_datakey(self, source: str) -> DataKey:
         return self.descriptor
 
     async def get_reading(self) -> Reading[SignalDatatypeT]:
         if self.proxies[self.read_trl] is None:
             raise NotConnected(f"Not connected to {self.read_trl}")
-        return await self.proxies[self.read_trl].get_reading()  # type: ignore
+        reading = await self.proxies[self.read_trl].get_reading()  # type: ignore
+        return reading
 
     async def get_value(self) -> SignalDatatypeT:
         if self.proxies[self.read_trl] is None:
@@ -712,7 +786,8 @@ class TangoSignalBackend(SignalBackend[SignalDatatypeT]):
         proxy = self.proxies[self.read_trl]
         if proxy is None:
             raise NotConnected(f"Not connected to {self.read_trl}")
-        return cast(SignalDatatypeT, await proxy.get())
+        value = await proxy.get()
+        return cast(SignalDatatypeT, value)
 
     async def get_setpoint(self) -> SignalDatatypeT:
         if self.proxies[self.write_trl] is None:
@@ -720,7 +795,8 @@ class TangoSignalBackend(SignalBackend[SignalDatatypeT]):
         proxy = self.proxies[self.write_trl]
         if proxy is None:
             raise NotConnected(f"Not connected to {self.write_trl}")
-        return cast(SignalDatatypeT, await proxy.get_w_value())
+        w_value = await proxy.get_w_value()
+        return cast(SignalDatatypeT, w_value)
 
     def set_callback(self, callback: Callback | None) -> None:
         if self.proxies[self.read_trl] is None:

ophyd_async/tango/core/_utils.py

@@ -0,0 +1,47 @@
+import re
+
+from ophyd_async.core import StrictEnum
+
+
+class DevStateEnum(StrictEnum):
+    ON = "ON"
+    OFF = "OFF"
+    CLOSE = "CLOSE"
+    OPEN = "OPEN"
+    INSERT = "INSERT"
+    EXTRACT = "EXTRACT"
+    MOVING = "MOVING"
+    STANDBY = "STANDBY"
+    FAULT = "FAULT"
+    INIT = "INIT"
+    RUNNING = "RUNNING"
+    ALARM = "ALARM"
+    DISABLE = "DISABLE"
+    UNKNOWN = "UNKNOWN"
+
+
+def get_full_attr_trl(device_trl: str, attr_name: str):
+    device_parts = device_trl.split("#", 1)
+    # my/device/name#dbase=no splits into my/device/name and dbase=no
+    full_trl = device_parts[0] + "/" + attr_name
+    if len(device_parts) > 1:
+        full_trl += "#" + device_parts[1]
+    return full_trl
+
+
+def get_device_trl_and_attr(name: str):
+    # trl can have form:
+    #   <protocol://><server:host/>domain/family/member/attr_name<#dbase=no>
+    # e.g. tango://127.0.0.1:8888/test/nodb/test#dbase=no
+    re_str = (
+        r"([\.a-zA-Z0-9_-]*://)?([\.a-zA-Z0-9_-]+:[0-9]+/)?"
+        r"([^#/]+/[^#/]+/[^#/]+/)([^#/]+)(#dbase=[a-z]+)?"
+    )
+    search = re.search(re_str, name)
+    if not search:
+        raise ValueError(f"Could not parse device and attribute from trl {name}")
+    groups = [part if part else "" for part in search.groups()]
+    attr = groups.pop(3)  # extract attr name from groups
+    groups[2] = groups[2].removesuffix("/")  # remove trailing slash from device name
+    device = "".join(groups)
+    return device, attr

ophyd_async/tango/{sim → demo}/_counter.py

@@ -6,6 +6,8 @@ from ophyd_async.tango.core import TangoPolling, TangoReadable
 
 
 class TangoCounter(TangoReadable):
+    """Tango counting device."""
+
     # Enter the name and type of the signals you want to use
     # If the server doesn't support events, the TangoPolling annotation gives
     # the parameters for ophyd to poll instead

ophyd_async/tango/{sim → demo}/_detector.py

@@ -11,6 +11,8 @@ from ._mover import TangoMover
 
 
 class TangoDetector(StandardReadable):
+    """For use with tango detector devices."""
+
     def __init__(self, mover_trl: str, counter_trls: list[str], name=""):
         # A detector device may be composed of tango sub-devices
         self.mover = TangoMover(mover_trl)

ophyd_async/tango/{sim → demo}/_mover.py

@@ -17,17 +17,18 @@ from ophyd_async.core import (
     wait_for_value,
 )
 from ophyd_async.core import StandardReadableFormat as Format
-from ophyd_async.tango.core import TangoPolling, TangoReadable
-from tango import DevState
+from ophyd_async.tango.core import DevStateEnum, TangoPolling, TangoReadable
 
 
 class TangoMover(TangoReadable, Movable, Stoppable):
+    """Tango moving device."""
+
     # Enter the name and type of the signals you want to use
     # If the server doesn't support events, the TangoPolling annotation gives
     # the parameters for ophyd to poll instead
     position: A[SignalRW[float], TangoPolling(0.1, 0.1, 0.1)]
     velocity: A[SignalRW[float], TangoPolling(0.1, 0.1, 0.1)]
-    state: A[SignalR[DevState], TangoPolling(0.1)]
+    state: A[SignalR[DevStateEnum], TangoPolling(0.1)]
     # If a tango name clashes with a bluesky verb, add a trailing underscore
     stop_: SignalX
 
@@ -56,7 +57,7 @@ class TangoMover(TangoReadable, Movable, Stoppable):
         await self.position.set(value, wait=False, timeout=timeout)
 
         move_status = AsyncStatus(
-            wait_for_value(self.state, DevState.ON, timeout=timeout)
+            wait_for_value(self.state, DevStateEnum.ON, timeout=timeout)
         )
 
         try:

ophyd_async/tango/{sim → demo}/_tango/_servers.py

@@ -8,6 +8,8 @@ from tango.server import Device, attribute, command
 
 
 class DemoMover(Device):
+    """Demo tango moving device."""
+
     green_mode = GreenMode.Asyncio
     _position = 0.0
     _setpoint = 0.0
@@ -65,6 +67,8 @@ class DemoMover(Device):
 
 
 class DemoCounter(Device):
+    """Demo tango counting device."""
+
     green_mode = GreenMode.Asyncio
     _counts = 0
     _sample_time = 1.0

ophyd_async/tango/testing/__init__.py

@@ -0,0 +1,6 @@
+from ._one_of_everything import (
+    ExampleStrEnum,
+    OneOfEverythingTangoDevice,
+)
+
+__all__ = ["ExampleStrEnum", "OneOfEverythingTangoDevice"]