ENH: work on CLI tool

Author: dmgav

docs/source/api-reference.rst

@@ -13,6 +13,10 @@ Synchronous Communication with Save-And-Restore Server
 
     SaveRestoreAPI
     SaveRestoreAPI.send_request
+    SaveRestoreAPI.open
+    SaveRestoreAPI.close
+    SaveRestoreAPI.__enter__
+    SaveRestoreAPI.__exit__
 
 Authentication
 **************

pyproject.toml

@@ -29,7 +29,7 @@ dependencies = [
 ]
 
 [project.scripts]
-save-and-restore-upload = "save_and_restore_api.tools.upload:main"
+save-and-restore = "save_and_restore_api.tools.upload:main"
 
 [project.urls]
 Homepage = "https://github.com/dmgav/save-and-restore-api"

src/save_and_restore_api/_api_async.py

@@ -6,22 +6,27 @@
 
 class SaveRestoreAPI(_SaveRestoreAPI_Base):
     def open(self):
+        # Reusing docstrings from the threaded version
         self._client = httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout)
 
     async def close(self):
+        # Reusing docstrings from the threaded version
         await self._client.aclose()
         self._client = None
 
     async def __aenter__(self):
+        # Reusing docstrings from the threaded version
         self.open()
         return self
 
     async def __aexit__(self, exc_type, exc_value, traceback):
+        # Reusing docstrings from the threaded version
         await self.close()
 
     async def send_request(
         self, method, url, *, body_json=None, params=None, headers=None, data=None, timeout=None, auth=None
     ):
