Merge pull request #18 from dls-controls/improve-docs

Improve the docs and tests for initially undefined values

Author: coretl

docs/explanations/why-use-pythonIoc.rst

@@ -14,15 +14,15 @@ allows you to write this as:
 .. code-block::
 
     import numpy as np
-    from cothread.catools import caget, camonitor
+    from cothread.catools import camonitor
     from softioc import builder, softioc
 
-    # The PVs we want to average and their initial values
+    # The PVs we want to average and initial values
     PVs = [f"DEVICE{i}:CURRENT" for i in range(100)]
-    values = np.array(caget(PVs))
+    values = np.empty(len(PVs)) * np.nan
 
-    # The PV we want to serve
-    avg = builder.aOut("AVERAGE:CURRENT", np.mean(values))
+    # The PV we want to serve, initially undefined
+    avg = builder.aOut("AVERAGE:CURRENT")
 
     # Start the IOC
     builder.LoadDatabase()
@@ -31,13 +31,22 @@ allows you to write this as:
     # Make a monitor on the PVs to keep the value up to date
     def update_avg(value: float, index: int):
         values[index] = value
-        avg.set(np.mean(values))
+        mean = np.mean(values)
+        # If all PVs have returned a value, set the mean
+        if not np.isnan(mean)
+            avg.set(mean)
 
     camonitor(PVs, update_avg)
 
     # Leave the IOC running with an interactive shell.
     softioc.interactive_ioc(globals())
 
+.. note::
+
+    If using `asyncio` then you would use `aioca.camonitor` instead of
+    `cothread.catools.camonitor`::
+
+        from aioca import camonitor
 
 Dynamically created PVs
 -----------------------

tests/sim_asyncio_ioc.py

@@ -23,7 +23,7 @@ async def callback(value):
         sys.stdout.flush()
         sim_records.t_ai.set(value)
 
-    t_ao = builder.aOut('AO2', initial_value=12.45, on_update=callback)
+    t_ao = builder.aOut('AO2', on_update=callback)
 
     # Run the IOC
     builder.LoadDatabase()

tests/test_asyncio.py

@@ -33,7 +33,7 @@ def asyncio_ioc():
 @pytest.mark.asyncio
 async def test_asyncio_ioc(asyncio_ioc):
     import asyncio
-    from aioca import caget, caput, camonitor, CANothing, _catools
+    from aioca import caget, caput, camonitor, CANothing, _catools, FORMAT_CTRL
     # Unregister the aioca atexit handler as it conflicts with the one installed
     # by cothread. If we don't do this we get a seg fault. This is not a problem
     # in production as we won't mix aioca and cothread, but we do mix them in
@@ -48,7 +48,10 @@ async def test_asyncio_ioc(asyncio_ioc):
     m = camonitor(PV_PREFIX + ":SIN", q.put, notify_disconnect=True)
     assert len(await asyncio.wait_for(q.get(), 1)) == 4
     # AO
-    assert await caget(PV_PREFIX + ":AO2") == 12.45
+    ao_val = await caget(PV_PREFIX + ":AO2", format=FORMAT_CTRL)
+    assert ao_val == 0
+    assert ao_val.severity == 3  # INVALID
+    assert ao_val.status == 17  # UDF
     await caput(PV_PREFIX + ":AO2", 3.56, wait=True)
     await asyncio.sleep(0.1)
     assert await caget(PV_PREFIX + ":AI") == 12.34
@@ -70,7 +73,7 @@ async def test_asyncio_ioc(asyncio_ioc):
     # check closed and output
     assert "%s:SINN.VAL 1024 -> 4" % PV_PREFIX in out
     assert 'update_sin_wf 4' in out
-    assert "%s:AO2.VAL 12.45 -> 3.56" % PV_PREFIX in out
+    assert "%s:AO2.VAL 0 -> 3.56" % PV_PREFIX in out
     assert 'async update 3.56' in out
     assert 'Starting iocInit' in err
     assert 'iocRun: All initialization complete' in err