ENH: implementations of 'filter_add', 'filters_get' and 'filter_delete' API

Author: dmgav

src/save_and_restore_api/_api_async.py

@@ -231,6 +231,25 @@ async def compare(self, nodeId, *, tolerance=None, compareMode=None, skipReadbac
         )
         return await self.send_request(method, url, url_params=url_params)
 
+    # =============================================================================================
+    #                     FILTER-CONTROLLER API METHODS
+    # =============================================================================================
+
+    async def filter_add(self, filter, *, auth=None):
+        # Reusing docstrings from the threaded version
+        method, url, params = self._prepare_filter_add(filter=filter)
+        return await self.send_request(method, url, params=params, auth=auth)
+
+    async def filters_get(self):
+        # Reusing docstrings from the threaded version
+        method, url = self._prepare_filters_get()
+        return await self.send_request(method, url)
+
+    async def filter_delete(self, name, *, auth=None):
+        # Reusing docstrings from the threaded version
+        method, url = self._prepare_filter_delete(name=name)
+        return await self.send_request(method, url, auth=auth)
+
     # =============================================================================================
     #                     STRUCTURE-CONTROLLER API METHODS
     # =============================================================================================

src/save_and_restore_api/_api_base.py

@@ -1,6 +1,7 @@
 # import getpass
 import json
 from collections.abc import Mapping
+from urllib.parse import quote
 
 import httpx
 
@@ -345,6 +346,24 @@ def _prepare_compare(self, *, nodeId, tolerance, compareMode, skipReadback):
             url_params = None
         return method, url, url_params
 
+    # =============================================================================================
+    #                     FILTER-CONTROLLER API METHODS
+    # =============================================================================================
+
+    def _prepare_filter_add(self, *, filter):
+        method, url = "PUT", "/filter"
+        params = filter
+        return method, url, params
+
+    def _prepare_filters_get(self):
+        method, url = "GET", "/filters"
+        return method, url
+
+    def _prepare_filter_delete(self, *, name):
+        # URL may contain spaces and special characters
+        method, url = "DELETE", quote(f"/filter/{name}")
+        return method, url
+
     # =============================================================================================
     #                     STRUCTURE-CONTROLLER API METHODS
     # =============================================================================================

src/save_and_restore_api/_api_threads.py

@@ -376,6 +376,37 @@ def compare(self, nodeId, *, tolerance=None, compareMode=None, skipReadback=None
         )
         return self.send_request(method, url, url_params=url_params)
 
+    # =============================================================================================
+    #                     FILTER-CONTROLLER API METHODS
+    # =============================================================================================
+
+    def filter_add(self, filter, *, auth=None):
+        """
+        Add a filter to the list stored in the database.
+
+        API: PUT /filter
+        """
+        method, url, params = self._prepare_filter_add(filter=filter)
+        return self.send_request(method, url, params=params, auth=auth)
+
+    def filters_get(self):
+        """
+        Get the list of all the filters from the database.
+
+        API: GET /filters
+        """
+        method, url = self._prepare_filters_get()
+        return self.send_request(method, url)
+
+    def filter_delete(self, name, *, auth=None):
+        """
+        Delete filter with the given name from the database.
+
+        API: DELETE /filter/{name}
+        """
+        method, url = self._prepare_filter_delete(name=name)
+        return self.send_request(method, url, auth=auth)
+
     # =============================================================================================
     #                     STRUCTURE-CONTROLLER API METHODS
     # =============================================================================================

tests/common.py

@@ -12,6 +12,7 @@
 # Unit tests will create this folder and add nodes only inside this folder.
 # This folder will be deleted after each test to ensure clean state.
 root_folder_node_name = "unit-test-root-folder"
+filter_prefix = "UNITTESTFILTER"
 
 
 def _is_async(library):
@@ -104,6 +105,12 @@ def _clear():
                 for uid in reversed(uids):
                     SR.nodes_delete([uid])
 
+            # Delete all filters
+            filters = SR.filters_get()
+            for f in filters:
+                if f.startswith("filter_prefix"):
+                    SR.filter_delete(f["name"])
+
     _clear()
     yield
     _clear()

tests/test_filter_control.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from save_and_restore_api import SaveRestoreAPI as SaveRestoreAPI_Threads
+from save_and_restore_api.aio import SaveRestoreAPI as SaveRestoreAPI_Async
+
+from .common import (
+    _is_async,
+    _select_auth,
+    base_url,
+    clear_sar,  # noqa: F401
+    filter_prefix,
+)
+
+# =============================================================================================
+#                         TESTS FOR FILTER-CONTROLLER API METHODS
+# =============================================================================================
+
+
+# fmt: off
+@pytest.mark.parametrize("usesetauth", [True, False])
+@pytest.mark.parametrize("library", ["THREADS", "ASYNC"])
+# fmt: on
+def test_filter_add_01(clear_sar, ioc, library, usesetauth):  # noqa: F811
+    """
+    Basic tests for the 'filter_add', 'filters_get' and 'filter_delete' API.
+    """
+    if not _is_async(library):
+        with SaveRestoreAPI_Threads(base_url=base_url, timeout=10) as SR:
+            auth = _select_auth(SR=SR, usesetauth=usesetauth)
+
+            response = SR.filters_get()
+            n_filters_baseline = len(response)
+
+            f1_name = filter_prefix + " Test Filter #01"
+            f2_name = filter_prefix + " Test Filter #02"
+            response = SR.filter_add({"name": f1_name, "filter": "name=ISrc&type=snapshot"}, **auth)
+            response = SR.filter_add({"name": f2_name, "filter": "type=snapshot&tags=TimingTables"}, **auth)
+
+            response = SR.filters_get()
+            assert len(response) == n_filters_baseline + 2
+
+            response = SR.filter_delete(f1_name, **auth)
+            response = SR.filter_delete(f2_name, **auth)
+
+            response = SR.filters_get()
+            assert len(response) == n_filters_baseline
+
+    else:
+        async def testing():
+            async with SaveRestoreAPI_Async(base_url=base_url, timeout=2) as SR:
+                auth = _select_auth(SR=SR, usesetauth=usesetauth)
+
+                response = await SR.filters_get()
+                n_filters_baseline = len(response)
+
+                f1_name = filter_prefix + " Test Filter #01"
+                f2_name = filter_prefix + " Test Filter #02"
+                response = await SR.filter_add(
+                    {"name": f1_name, "filter": "name=ISrc&type=snapshot"}, **auth
+                )
+                response = await SR.filter_add(
+                    {"name": f2_name, "filter": "type=snapshot&tags=TimingTables"}, **auth
+                )
+
+                response = await SR.filters_get()
+                assert len(response) == n_filters_baseline + 2
+
+                response = await SR.filter_delete(f1_name, **auth)
+                response = await SR.filter_delete(f2_name, **auth)
+
+                response = await SR.filters_get()
+                assert len(response) == n_filters_baseline
+
+        asyncio.run(testing())