Use single autosave kwarg instead of autosave and autosave_fields

Author: jsouter

docs/examples/example_autosave_ioc.py

@@ -7,11 +7,11 @@
 # Create records, set some of them to autosave, also save some of their fields
 
 builder.aOut("AO", autosave=True)
-builder.aIn("AI", autosave_fields=["PREC", "EGU"])
+builder.aIn("AI", autosave=["PREC", "EGU"])
 builder.boolIn("BO")
 builder.WaveformIn("WAVEFORMIN", [0, 0, 0, 0], autosave=True)
-with autosave.Autosave(True, ["LOPR", "HOPR"]):
-    builder.aOut("AUTOMATIC-AO", autosave_fields=["EGU"])
+with autosave.Autosave(["VAL", "LOPR", "HOPR"]):
+    builder.aOut("AUTOMATIC-AO", autosave=["EGU"])
 seconds = builder.longOut("SECONDSRUN", autosave=True)
 
 autosave.configure(

docs/how-to/use-autosave-in-an-ioc.rst

@@ -10,10 +10,12 @@ Example IOC
 .. literalinclude:: ../examples/example_autosave_ioc.py
 
 Records are instantiated as normal and configured for automatic loading and
-periodic saving to a backup file with the keyword arguments ``autosave`` and ``autosave_fields``.
-Records with ``autosave=True`` (``False`` by default) have their
-VAL fields backed up. Additional record fields in a list passed to ``autosave_fields`` will be backed
-up - note that this applies even when ``autosave`` is ``False``.
+periodic saving to a backup file with use of the keyword argument ``autosave``.
+``autosave`` resolves to a list of strings, which are the names of fields to be
+tracked by autosave. By default ``autosave=False``, which disables autosave for that PV.
+Setting ``autosave=True`` is equivalent to passing ``["VAL"]``. Note that ``"VAL"`` must be
+explicitly passed when tracking other fields, e.g. ``["VAL", "LOPR", "HOPR"]``.
+``autosave`` can also accept a single string field name as an argument.
 
 The field values get written into a yaml-formatted file containing key-value pairs.
 By default the keys are the same as the full PV name, including any device name specified
@@ -26,10 +28,11 @@ set to 30.0 by default. The directory must exist, and should be configured with
 read/write permissions for the user running the IOC.
 
 IOC developers should only need to interface with autosave via the :func:`~softioc.autosave.configure()`
-method and the ``autosave`` and ``autosave_fields`` keyword arguments. Alternatively,
+method and the ``autosave`` keyword argument. Alternatively,
 PVs can be instantiated inside the :class:`~softioc.autosave.Autosave()` context manager, which 
-automatically passes the arguments ``autosave`` and ``autosave_fields`` to any PVs created
-inside the context manager. If the PV already has ``autosave_fields`` set, the lists
+automatically passes the ``autosave`` argument to any PVs created
+inside the context manager. If any fields are already specified by the ``autosave`` keyword
+argument of PV's initialisation call the lists
 of fields get combined. All other module members are intended for internal use only.
 
 In normal operation, loading from a backup is performed once during the
@@ -44,7 +47,7 @@ the backup file.
 If autosave is enabled and active, a timestamped copy of the latest existing autosave backup file is created
 when the IOC is restarted, e.g. ``<name>.softsav_240717-095004`` (timestamps are in the format yymmdd-HHMMSS).
 If you only wish to store one backup of the autosave file at a time, ``timestamped_backups=False``
-can be passed to :func:`~softioc.autosave.configure()`, this will create a backup file
+can be passed to :func:`~softioc.autosave.configure()` when it is called, this will create a backup file
 named ``<name>.softsav.bu``. To disable any autosaving, comment out the
 :func:`~softioc.autosave.configure()` call or pass it the keyword argument
 ``enabled=False``.

docs/reference/api.rst

@@ -196,21 +196,21 @@ and stderr streams, is sent directly to the terminal.
     at IOC startup, and no values with be saved to any backup files.
 
     .. seealso::
-        `softioc.builder` for how to designate a field for autosave.
 
-        :ref:`autosave`, the keyword argument used to initialise PVs with the VAL field tracked by autosave.
+        :ref:`autosave`, the builder keyword argument used to designate PV fields for autosave
 
-        `autosave_fields`, the keyword argument used to initialise PVs with designated fields tracked by autosave.
+        :class:`Autosave` for how to add fields to autosave inside a context manager.
 
     ..  class:: Autosave
 
-        ..  method:: __init__(autosave=True, autosave_fields=None)
+        ..  method:: __init__(autosave=True)
 
             To be called as a context manager. Any PVs that are created inside
-            the context manager have the arguments ``autosave`` and ``autosave_fields``
-            passed to them automatically, where ``autosave_fields`` is an optional list of
-            field names. If the PV already has autosave_fields set, the lists of fields get
-            combined.
+            the context manager have the fields passed to the ``autosave`` argument of 
+            the context manager added to autosave tracking. The options for ``autosave``
+            are identical to the ones described in the builder keyword argument
+            :ref:`autosave`. If a PV already has :ref:`autosave` set, the two lists of fields
+            get combined into a single set.
 
 
 
@@ -337,24 +337,24 @@ and stderr streams, is sent directly to the terminal.
     :ref:`autosave`
     ~~~~~~~~~~~~~~~
 
-    Available on all record types. When set to `True` it marks the record
-    value for automatic periodic backing up to a file. Set to `False` by
-    default. When the IOC is restarted and a backup file exists, the value is
+    Available on all record types. 
+    Resoles to a list of string field names, when not empty it marks the record
+    fields for automatic periodic backing up to a file. Set to `False` by
+    default. When the IOC is restarted and a backup file exists, the saved values are
     loaded from this file when :func:`~softioc.builder.LoadDatabase` is called.
-    The saved value takes priority over any value
-    given in `initial_value`. No backing up will occur unless autosave is
+    The saved values takes priority over any initial field value passed to the PV
+    in `initial_value` or ``**fields``. No backing up will occur unless autosave is
     enabled and configured with :func:`~softioc.autosave.configure`.
 
-    .. seealso::
-        :func:`~softioc.autosave.configure` for discussion on how to configure saving.
-
-    .. _autosave_fields:
+    The options for the argument are:
 
-    `autosave_fields`
-    ~~~~~~~~~~~~~~~~~
+        * ``True``, which is equivalent to ``["VAL"]``
+        * ``False``, which is equivalent to ``[]`` and disables autosave tracking for the PV
+        * A list of field names such as ``["VAL", "LOPR", "HOPR"]``, note that ``"VAL"`` must be explicitly provided
+        * A single field name such as ``"EGU"`` which is equivalent to passing ``["EGU"]``.
 
-    A list of strings of record fields belonging to the PV (e.g. ["EGU", "PREC"])
-    to be saved to and loaded from a backup file. Empty by default.
+    .. seealso::
+        :func:`~softioc.autosave.configure` for discussion on how to configure saving.
 
 
 For all of these functions any EPICS database field can be assigned a value by

softioc/autosave.py

@@ -80,49 +80,50 @@ def _shutdown_autosave_thread(worker):
     worker.join()
 
 
-def add_pv_to_autosave(pv, name, kargs):
+def _parse_autosave_fields(fields):
+    if fields is False:
+        return []
+    elif fields is True:
+        return ["VAL"]
+    elif isinstance(fields, list):
+        return fields
+    elif isinstance(fields, str):
+        return [fields]
+    else:
+        raise ValueError(f"Could not parse autosave fields argument: {fields}")
+
+
+def add_pv_to_autosave(pv, name, fields):
     """Configures a PV for autosave
 
     Args:
         pv: a PV object inheriting ProcessDeviceSupportCore
         name: the key by which the PV value is saved to and loaded from a
             backup. This is typically the same as the PV name.
-        kargs: a dictionary containing the optional keys "autosave", a boolean
-            used to add the VAL field to autosave backups, and
-            "autosave_fields", a list of string field names to save to the
-            backup file.
+        fields: used to determine which fields of a PV are tracked by autosave.
+            The allowed options are a single string such as "VAL" or "EGU",
+            a list of strings such as ["VAL", "EGU"], a boolean True which
+            evaluates to ["VAL"] or False to track no fields. If the PV is
+            created inside an Autosave context manager, the fields passed to the
+            context manager are also tracked by autosave.
     """
-
     context = _AutosaveContext()
+    fields = set(_parse_autosave_fields(fields))
     # instantiate to get thread local class variables via instance
-    if context._in_cm:
-        # non-None autosave argument to PV takes priority over context manager
-        autosave_karg = kargs.pop("autosave", None)
-        save_val = (
-            autosave_karg
-            if autosave_karg is not None
-            else context._val
-        )
-        save_fields = (
-            kargs.pop("autosave_fields", []) + context._fields
-        )
-    else:
-        save_val = kargs.pop("autosave", False)
-        save_fields = kargs.pop("autosave_fields", [])
-    if save_val:
-        Autosave._pvs[name] = _AutosavePV(pv)
-    if save_fields:
-        for field in save_fields:
-            Autosave._pvs[f"{name}.{field}"] = _AutosavePV(pv, field)
+    if context._in_cm:  # _fields should always be a list if in context manager
+        fields.update(context._fields)
+    for field in fields:
+        field_name = name if field == "VAL" else f"{name}.{field}"
+        Autosave._pvs[field_name] = _AutosavePV(pv, field)
 
 
 def load_autosave():
     Autosave._load()
 
 
 class _AutosavePV:
-    def __init__(self, pv, field=None):
-        if not field or field == "VAL":
+    def __init__(self, pv, field):
+        if field == "VAL":
             self.get = pv.get
             self.set = pv.set
         else:
@@ -153,45 +154,55 @@ def _get_backup_sav_path():
     sav_path = _get_current_sav_path()
     return sav_path.parent / (sav_path.name + ".bu")
 
+
 class _AutosaveContext(threading.local):
     _instance = None
     _lock = threading.Lock()
-    _val = None
     _fields = None
     _in_cm = False
-    def __new__(cls, val=None, fields=None):
+
+    def __new__(cls, fields=None):
         if cls._instance is None:
             with cls._lock:
                 if not cls._instance:
                     cls._instance = super().__new__(cls)
-        if cls._instance._in_cm:
-            if val is not None:
-                cls._instance._val = val
-            if fields is not None:
-                cls._instance._fields = fields or []
+        if cls._instance._in_cm and fields is not None:
+            cls._instance._fields = fields or []
         return cls._instance
 
     def reset(self):
         self._fields = None
-        self._val = None
         self._in_cm = False
 
+
 class Autosave:
     _pvs = {}
     _last_saved_state = {}
     _last_saved_time = datetime.now()
     _stop_event = threading.Event()
     _loop_started = False
 
-    def __init__(self, autosave=None, autosave_fields=None):
+    def __init__(self, fields=True):
+        """
+        When called as a context manager, any PVs created in the context have
+        the fields provided by the fields argument added to autosave backups.
+
+        Args:
+            fields: a list of string field names to be periodically saved to a
+            backup file, which are loaded from on IOC restart.
+            The allowed options are a single string such as "VAL" or "EGU",
+            a list of strings such as ["VAL", "EGU"], a boolean True which
+            evaluates to ["VAL"] or False to track no additional fields.
+            If the autosave keyword is already specified in a PV's
+            initialisation, the list of fields to track are combined.
+        """
         context = _AutosaveContext()
         if context._in_cm:
             raise RuntimeError(
-                "Can not instantiate Autosave when already in context manager")
-        if autosave is not None:
-            context._val = autosave
-        if autosave_fields is not None:
-            context._fields = autosave_fields
+                "Can not instantiate Autosave when already in context manager"
+            )
+        fields = _parse_autosave_fields(fields)
+        context._fields = fields
 
     def __enter__(self):
         context = _AutosaveContext()

