DOC: additional docstrings

Author: dmgav

container/save-and-restore.yml

@@ -1,6 +1,7 @@
 services:
   saveandrestore:
-    image: ghcr.io/controlsystemstudio/phoebus/service-save-and-restore:v5.0.2
+    image: ghcr.io/controlsystemstudio/phoebus/service-save-and-restore:master
+    # image: ghcr.io/controlsystemstudio/phoebus/service-save-and-restore:v5.0.2
     network_mode: "host"
     # ports:
     #   - "8080:8080"

container/start-save-and-restore.sh

@@ -1,3 +1,4 @@
+#!/usr/bin/env bash
 set -x
 
 python create_env_file.py

ioc/sim_ioc2.py

@@ -83,7 +83,7 @@ async def help(self, what, *, lang=None):
     #                         AUTHENTICATION-CONTROLLER API METHODS
     # =============================================================================================
 
-    async def login(self, *, username=None, password=None):
+    async def login(self, *, username, password):
         # Reusing docstrings from the threaded version
         method, url, body_json = self._prepare_login(username=username, password=password)
         return await self.send_request(method, url, body_json=body_json)

src/save_and_restore_api/_api_async.py

@@ -151,6 +151,11 @@ def info_get(self):
         Returns information about the Save and Restore service.
 
         API: GET /
+
+        Returns
+        -------
+        dict
+            Dictionary that contains service information.
         """
         method, url = self._prepare_info_get()
         return self.send_request(method, url)
@@ -160,6 +165,12 @@ def version_get(self):
         Returns information on the name and current version of the service.
 
         API: GET /verson
+
+        Returns
+        -------
+        str
+            String that contains service name (``service-save-and-restore``) and the service version
+            number.
         """
         method, url = self._prepare_version_get()
         return self.send_request(method, url)
@@ -178,6 +189,18 @@ def search(self, allRequestParams):
         ``nodes`` - a list of matching nodes (not including data).
 
         API: GET /search
+
+        Parameters
+        ----------
+        allRequestParams : dict
+            Dictionary with search parameters, e.g. ``{"name": "test config"}`` or
+            ``{"description": "backup pvs"}``.
+
+        Returns
+        -------
+        dict
+            Dictionary with the following keys: ``hitCount`` - the number of matching nodes,
+            ``nodes`` - a list of matching nodes (not including data).
         """
         method, url, params = self._prepare_search(allRequestParams=allRequestParams)
         return self.send_request(method, url, params=params)
@@ -188,9 +211,16 @@ def search(self, allRequestParams):
 
     def help(self, what, *, lang=None):
         """
-        Download help pages, e.g. /help/SearchHelp
+        Download help pages, e.g. ``/help/SearchHelp``
 
         API: GET /help/{what}?lang={lang}
+
+        Parameters
+        ----------
+        what : str
+            Name of the help page, e.g. ``/help/SearchHelp``.
+        lang : str, optional
+            Language code.
         """
         method, url, params = self._prepare_help(what=what, lang=lang)
         return self.send_request(method, url, params=params)
@@ -199,11 +229,23 @@ def help(self, what, *, lang=None):
     #                         AUTHENTICATION-CONTROLLER API METHODS
     # =============================================================================================
 
-    def login(self, *, username=None, password=None):
+    def login(self, *, username, password):
         """
-        Validate user credentials and return user information.
+        Validate user credentials and return user information. Raises ``HTTPClientError``
+        if the login fails.
 
         API: POST /login
+
+        Parameters
+        ----------
+        username : str
+            User name.
+        password : str
+            User password.
+
+        Returns
+        -------
+        None
         """
         method, url, body_json = self._prepare_login(username=username, password=password)
         return self.send_request(method, url, body_json=body_json)

src/save_and_restore_api/_api_threads.py

@@ -239,19 +239,15 @@ def test_login_01(username, password, roles, library, code):
     if not _is_async(library):
         with SaveRestoreAPI_Threads(base_url=base_url, timeout=2) as SR:
             if code == 200:
-                response = SR.login(username=username, password=password)
-                assert response["userName"] == username
-                assert response["roles"] == roles
+                SR.login(username=username, password=password)
             else:
                 with pytest.raises(SR.HTTPClientError, match=f"{code}"):
                     SR.login(username=username, password=password)
     else:
         async def testing():
             async with SaveRestoreAPI_Async(base_url=base_url, timeout=2) as SR:
                 if code == 200:
-                    response = await SR.login(username=username, password=password)
-                    assert response["userName"] == username
-                    assert response["roles"] == roles
+                    await SR.login(username=username, password=password)
                 else:
                     with pytest.raises(SR.HTTPClientError, match=f"{code}"):
                         await SR.login(username=username, password=password)