Merge pull request #66 from lsst-sqre/tickets/DM-42994

DM-42994: Improve messages for LTD Keeper-related errors (for 0.8.3 release)

CHANGELOG.rst

@@ -2,6 +2,11 @@
 Change log
 ##########
 
+0.8.3 (2024-02-22)
+==================
+
+- Improved error reporting from LTD Keeper API responses for common scenarios and direct the user to contact dm-docs-support on the LSSTC Slack.
+
 0.8.2 (2024-02-22)
 ==================
 

src/ltdconveyor/keeper/build.py

@@ -66,7 +66,28 @@ def register_build(
     )
 
     if r.status_code != 201:
-        raise KeeperError(r.json())
+        r2 = requests.get(
+            uritemplate.expand(urljoin(host, "/products/{p}"), p=product),
+            auth=(keeper_token, ""),
+            headers={"Accept": "application/vnd.ltdkeeper.v2+json"},
+        )
+        if r2.status_code >= 300:
+            raise KeeperError(
+                f"Could not register a new build for the project {product}. "
+                "It's possible that the project is not registered yet. Please "
+                "contact #dm-docs-support on Slack.",
+                r2.status_code,
+                r2.text,
+            )
+
+        raise KeeperError(
+            f"Could not register a new build for the project {product}. "
+            "It's possible that another build is currently underway. Please "
+            "re-run the documentation job in a few minutes. If the problem "
+            "persists, contact #dm-docs-support on Slack.",
+            r.status_code,
+            r.text,
+        )
     build_info: Dict[str, Any] = r.json()
     logger.debug("Registered a build for product %s:\n%s", product, build_info)
     return build_info
@@ -94,4 +115,9 @@ def confirm_build(build_url: str, keeper_token: str) -> None:
 
     r = requests.patch(build_url, auth=(keeper_token, ""), json=data)
     if r.status_code != 200:
-        raise KeeperError(r)
+        raise KeeperError(
+            f"Could not confirm build upload for {build_url}. "
+            "Contact #dm-docs-support on Slack",
+            r.status_code,
+            r.text,
+        )

src/ltdconveyor/keeper/exceptions.py

@@ -1,10 +1,23 @@
-"""Exceptions related to the LTD Keeper.
-"""
+"""Exceptions related to the LTD Keeper."""
 
 __all__ = ("KeeperError",)
 
+from typing import Optional
+
 from ..exceptions import ConveyorError
 
 
 class KeeperError(ConveyorError):
     """Error raised because of issues using the LTD Keeper API."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        body: Optional[str] = None,
+    ):
+        if status_code is not None:
+            message = f"(LTD status code: {status_code})\n\n{message}"
+        if body is not None:
+            message = f"{body}\n\n{message}"
+        super().__init__(message)

src/ltdconveyor/keeper/login.py

@@ -35,8 +35,6 @@ def get_keeper_token(host: str, username: str, password: str) -> str:
     r = requests.get(token_endpoint, auth=(username, password))
     if r.status_code != 200:
         raise KeeperError(
-            "Could not authenticate to {0}: error {1:d}\n{2}".format(
-                host, r.status_code, r.json()
-            )
+            f"Could not authenticate to {host}", r.status_code, r.text
         )
     return r.json()["token"]