+        # Reusing docstrings from the threaded version
         try:
             client_response = None
             kwargs = self._prepare_request(
@@ -326,6 +331,11 @@ async def structure_path_nodes(self, path):
         return await self.send_request(method, url, params=params)
 
 
+SaveRestoreAPI.open.__doc__ = _SaveRestoreAPI_Threads.open.__doc__
+SaveRestoreAPI.close.__doc__ = _SaveRestoreAPI_Threads.close.__doc__
+SaveRestoreAPI.__aenter__.__doc__ = _SaveRestoreAPI_Threads.__enter__.__doc__
+SaveRestoreAPI.__aexit__.__doc__ = _SaveRestoreAPI_Threads.__exit__.__doc__
+
 SaveRestoreAPI.send_request.__doc__ = _SaveRestoreAPI_Threads.send_request.__doc__
 
 SaveRestoreAPI.info_get.__doc__ = _SaveRestoreAPI_Threads.info_get.__doc__

src/save_and_restore_api/_api_base.py

@@ -1,6 +1,5 @@
 # import getpass
 import json
-from collections.abc import Mapping
 from urllib.parse import quote
 
 import httpx
@@ -25,27 +24,16 @@ def __init__(self, msg, request):
         super().__init__(msg)
 
 
-class RequestFailedError(Exception):
-    def __init__(self, request, response):
-        msg = response.get("msg", "") if isinstance(response, Mapping) else str(response)
-        msg = msg or "(no error message)"
-        msg = f"Request failed: {msg}"
-        self.request = request
-        self.response = response
-        super().__init__(msg)
-
-
 class _SaveRestoreAPI_Base:
     RequestParameterError = RequestParameterError
     RequestTimeoutError = RequestTimeoutError
-    RequestFailedError = RequestFailedError
     HTTPRequestError = HTTPRequestError
     HTTPClientError = HTTPClientError
     HTTPServerError = HTTPServerError
 
     ROOT_NODE_UID = "44bef5de-e8e6-4014-af37-b8f6c8a939a2"
 
-    def __init__(self, *, base_url, timeout, request_fail_exceptions=True):
+    def __init__(self, *, base_url, timeout=5.0):
         self._base_url = base_url
         self._timeout = timeout
         self._client = None
@@ -55,15 +43,67 @@ def __init__(self, *, base_url, timeout, request_fail_exceptions=True):
     def auth_gen(username, password):
         """
         Generate and return httpx.BasicAuth object based on username and password.
-        The object can be passed as ``auth`` parameter in API calls.
+        The object can be passed as a value of  ``auth`` parameter in API calls.
+        Explicitly passing the authentication object may be useful if requests
+        are made on behalf of multiple users in the same session. If a single user
+        is authenticated per session, then use ``auth_set()`` to set authentication
+        once.
+
+        Parameters
+        ----------
+        username : str
+            Username.
+        password : str
+            Password.
+
+        Returns
+        -------
+        httpx.BasicAuth
+            Basic authentication object.
+
+        Examples
+        --------
+
+        .. code-block:: python
+
+            from save_and_restore_api import SaveRestoreAPI
+
+            auth = SaveRestoreAPI.auth_gen(username="user", password="userPass")
         """
         return httpx.BasicAuth(username=username, password=password)
 
     def auth_set(self, *, username, password):
         """
-        Configure authentication for the session based on username and password.
-        If the authentication is configured, there is no need to pass the authentication
-        object with each API call.
+        Set authentication for the session. Once the authentication is configured, the
+        authentication object is automatically passed with each API call. Calling
+        this function again overwrites the previous authentication. Use ``auth_clear()``
+        function to clear authentication.
+
+        Parameters
+        ----------
+        username : str
+            Username.
+        password : str
+            Password.
+
+        Returns
+        -------
+        None
+
+        Examples
+        --------
+
+        .. code-block:: python
+
+            from save_and_restore_api import SaveRestoreAPI
+
+            SR = SaveRestoreAPI(base_url="http://localhost:8080/save-restore")
+            SR.auth_set(username="user", password="userPass")
+            # ...........
+            SR.auth_set(username="admin", password="adminPass")
+            # ...........
+            SR.auth_clear()
+
         """
         self._auth = self.auth_gen(username=username, password=password)
 

src/save_and_restore_api/_api_threads.py

@@ -5,17 +5,78 @@
 
 class SaveRestoreAPI(_SaveRestoreAPI_Base):
     def open(self):
-        self._client = httpx.Client(base_url=self._base_url, timeout=self._timeout)
+        """
+        Open HTTP connection to the server. The function creates the HTTP client
+        that is used to send requests to the server.
+
+        Examples
+        --------
+
+        .. code-block:: python
+
+            from save_and_restore_api import SaveRestoreAPI
+
+            SR = SaveRestoreAPI(base_url="http://localhost:8080/save-restore")
+            SR.open()
+            info = SR.info_get()
+            print(f"info={info}")
+            SR.close()
+
+        Async version:
+
+        .. code-block:: python
+
+            from save_and_restore_api.aio import SaveRestoreAPI
+
+            SR = SaveRestoreAPI(base_url="http://localhost:8080/save-restore")
+            await SR.open()
+            info = await SR.info_get()
+            print(f"info={info}")
+            await SR.close()
+        """
+        if self._client is not None:
+            self._client = httpx.Client(base_url=self._base_url, timeout=self._timeout)
 
     def close(self):
-        self._client.close()
-        self._client = None
+        """
+        Close HTTP connection to the server. The function closes the HTTP client.
+        """
+        if self._client is not None:
+            self._client.close()
+            self._client = None
 
     def __enter__(self):
+        """
+        Support for the context manager protocol.
+
+        Examples
+        --------
+
+        .. code-block:: python
+
+            from save_and_restore_api import SaveRestoreAPI
+
+            with SaveRestoreAPI(base_url="http://localhost:8080/save-restore") as SR:
+                info = SR.info_get()
+                print(f"info={info}")
+
+        Async version:
+
+        .. code-block:: python
+
+            from save_and_restore_api.aio import SaveRestoreAPI
+
+            async with SaveRestoreAPI(base_url="http://localhost:8080/save-restore") as SR:
+                info = await SR.info_get()
+                print(f"info={info}")
+        """
         self.open()
         return self
 
     def __exit__(self, exc_type, exc_value, traceback):
+        """
+        Support for the context manager protocol.
+        """
         self.close()
 
     def send_request(
@@ -54,10 +115,12 @@ class constructor is used.
 
         Raises
         ------
-        SaveRestoreAPI.RequestParameterError, SaveRestoreAPI.RequestTimeoutError,
-        SaveRestoreAPI.RequestFailedError, SaveRestoreAPI.HTTPRequestError,
-        SaveRestoreAPI.HTTPClientError, SaveRestoreAPI.HTTPServerError
-
+        RequestParameterError
+            Invalid parameter value or type
+        RequestTimeoutError
+            Communication timeout error
+        HTTPRequestError, HTTPClientError, HTTPServerError
+            Error while processing the request or communicating with the server.
         """
         try:
             client_response = None