ENH: implementation of the 'help' API

Author: dmgav

src/save_and_restore_api/_api_async.py

@@ -63,6 +63,15 @@ async def search(self, allRequestParams):
         method, url, url_params = self._prepare_search(allRequestParams=allRequestParams)
         return await self.send_request(method, url, url_params=url_params)
 
+    # =============================================================================================
+    #                         HELP-RESOURCE API METHODS
+    # =============================================================================================
+
+    async def help(self, what, *, lang=None):
+        # Reusing docstrings from the threaded version
+        method, url, url_params = self._prepare_help(what=what, lang=lang)
+        return await self.send_request(method, url, url_params=url_params)
+
     # =============================================================================================
     #                         AUTHENTICATION-CONTROLLER API METHODS
     # =============================================================================================

src/save_and_restore_api/_api_base.py

@@ -185,6 +185,15 @@ def _prepare_search(self, *, allRequestParams):
         url_params = allRequestParams
         return method, url, url_params
 
+    # =============================================================================================
+    #                         HELP-RESOURCE API METHODS
+    # =============================================================================================
+
+    def _prepare_help(self, *, what, lang):
+        method, url = "GET", f"/help/{what}"
+        url_params = {"lang": lang} if lang else None
+        return method, url, url_params
+
     # =============================================================================================
     #                         AUTHENTICATION-CONTROLLER API METHODS
     # =============================================================================================

src/save_and_restore_api/_api_threads.py

@@ -79,6 +79,19 @@ def search(self, allRequestParams):
         method, url, url_params = self._prepare_search(allRequestParams=allRequestParams)
         return self.send_request(method, url, url_params=url_params)
 
+    # =============================================================================================
+    #                         HELP-RESOURCE API METHODS
+    # =============================================================================================
+
+    def help(self, what, *, lang=None):
+        """
+        Download help pages, e.g. /help/SearchHelp
+
+        API: GET /help/{what}?lang={lang}
+        """
+        method, url, url_params = self._prepare_help(what=what, lang=lang)
+        return self.send_request(method, url, url_params=url_params)
+
     # =============================================================================================
     #                         AUTHENTICATION-CONTROLLER API METHODS
     # =============================================================================================

tests/test_misc.py

@@ -191,6 +191,32 @@ async def testing():
 
         asyncio.run(testing())
 
+# =============================================================================================
+#                         HELP-RESOURCE API METHODS
+# =============================================================================================
+
+# fmt: off
+@pytest.mark.parametrize("library", ["THREADS", "ASYNC"])
+# fmt: on
+def test_help_01(library):
+    """
+    Tests for the 'help' API.
+    """
+    if not _is_async(library):
+        with SaveRestoreAPI_Threads(base_url=base_url, timeout=2) as SR:
+            response = SR.help(what="SearchHelp")
+            isinstance(response, str)
+            assert "Save-and-restore Search Help Reference" in response
+
+    else:
+        async def testing():
+            async with SaveRestoreAPI_Async(base_url=base_url, timeout=2) as SR:
+                response = await SR.help(what="SearchHelp")
+                isinstance(response, str)
+                assert "Save-and-restore Search Help Reference" in response
+
+        asyncio.run(testing())
+
 
 # =============================================================================================
 #                         TESTS FOR AUTHENTICATION-CONTROLLER API METHODS