softioc/device.py

@@ -55,7 +55,8 @@ class ProcessDeviceSupportCore(DeviceSupportCore, RecordLookup):
 
     # all record types can support autosave
     def __init__(self, name, **kargs):
-        autosave.add_pv_to_autosave(self, name, kargs)
+        autosave_fields = kargs.pop("autosave", False)
+        autosave.add_pv_to_autosave(self, name, autosave_fields)
         self.__super.__init__(name, **kargs)
 
     # Most subclasses (all except waveforms) define a ctypes constructor for the

softioc/pythonSoftIoc.py

@@ -25,7 +25,7 @@ def __init__(self, builder, device, name, **fields):
         DeviceKeywords = [
             'on_update', 'on_update_name', 'validate', 'always_update',
             'initial_value', '_wf_nelm', '_wf_dtype', 'blocking',
-            'autosave', 'autosave_fields'
+            'autosave'
         ]
         device_kargs = {}
         for keyword in DeviceKeywords:

tests/test_autosave.py

@@ -20,7 +20,6 @@ def reset_autosave_setup_teardown():
     default_tb = autosave.AutosaveConfig.timestamped_backups
     default_pvs = autosave.Autosave._pvs.copy()
     default_state = autosave.Autosave._last_saved_state.copy()
-    default_cm_save_val = autosave._AutosaveContext._val
     default_cm_save_fields = autosave._AutosaveContext._fields
     default_instance = autosave._AutosaveContext._instance
     yield
