From 3fa51ca5392bee96a8cdaaa36ccadb38242ac9a9 Mon Sep 17 00:00:00 2001 From: Dmitri Gavrilov Date: Mon, 13 Oct 2025 20:25:36 -0400 Subject: [PATCH] DOC: additional docstrings --- container/save-and-restore.yml | 3 +- container/start-save-and-restore.sh | 1 + ioc/sim_ioc2.py | 30 --------------- src/save_and_restore_api/_api_async.py | 2 +- src/save_and_restore_api/_api_threads.py | 48 ++++++++++++++++++++++-- tests/test_misc.py | 8 +--- 6 files changed, 51 insertions(+), 41 deletions(-) delete mode 100644 ioc/sim_ioc2.py diff --git a/container/save-and-restore.yml b/container/save-and-restore.yml index f1c3325..04462bc 100644 --- a/container/save-and-restore.yml +++ b/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" diff --git a/container/start-save-and-restore.sh b/container/start-save-and-restore.sh index a36c9b7..054c791 100755 --- a/container/start-save-and-restore.sh +++ b/container/start-save-and-restore.sh @@ -1,3 +1,4 @@ +#!/usr/bin/env bash set -x python create_env_file.py diff --git a/ioc/sim_ioc2.py b/ioc/sim_ioc2.py deleted file mode 100644 index fc67ef2..0000000 --- a/ioc/sim_ioc2.py +++ /dev/null @@ -1,30 +0,0 @@ -from textwrap import dedent - -from caproto.server import PVGroup, ioc_arg_parser, pvproperty, run - - -class SimpleIOC(PVGroup): - """ - An IOC with three uncoupled read/writable PVs. - - Scalar PVs - ---------- - A, B, C, D, E, F, G, H, I, J (float) - """ - - A = pvproperty(value=1.0, doc="Value A") - B = pvproperty(value=1.0, doc="Value B") - C = pvproperty(value=1.0, doc="Value C") - D = pvproperty(value=1.0, doc="Value D") - E = pvproperty(value=1.0, doc="Value E") - F = pvproperty(value=1.0, doc="Value F") - G = pvproperty(value=1.0, doc="Value G") - H = pvproperty(value=1.0, doc="Value H") - I = pvproperty(value=1.0, doc="Value I") # noqa:E741 - J = pvproperty(value=1.0, doc="Value J") - - -if __name__ == "__main__": - ioc_options, run_options = ioc_arg_parser(default_prefix="simulated:", desc=dedent(SimpleIOC.__doc__)) - ioc = SimpleIOC(**ioc_options) - run(ioc.pvdb, **run_options) diff --git a/src/save_and_restore_api/_api_async.py b/src/save_and_restore_api/_api_async.py index 13a9db6..5d21d04 100644 --- a/src/save_and_restore_api/_api_async.py +++ b/src/save_and_restore_api/_api_async.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) diff --git a/src/save_and_restore_api/_api_threads.py b/src/save_and_restore_api/_api_threads.py index 22e8829..44701e6 100644 --- a/src/save_and_restore_api/_api_threads.py +++ b/src/save_and_restore_api/_api_threads.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) diff --git a/tests/test_misc.py b/tests/test_misc.py index 468f687..c692224 100644 --- a/tests/test_misc.py +++ b/tests/test_misc.py @@ -239,9 +239,7 @@ 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) @@ -249,9 +247,7 @@ def test_login_01(username, password, roles, library, code): 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)