GHASToolkit errors

src/ghastoolkit/__init__.py

@@ -27,6 +27,8 @@
 """
 
 
+from ghastoolkit.errors import GHASToolkitError, GHASToolkitAuthenticationError
+
 # Octokit
 from ghastoolkit.octokit.github import GitHub
 from ghastoolkit.octokit.repository import Repository

src/ghastoolkit/errors.py

@@ -0,0 +1,41 @@
+# GHASToolkit Errors
+
+
+from typing import List, Optional
+
+
+class GHASToolkitError(Exception):
+    """Base class for GHASToolkit errors."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        docs: Optional[str] = None,
+        permissions: Optional[List[str]] = [],
+    ) -> None:
+        self.message = message
+        self.docs = docs
+        self.permissions = permissions
+
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        msg = ""
+
+        if hasattr(self, "message"):
+            msg = self.message
+        else:
+            msg = "An error occurred"
+
+        if permissions := self.permissions:
+            msg += "\n\nPermissions Required:"
+            for perm in permissions:
+                msg += f"\n- {perm}"
+        if docs := self.docs:
+            msg += f"\n\nFor more information, see: {docs}"
+
+        return msg
+
+
+class GHASToolkitAuthenticationError(GHASToolkitError):
+    """Raised when an authentication error occurs."""

src/ghastoolkit/octokit/octokit.py

@@ -8,6 +8,7 @@
 from requests import Session
 from ratelimit import limits, sleep_and_retry
 
+from ghastoolkit.errors import GHASToolkitAuthenticationError, GHASToolkitError
 from ghastoolkit.octokit.github import GitHub, Repository
 from ghastoolkit.octokit.graphql import QUERIES
 
@@ -19,7 +20,9 @@
 
 __OCTOKIT_PATH__ = os.path.dirname(os.path.realpath(__file__))
 
-__OCTOKIT_ERRORS__ = {401: "Authentication Issue"}
+__OCTOKIT_ERRORS__ = {
+    401: GHASToolkitAuthenticationError("Authentication / Permission Issue")
+}
 
 
 # logger
@@ -195,7 +198,9 @@ def get(
         logger.debug(f"Fetching content from URL :: {url}")
 
         if authenticated and not self.session.headers.get("Authorization"):
-            raise Exception(f"GitHub Token required for this request")
+            raise GHASToolkitAuthenticationError(
+                "GitHub Token required for this request"
+            )
 
         result = []
         params = {}
@@ -221,7 +226,7 @@ def get(
 
                 known_error = __OCTOKIT_ERRORS__.get(response.status_code)
                 if known_error:
-                    raise Exception(known_error)
+                    raise known_error
 
             # Handle errors in the response
             if isinstance(response_json, dict) and response_json.get("message"):
@@ -238,7 +243,7 @@ def get(
                 logger.error(f"Error message from server :: {message}")
                 logger.error(f"Documentation Link :: {docs}")
 
-                raise Exception(f"REST Request failed :: {message}")
+                raise GHASToolkitError(f"REST Request failed :: {message}", docs=docs)
 
             if isinstance(response_json, dict):
                 return response_json