@@ -32,7 +31,6 @@ def reset_autosave_setup_teardown():
     autosave.Autosave._pvs = default_pvs
     autosave.Autosave._last_saved_state = default_state
     autosave.Autosave._stop_event = threading.Event()
-    autosave._AutosaveContext._val = default_cm_save_val
     autosave._AutosaveContext._fields = default_cm_save_fields
     autosave._AutosaveContext._instance = default_instance
 
@@ -142,8 +140,8 @@ def test_all_record_types_saveable(tmp_path):
 
 
 def test_can_save_fields(tmp_path):
-    builder.aOut("SAVEVAL", autosave=True, autosave_fields=["DISA"])
-    builder.aOut("DONTSAVEVAL", autosave_fields=["SCAN"])
+    builder.aOut("SAVEVAL", autosave=["VAL", "DISA"])
+    builder.aOut("DONTSAVEVAL", autosave=["SCAN"])
     # we need to patch get_field as we can't call builder.LoadDatabase()
     # and softioc.iocInit() in unit tests
     with patch(
@@ -219,11 +217,11 @@ def test_autosave_key_names(tmp_path):
 
 
 def test_context_manager(tmp_path):
-    builder.aOut("MANUAL", autosave=True, autosave_fields=["EGU"])
-    with autosave.Autosave(True, ["PINI"]):
+    builder.aOut("MANUAL", autosave=["VAL", "EGU"])
+    with autosave.Autosave(["VAL", "PINI"]):
         builder.aOut("AUTOMATIC")
         builder.aOut(
-            "AUTOMATIC-OVERRIDDEN", autosave=False, autosave_fields=["SCAN"]
+            "AUTOMATIC-EXTRA-FIELD", autosave=["SCAN"]
         )
     autosave.configure(tmp_path, DEVICE_NAME)
     with patch(
@@ -237,9 +235,9 @@ def test_context_manager(tmp_path):
         assert "MANUAL.EGU" in saved
         assert "AUTOMATIC" in saved
         assert "AUTOMATIC.PINI" in saved
-        assert "AUTOMATIC-OVERRIDDEN" not in saved
-        assert "AUTOMATIC-OVERRIDDEN.SCAN" in saved
-        assert "AUTOMATIC-OVERRIDDEN.PINI" in saved
+        assert "AUTOMATIC-EXTRA-FIELD" in saved
+        assert "AUTOMATIC-EXTRA-FIELD.SCAN" in saved
+        assert "AUTOMATIC-EXTRA-FIELD.PINI" in saved
 
 
 def check_all_record_types_load_properly(device_name, autosave_dir, conn):
@@ -401,9 +399,9 @@ def check_autosave_field_names_contain_device_prefix(
     device_name, tmp_path, conn
 ):
     autosave.configure(tmp_path, device_name, save_period=1)
-    builder.aOut("BEFORE", autosave=True, autosave_fields=["EGU"])
+    builder.aOut("BEFORE", autosave=["VAL", "EGU"])
     builder.SetDeviceName(device_name)
-    builder.aOut("AFTER", autosave=True, autosave_fields=["EGU"])
+    builder.aOut("AFTER", autosave=["VAL", "EGU"])
     builder.LoadDatabase()
     softioc.iocInit()
     time.sleep(2)
@@ -438,7 +436,7 @@ def create_pv_in_thread(name, wait):
     pv_thread_in_cm = threading.Thread(
         target=create_pv_in_thread, args=["PV-FROM-THREAD-DURING", 0])
     pv_thread_before_cm.start()
-    with autosave.Autosave(True, ["EGU"]):
+    with autosave.Autosave(["VAL", "EGU"]):
         builder.aOut("PV-FROM-CM")
         pv_thread_in_cm.start()
         pv_thread_in_cm.join()
@@ -451,9 +449,9 @@ def create_pv_in_thread(name, wait):
 
 def test_nested_context_managers_raises(tmp_path):
     autosave.configure(tmp_path, DEVICE_NAME)
-    with autosave.Autosave(False, ["SCAN"]):
+    with autosave.Autosave(["SCAN"]):
         with pytest.raises(RuntimeError):
-            with autosave.Autosave(True, []):
+            with autosave.Autosave(False):
                 builder.aOut("MY-PV")
         with pytest.raises(RuntimeError):
             autosave.Autosave()