Handle errors more gracefully

Problem:
Unclear error display when an illegal_url or bearer token is used.

Solution:
URL with trailing slash will immediately raise an exception.
Illegal client_id and secret will generate an auth token that is None
and this will raise an exception on first use.
Logger handling is now fully documented with examples.
Docs generation fixed (spelling plugin was preventing generation of
html)
Archivist unittests split into smaller files as original exceeded
1000 lines.

Signed-off-by: Paul Hewlett <[email protected]>

Author: eccles

README.rst

@@ -337,6 +337,26 @@ A recommended minimum configuration would be:
         },
     })
 
+For convenience this has been encapsulated in a convenience function :code:`set_logger`
+which should be called before anything else:
+
+.. code:: python
+
+    from archivist.logger import set_logger
+    from archivist.archivist import Archivist
+
+    set_logger("DEBUG")
+    client_id = getenv("ARCHIVIST_CLIENT_ID")
+    client_secret_file = getenv("ARCHIVIST_CLIENT_SECRET_FILENAME")
+    with open(client_secret_file, mode="r", encoding="utf-8") as tokenfile:
+        client_secret = tokenfile.read().strip()
+
+    arch = Archivist(
+        "https://app.rkvst.io",
+        (client_id, client_secret),
+        max_time=300,
+    )
+
 Development
 ===========
 

archivist/archivist.py

@@ -52,6 +52,7 @@
     _parse_response,
     ArchivistBadFieldError,
     ArchivistDuplicateError,
+    ArchivistError,
     ArchivistHeaderError,
     ArchivistNotFoundError,
 )
@@ -131,6 +132,9 @@ def __init__(
             self._client_secret = None
 
         self._expires_at = 0
+        if url.endswith("/"):
+            raise ArchivistError(f"URL {url} has trailing /")
+
         self._url = url
         self._verify = verify
         self._response_ring_buffer = deque(maxlen=self.RING_BUFFER_MAX_LEN)
@@ -187,7 +191,9 @@ def auth(self) -> str:
         """str: authorization token."""
         if self._client_id is not None and self._expires_at < time():
             apptoken = self.appidp.token(self._client_id, self._client_secret)  # type: ignore
-            self._auth = apptoken["access_token"]
+            self._auth = apptoken.get("access_token")
+            if self._auth is None:
+                raise ArchivistError("Auth token from client id,secret is invalid")
             self._expires_at = time() + apptoken["expires_in"] - 10  # fudge factor
             LOGGER.info("Refresh token")
 

archivist/errors.py

@@ -115,7 +115,8 @@ def __description(response):
         return f"{__identity(response)} not found ({status_code})"
 
     text = response.text or ""
-    return f"{text} ({status_code})"
+    url = getattr(response, "url", "")
+    return f"{url}: {text} ({status_code})"
 
 
 def _parse_response(response):

archivist/logger.py

@@ -7,8 +7,6 @@
    urllib3 package.
 
    URL: https://docs.djangoproject.com/en/3.2/topics/logging/
-
-   This code is not used directly by this package... but is used in unittests (if enabled)
 """
 
 # pylint:  disable=missing-docstring
@@ -20,6 +18,13 @@
 
 
 def set_logger(level):
+    """
+    Set logging level
+
+    Args:
+        level (str): Either INFO or DEBUG
+
+    """
     config.dictConfig(
         {
             "version": 1,

docs/Makefile

@@ -18,3 +18,4 @@ help:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(O)

docs/index.rst

@@ -26,6 +26,7 @@
 
    timestamp
    errors
+   logger
    proof_mechanism
 
 Indices and tables

docs/logger.rst

@@ -0,0 +1,29 @@
+
+.. _loggerref:
+
+Logger
+--------------
+
+The first (optional) call from the archivist package is to set the logger.
+
+.. code:: python
+
+    from archivist.logger import set_logger
+    from archivist.archivist import Archivist
+
+    set_logger("DEBUG")
+    client_id = getenv("ARCHIVIST_CLIENT_ID")
+    client_secret_file = getenv("ARCHIVIST_CLIENT_SECRET_FILENAME")
+    with open(client_secret_file, mode="r", encoding="utf-8") as tokenfile:
+        client_secret = tokenfile.read().strip()
+
+    arch = Archivist(
+        "https://app.rkvst.io",
+        (client_id, client_secret),
+        max_time=300,
+    )
+
+
+.. automodule:: archivist.logger
+   :members:
+

examples/create_asset.py

@@ -9,6 +9,7 @@
 from os import getenv
 
 from archivist.archivist import Archivist
+from archivist.logger import set_logger
 from archivist.proof_mechanism import ProofMechanism
 from archivist.utils import get_auth
 
@@ -74,6 +75,10 @@ def main():
     create an example archivist connection and create an asset.
 
     """
+    # optional call to set the logger level for all subsystems. The argumant can
+    # be either "INFO" or "DEBUG". For more sophisticated logging control see the
+    # documentation.
+    set_logger("INFO")
 
     # client id and client secret is obtained from the appidp endpoint - see the
     # application registrations example code in examples/applications_registration.py

examples/create_event.py

@@ -11,6 +11,7 @@
 from os import getenv
 
 from archivist.archivist import Archivist
+from archivist.logger import set_logger
 
 
 def create_event(arch, asset):
@@ -108,6 +109,11 @@ def main():
     the asset and fetch the event.
 
     """
+    # optional call to set the logger level for all subsystems. The argumant can
+    # be either "INFO" or "DEBUG". For more sophisticated logging control see the
+    # documentation.
+    set_logger("DEBUG")
+
     # client id and client secret is obtained from the appidp endpoint - see the
     # application registrations example code in examples/applications_registration.py
     #

functests/execattachments.py

@@ -22,7 +22,7 @@
 # pylint: disable=unused-variable
 
 
-class TestAttachmentstCreate(TestCase):
+class TestAttachmentsCreate(TestCase):
     """
     Test Archivist Attachment Create method
     """