Draft: Asyncio conversion

docs/explanations/what-is-pytac.md

@@ -51,7 +51,7 @@ with EPICS, readback (``pytac.RB``) or setpoint (``pytac.SP``).
 Data may be set to or retrieved from different data sources, from the live
 machine (``pytac.LIVE``) or from a simulator (``pytac.SIM``). By default the
 'live' data source is implemented using
-`Cothread <https://github.com/dls-controls/cothread>`_ to communicate with
+`aioca <https://github.com/dls-controls/aioca>`_ to communicate with
 EPICS, as described above. The 'simulation' data source is left unimplemented,
 as Pytac does not include a simulator. However, ATIP, a module designed to
 integrate the `Accelerator Toolbox <https://github.com/atcollab/at>`_ simulator

docs/tutorials/basic-tutorial.rst

@@ -5,10 +5,10 @@ In this tutorial we will go through some of the most common ways of using pytac.
 The aim is to give you an understanding of the interface and how to find out what
 is available.
 
-The import of the cothread channel access library and epicscorelibs will
+The import of the aioca channel access library and epicscorelibs will
 allow us to get some live values from the Diamond accelerators.
 
-    $ pip install cothread epicscorelibs
+    $ pip install aioca epicscorelibs
 
 These docs are able to be run and tested, but may return different values as
 accelerator conditions will have changed.

pyproject.toml

@@ -15,7 +15,7 @@ description = "Python Toolkit for Accelerator Controls (Pytac) is a Python libra
 dependencies = [
     "numpy",
     "scipy",
-    "cothread",
+    "aioca",
     "epicscorelibs",
 ] # Add project dependencies here, e.g. ["click", "numpy"]
 dynamic = ["version"]
