Raise qualified exceptions instead of generic 'Exception'

scraper/src/mindtouch2zim/asset.py

@@ -37,6 +37,18 @@
 WEBP_OPTIONS = WebpMedium().options
 
 
+class S3InvalidCredentialsError(Exception):
+    """Raised when S3 credentials are invalid"""
+
+    pass
+
+
+class S3CacheError(Exception):
+    """Raised when there is a problem with the S3 cache"""
+
+    pass
+
+
 class HeaderData(NamedTuple):
     ident: str  # ~version~ of the URL data to use for comparisons
     content_type: str | None
@@ -111,7 +123,7 @@ def _process_asset_internal(
                             f"Exception while processing asset for {asset_url.value}: "
                             f"{exc}"
                         )
-                        raise Exception(  # noqa: B904
+                        raise OSError(  # noqa: B904
                             f"Asset failure threshold ({self.bad_assets_threshold}) "
                             "reached, stopping execution"
                         )
@@ -195,7 +207,7 @@ def _download_from_s3_cache(
         self, s3_key: str, meta: dict[str, str]
     ) -> BytesIO | None:
         if not self.s3_storage:
-            raise Exception("s3 storage must be set")
+            raise AttributeError("s3 storage must be set")
         try:
             asset_content = BytesIO()
             self.s3_storage.download_matching_fileobj(  # pyright: ignore[reportUnknownMemberType]
@@ -205,19 +217,19 @@ def _download_from_s3_cache(
         except NotFoundError:
             return None
         except Exception as exc:
-            raise Exception(f"Failed to download {s3_key} from S3 cache") from exc
+            raise S3CacheError(f"Failed to download {s3_key} from S3 cache") from exc
 
     def _upload_to_s3_cache(
         self, s3_key: str, meta: dict[str, str], asset_content: BytesIO
     ):
         if not self.s3_storage:
-            raise Exception("s3 storage must be set")
+            raise AttributeError("s3 storage must be set")
         try:
             self.s3_storage.upload_fileobj(  # pyright: ignore[reportUnknownMemberType]
                 key=s3_key, fileobj=asset_content, meta=meta
             )
         except Exception as exc:
-            raise Exception(f"Failed to upload {s3_key} to S3 cache") from exc
+            raise S3CacheError(f"Failed to upload {s3_key} to S3 cache") from exc
 
     def _download_from_online(self, asset_url: HttpUrl) -> BytesIO:
         """Download whole content from online server with retry from scraperlib"""
@@ -284,4 +296,4 @@ def _setup_s3(self):
                 f"  Key ID: {self.s3_storage.params.get('keyid')}"  # pyright: ignore[reportUnknownMemberType]
             )
             logger.error(f"  Public IP: {get_public_ip()}")
-            raise Exception("Invalid S3 credentials")
+            raise S3InvalidCredentialsError("Invalid S3 credentials")

scraper/src/mindtouch2zim/client.py

@@ -20,6 +20,12 @@ class MindtouchParsingError(Exception):
     pass
 
 
+class APITokenRetrievalError(Exception):
+    """Exception raised when failing to retrieve API token to query website API"""
+
+    pass
+
+
 class MindtouchHome(BaseModel):
     home_url: str
     welcome_text_paragraphs: list[str]
@@ -425,15 +431,15 @@ def _get_deki_token_from_home(soup: BeautifulSoup) -> str:
     if not global_settings:
         logger.debug("home content:")
         logger.debug(soup)
-        raise Exception(
+        raise APITokenRetrievalError(
             "Failed to retrieve API token to query website API, missing "
             "mt-global-settings script"
         )
     x_deki_token = json.loads(global_settings.text).get("apiToken", None)
     if not x_deki_token:
         logger.debug("mt-global-settings script content:")
         logger.debug(global_settings.text)
-        raise Exception(
+        raise APITokenRetrievalError(
             "Failed to retrieve API token to query website API, missing apiToken."
         )
     return x_deki_token

scraper/src/mindtouch2zim/html_rewriting.py

@@ -38,7 +38,7 @@ def rewrite_href_src_srcset_attributes(
     if attr_name not in ("href", "src", "srcset") or not attr_value:
         return
     if not isinstance(url_rewriter, HtmlUrlsRewriter):
-        raise Exception("Expecting HtmlUrlsRewriter")
+        raise TypeError("Expecting instance of HtmlUrlsRewriter")
     new_attr_value = None
     if tag in ["a", "area"]:
         rewrite_result = url_rewriter(
@@ -77,7 +77,7 @@ def rewrite_iframe_tags(
     if tag not in ["iframe"]:
         return
     if not isinstance(url_rewriter, HtmlUrlsRewriter):
-        raise Exception("Expecting HtmlUrlsRewriter")
+        raise TypeError("Expecting instance of HtmlUrlsRewriter")
     src = get_attr_value_from(attrs=attrs, name="src")
     if not src:
         logger.warning(f"Empty src found in iframe while rewriting {rewriting_context}")
@@ -185,7 +185,7 @@ def rewrite_img_tags(
     if tag != "img":
         return
     if not isinstance(url_rewriter, HtmlUrlsRewriter):
-        raise Exception("Expecting HtmlUrlsRewriter")
+        raise TypeError("Expecting instance of HtmlUrlsRewriter")
     if not (srcset_value := get_attr_value_from(attrs, "srcset")):
         # simple case, just need to rewrite the src
         src_value = get_attr_value_from(attrs, "src")

scraper/src/mindtouch2zim/processor.py

@@ -407,7 +407,7 @@ def run_with_creator(self, creator: Creator):
             except HTTPError as exc:
                 if exc.response.status_code == HTTPStatus.FORBIDDEN:
                     if page == selected_pages[0]:
-                        raise Exception(
+                        raise PermissionError(
                             "Root page is private, we cannot ZIM it, stopping"
                         ) from None
                     logger.debug(f"Ignoring page {page.id} (private page)")
@@ -417,7 +417,7 @@ def run_with_creator(self, creator: Creator):
         if len(private_pages) == len(selected_pages):
             # we should never get here since we already check fail early if root
             # page is private, but we are better safe than sorry
-            raise Exception("All pages have been ignored, not creating an empty ZIM")
+            raise OSError("All pages have been ignored, not creating an empty ZIM")
         del private_pages
 
         logger.info(f"  Retrieving {len(self.items_to_download)} assets...")