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

DM-42994: Improve reporting for LTD Keeper errors

.github/workflows/ci.yaml

@@ -24,15 +24,15 @@ jobs:
     timeout-minutes: 5
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: "3.11"
+          python-version: "3.12"
 
       - name: Run pre-commit
-        uses: pre-commit/[email protected].0
+        uses: pre-commit/[email protected].1
 
   test:
 
@@ -46,9 +46,10 @@ jobs:
           - "3.9"
           - "3.10"
           - "3.11"
+          - "3.12"
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Run tox
         uses: lsst-sqre/run-tox@v1
@@ -66,7 +67,7 @@ jobs:
     timeout-minutes: 10
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0 # full history for setuptools_scm
 
@@ -76,7 +77,7 @@ jobs:
       - name: Run tox
         uses: lsst-sqre/run-tox@v1
         with:
-          python-version: "3.11"
+          python-version: "3.12"
           tox-envs: "docs"
           # Add docs-linkcheck when the docs and PyPI package are published
           # tox-envs: "docs,docs-linkcheck"
@@ -105,14 +106,14 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0 # full history for setuptools_scm
 
       - name: Build and publish
         uses: lsst-sqre/build-and-publish-to-pypi@v2
         with:
-          python-version: "3.11"
+          python-version: "3.12"
           upload: false
 
   pypi:
@@ -132,11 +133,11 @@ jobs:
     if: github.event_name == 'release' && github.event.action == 'published'
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0 # full history for setuptools_scm
 
       - name: Build and publish
         uses: lsst-sqre/build-and-publish-to-pypi@v2
         with:
-          python-version: "3.11"
+          python-version: "3.12"

.github/workflows/dependencies.yaml

@@ -11,12 +11,12 @@ jobs:
     timeout-minutes: 10
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Run neophile
         uses: lsst-sqre/run-neophile@v1
         with:
-          python-version: "3.11"
+          python-version: "3.12"
           mode: pr
           types: pre-commit
           app-id: ${{ secrets.NEOPHILE_APP_ID }}

.github/workflows/periodic-ci.yaml

@@ -20,9 +20,10 @@ jobs:
           - "3.9"
           - "3.10"
           - "3.11"
+          - "3.12"
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Run tests in tox
         uses: lsst-sqre/run-tox@v1
@@ -36,12 +37,12 @@ jobs:
     timeout-minutes: 10
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Build docs in tox
         uses: lsst-sqre/run-tox@v1
         with:
-          python-version: "3.11"
+          python-version: "3.12"
           tox-envs: "docs"
           use-cache: false
 
@@ -50,12 +51,12 @@ jobs:
     timeout-minutes: 10
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0 # full history for setuptools_scm
 
       - name: Build and publish
         uses: lsst-sqre/build-and-publish-to-pypi@v2
         with:
-          python-version: "3.11"
+          python-version: "3.12"
           upload: false

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 <!-- scriv-insert-here -->
 
+## 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)
+
+- Removed usage of `pkg_resources` for better compatibility with Python 3.12 environments.
+- Fixed internal typing issues.
+- Updated the GitHub Actions workflows.
+
 ## 0.8.1 (2021-09-27)
 
 - Fix parsing of the `GITHUB_HEAD_REF` environment variable in GitHub Actions.

changelog.d/20240222_160913_jsick_DM_42994.md

@@ -0,0 +1,3 @@
+### New features
+
+- Improved error reporting when requests to LTD Keeper fail.

src/ltdconveyor/keeper/exceptions.py

@@ -1,10 +1,23 @@
-"""Exceptions related to the LTD Keeper.
-"""
+"""Exceptions related to the LTD Keeper."""
 
-__all__ = ("KeeperError",)
+__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/v1/build.py

@@ -114,7 +114,29 @@ 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
@@ -142,4 +164,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/v1/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"]

src/ltdconveyor/keeper/v2/build.py

@@ -117,7 +117,33 @@ def register_build(
     )
 
     if r.status_code != 201:
-        raise KeeperError(r.json())
+        r2 = requests.get(
+            uritemplate.expand(
+                urljoin(base_url, "/v2/orgs/{org}/projects/{p}"),
+                p=project,
+                org=org,
+            ),
+            auth=(keeper_token, ""),
+            headers={"Accept": "application/json"},
+        )
+        if r2.status_code >= 300:
+            raise KeeperError(
+                f"Could not register a new build for the project {project}. "
+                "It's possible that the project is not registered yet. "
+                "Please contact your documentation support team.",
+                r2.status_code,
+                r2.text,
+            )
+
+        raise KeeperError(
+            f"Could not register a new build for the project {project}. "
+            "It's possible that another build is currently underway. Please "
+            "re-run the documentation job in a few minutes. If the problem "
+            "persists, contact your documentation support team",
+            r.status_code,
+            r.text,
+        )
+
     build_info: Dict[str, Any] = r.json()
     logger.debug(
         "Registered a build, org=%s project=%s:\n%s", org, project, build_info
@@ -147,4 +173,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 != 202:
-        raise KeeperError(r)
+        raise KeeperError(
+            f"Could not confirm build upload for {build_url}. "
+            "Contact your documentation support team for help.",
+            r.status_code,
+            r.text,
+        )