@@ -32,6 +32,7 @@ dev = [
     "pre-commit",
     "pydata-sphinx-theme>=0.12",
     "pytest",
+    "pytest-asyncio>=0.17",
     "pytest-cov",
     "ruff",
     "sphinx-autobuild",
@@ -68,6 +69,8 @@ addopts = """
 filterwarnings = "error"
 # Doctest python code in docs, python code in src docstrings, test functions in tests
 testpaths = "src tests"
+asyncio_mode = "auto"
+
 
 [tool.coverage.run]
 patch = ["subprocess"]
@@ -88,8 +91,9 @@ skipsdist=True
 # Don't create a virtualenv for the command, requires tox-direct plugin
 direct = True
 passenv = *
-allowlist_externals =
+allowlist_externals = 
     pytest
+    pytest-asyncio
     pre-commit
     mypy
     sphinx-build

src/pytac/cothread_cs.py → src/pytac/aioca_cs.py

@@ -1,13 +1,13 @@
 import logging
 
-from cothread.catools import ca_nothing, caget, caput
+from aioca import CANothing, caget, caput
 
 from pytac.cs import ControlSystem
 from pytac.exceptions import ControlSystemException
 
 
-class CothreadControlSystem(ControlSystem):
-    """A control system using cothread to communicate with EPICS.
+class AIOCAControlSystem(ControlSystem):
+    """A control system using aioca to communicate with EPICS.
 
     N.B. this is the default control system. It is used to communicate over
     channel access with the hardware in the ring.
@@ -19,7 +19,7 @@ def __init__(self, timeout=1.0, wait=False):
         self._timeout = timeout
         self._wait = wait
 
-    def get_single(self, pv, throw=True):
+    async def get_single(self, pv, throw=True):
         """Get the value of a given PV.
 
         Args:
@@ -35,16 +35,16 @@ def get_single(self, pv, throw=True):
             ControlSystemException: if it cannot connect to the specified PV.
         """
         try:
-            return caget(pv, timeout=self._timeout, throw=True)
-        except ca_nothing:
+            return await caget(pv, timeout=self._timeout, throw=True)
+        except CANothing:
             error_msg = f"Cannot connect to {pv}."
             if throw:
                 raise ControlSystemException(error_msg)  # noqa: B904
             else:
                 logging.warning(error_msg)
                 return None
 
-    def get_multiple(self, pvs, throw=True):
+    async def get_multiple(self, pvs, throw=True):
         """Get the value for given PVs.
 
         Args:
@@ -59,11 +59,11 @@ def get_multiple(self, pvs, throw=True):
         Raises:
             ControlSystemException: if it cannot connect to one or more PVs.
         """
-        results = caget(pvs, timeout=self._timeout, throw=False)
+        results = await caget(pvs, timeout=self._timeout, throw=False)
         return_values = []
         failures = []
         for result in results:
-            if isinstance(result, ca_nothing):
+            if isinstance(result, CANothing):
                 logging.warning(f"Cannot connect to {result.name}.")
                 if throw:
                     failures.append(result)
@@ -75,7 +75,7 @@ def get_multiple(self, pvs, throw=True):
             raise ControlSystemException(f"{len(failures)} caget calls failed.")
         return return_values
 
-    def set_single(self, pv, value, throw=True):
+    async def set_single(self, pv, value, throw=True):
         """Set the value of a given PV.
 
         Args:
@@ -91,17 +91,17 @@ def set_single(self, pv, value, throw=True):
             ControlSystemException: if it cannot connect to the specified PV.
         """
         try:
-            caput(pv, value, timeout=self._timeout, throw=True, wait=self._wait)
+            await caput(pv, value, timeout=self._timeout, throw=True, wait=self._wait)
             return True
-        except ca_nothing:
+        except CANothing:
             error_msg = f"Cannot connect to {pv}."
             if throw:
                 raise ControlSystemException(error_msg)  # noqa: B904
             else:
                 logging.warning(error_msg)
                 return False
 
-    def set_multiple(self, pvs, values, throw=True):
+    async def set_multiple(self, pvs, values, throw=True):
         """Set the values for given PVs.
 
         Args:
@@ -122,7 +122,9 @@ def set_multiple(self, pvs, values, throw=True):
         """
         if len(pvs) != len(values):
             raise ValueError("Please enter the same number of values as PVs.")
-        status = caput(pvs, values, timeout=self._timeout, throw=False, wait=self._wait)
+        status = await caput(
+            pvs, values, timeout=self._timeout, throw=False, wait=self._wait
+        )
         return_values = []
         failures = []
         for stat in status:

src/pytac/data_source.py

@@ -1,5 +1,7 @@
 """Module containing pytac data source classes."""
 
+import inspect
+
 import pytac
 from pytac.exceptions import DataSourceException, FieldException
 
@@ -189,7 +191,7 @@ def set_unitconv(self, field, uc):
         """
         self._uc[field] = uc
 
-    def get_value(
+    async def get_value(
         self,
         field: str,
         handle: str = pytac.RB,
@@ -225,12 +227,12 @@ def get_value(
         if data_source_type == pytac.DEFAULT:
             data_source_type = self.default_data_source
         data_source = self.get_data_source(data_source_type)
-        value = data_source.get_value(field, handle, throw)
+        value = await data_source.get_value(field, handle, throw)
         return self.get_unitconv(field).convert(
             value, origin=data_source.units, target=units
         )
 
-    def set_value(
+    async def set_value(
         self,
         field: str,
         value: float,
@@ -264,7 +266,7 @@ def set_value(
         value = self.get_unitconv(field).convert(
             value, origin=units, target=data_source.units
         )
-        data_source.set_value(field, value, throw)
+        await data_source.set_value(field, value, throw)
 
 
 class DeviceDataSource(DataSource):
@@ -321,7 +323,7 @@ def get_fields(self):
         """
         return self._devices.keys()
 
-    def get_value(self, field, handle, throw=True):
+    async def get_value(self, field, handle, throw=True):
         """Get the value of a readback or setpoint PV for a field from the
         data_source.
 
@@ -337,9 +339,17 @@ def get_value(self, field, handle, throw=True):
         Raises:
             FieldException: if the device does not have the specified field.
         """
-        return self.get_device(field).get_value(handle, throw)
-
-    def set_value(self, field, value, throw=True):
+        device = self.get_device(field)
+        # TODO some devices dont need to be awaited as they are just retrieving stored
+        # data, but others get data from PVs so do, make this better
+        val = 0
+        if inspect.iscoroutinefunction(device.get_value):
+            val = await device.get_value(handle, throw)
+        else:
+            val = device.get_value(handle, throw)
+        return val
+
+    async def set_value(self, field, value, throw=True):
         """Set the value of a readback or setpoint PV for a field from the
         data_source.
 
@@ -352,4 +362,10 @@ def set_value(self, field, value, throw=True):
         Raises:
             FieldException: if the device does not have the specified field.
         """
-        self.get_device(field).set_value(value, throw)
+        device = self.get_device(field)
+        # TODO some devices dont need to be awaited as they are just setting local
+        # data, but others set data to PVs, so do, make this better
+        if inspect.iscoroutinefunction(device.set_value):
+            await device.set_value(value, throw)
+        else:
+            device.set_value(value, throw)

src/pytac/device.py

@@ -168,7 +168,7 @@ def is_enabled(self):
         """
         return bool(self._enabled)
 
-    def get_value(self, handle, throw=True):
+    async def get_value(self, handle, throw=True):
         """Read the value of a readback or setpoint PV.
 
         Args:
@@ -182,9 +182,9 @@ def get_value(self, handle, throw=True):
         Raises:
             HandleException: if the requested PV doesn't exist.
         """
-        return self._cs.get_single(self.get_pv_name(handle), throw)
+        return await self._cs.get_single(self.get_pv_name(handle), throw)
 
-    def set_value(self, value, throw=True):
+    async def set_value(self, value, throw=True):
         """Set the device value.
 
         Args:
@@ -195,7 +195,7 @@ def set_value(self, value, throw=True):
         Raises:
             HandleException: if no setpoint PV exists.
         """
-        self._cs.set_single(self.get_pv_name(pytac.SP), value, throw)
+        return await self._cs.set_single(self.get_pv_name(pytac.SP), value, throw)
 
     def get_pv_name(self, handle):
         """Get the PV name for the specified handle.
@@ -220,9 +220,6 @@ def get_pv_name(self, handle):
 class PvEnabler:
     """A PvEnabler class to check whether a device is enabled.
 
-    The class will behave like True if the PV value equals enabled_value,
-    and False otherwise.
-
     .. Private Attributes:
            _pv (str): The PV name.
            _enabled_value (str): The value for PV for which the device should
@@ -244,11 +241,11 @@ def __init__(self, pv, enabled_value, cs):
         self._enabled_value = str(int(float(enabled_value)))
         self._cs = cs
 
-    def __bool__(self):
+    async def is_enabled(self):
         """Used to override the 'if object' clause.
 
         Returns:
             bool: True if the device should be considered enabled.
         """
-        pv_value = self._cs.get_single(self._pv)
-        return self._enabled_value == str(int(float(pv_value)))
+        pv_value = await self._cs.get_single(self._pv)
+        return self._enabled_value == str(int(float(pv_value)))  # ???

src/pytac/element.py

@@ -226,7 +226,7 @@ def is_in_family(self, family):
         """
         return family.lower() in self._families
 
-    def get_value(
+    async def get_value(
         self,
         field,
         handle=pytac.RB,
@@ -257,15 +257,15 @@ def get_value(
             FieldException: if the element does not have the specified field.
         """
         try:
-            return self._data_source_manager.get_value(
+            return await self._data_source_manager.get_value(
                 field, handle, units, data_source, throw
             )
         except DataSourceException as e:
             raise DataSourceException(f"{self}: {e}") from e
         except FieldException as e:
             raise FieldException(f"{self}: {e}") from e
 
-    def set_value(
+    async def set_value(
         self,
         field,
         value,
@@ -290,7 +290,9 @@ def set_value(
             FieldException: if the element does not have the specified field.
         """
         try:
-            self._data_source_manager.set_value(field, value, units, data_source, throw)
+            await self._data_source_manager.set_value(
+                field, value, units, data_source, throw
+            )
         except DataSourceException as e:
             raise DataSourceException(f"{self}: {e}") from e
         except FieldException as e: