feat: include should_retry and http_status_code properties in all DeepLExceptions

Author: daniel-jones-dev

CHANGELOG.md

@@ -7,7 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ### Added
-* State explicitly that this library supports Python 3.11. 
+* State explicitly that this library supports Python 3.11.
+* Added the `should_retry` and `http_status_code` properties to all exceptions
+  thrown by the library.
 ### Fixed
 * Fix `py` dependency by upgrading `pytest` version to 7.2.0 for Python 3.7+. 
   For Python 3.6 tests `pytest` needs to be added manually.

deepl/exceptions.py

@@ -2,11 +2,28 @@
 # Use of this source code is governed by an MIT
 # license that can be found in the LICENSE file.
 
+from typing import Optional
+
 
 class DeepLException(Exception):
-    """Base class for deepl module exceptions."""
+    """Base class for deepl module exceptions.
 
-    pass
+    :param message: Message describing the error that occurred.
+    :param should_retry: True if the request would normally be retried
+        following this error, otherwise false.
+    :param http_status_code: The HTTP status code in the response, if
+        applicable, otherwise None.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        should_retry: bool = False,
+        http_status_code: Optional[int] = None,
+    ):
+        super().__init__(message)
+        self.should_retry = should_retry
+        self.http_status_code = http_status_code
 
 
 class AuthorizationException(DeepLException):
@@ -37,11 +54,13 @@ class ConnectionException(DeepLException):
 
     def __init__(
         self,
-        message,
-        should_retry=False,
+        message: str,
+        should_retry: bool = False,
     ):
-        super().__init__(message)
-        self.should_retry = should_retry
+        super().__init__(
+            message,
+            should_retry=should_retry,
+        )
 
 
 class DocumentTranslationException(DeepLException):
@@ -51,7 +70,9 @@ class DocumentTranslationException(DeepLException):
     :param document_handle: The document handle of the associated document.
     """
 
-    def __init__(self, message, document_handle):
+    def __init__(
+        self, message: str, document_handle: "DocumentHandle"  # noqa
+    ):
         super().__init__(message)
         self.document_handle = document_handle
 

deepl/translator.py

@@ -558,28 +558,48 @@ def _raise_for_status(
             return
         elif status_code == http.HTTPStatus.FORBIDDEN:
             raise AuthorizationException(
-                f"Authorization failure, check auth_key{message}"
+                f"Authorization failure, check auth_key{message}",
+                http_status_code=status_code,
             )
         elif status_code == self._HTTP_STATUS_QUOTA_EXCEEDED:
             raise QuotaExceededException(
-                f"Quota for this billing period has been exceeded{message}"
+                f"Quota for this billing period has been exceeded{message}",
+                http_status_code=status_code,
             )
         elif status_code == http.HTTPStatus.NOT_FOUND:
             if glossary:
-                raise GlossaryNotFoundException(f"Glossary not found{message}")
-            raise DeepLException(f"Not found, check server_url{message}")
+                raise GlossaryNotFoundException(
+                    f"Glossary not found{message}",
+                    http_status_code=status_code,
+                )
+            raise DeepLException(
+                f"Not found, check server_url{message}",
+                http_status_code=status_code,
+            )
         elif status_code == http.HTTPStatus.BAD_REQUEST:
-            raise DeepLException(f"Bad request{message}")
+            raise DeepLException(
+                f"Bad request{message}", http_status_code=status_code
+            )
         elif status_code == http.HTTPStatus.TOO_MANY_REQUESTS:
             raise TooManyRequestsException(
                 "Too many requests, DeepL servers are currently experiencing "
-                f"high load{message}"
+                f"high load{message}",
+                should_retry=True,
+                http_status_code=status_code,
             )
         elif status_code == http.HTTPStatus.SERVICE_UNAVAILABLE:
             if downloading_document:
-                raise DocumentNotReadyException(f"Document not ready{message}")
+                raise DocumentNotReadyException(
+                    f"Document not ready{message}",
+                    should_retry=True,
+                    http_status_code=status_code,
+                )
             else:
-                raise DeepLException(f"Service unavailable{message}")
+                raise DeepLException(
+                    f"Service unavailable{message}",
+                    should_retry=True,
+                    http_status_code=status_code,
+                )
         else:
             status_name = (
                 http.client.responses[status_code]
@@ -588,7 +608,9 @@ def _raise_for_status(
             )
             raise DeepLException(
                 f"Unexpected status code: {status_code} {status_name}, "
-                f"content: {content}."
+                f"content: {content}.",
+                should_retry=False,
+                http_status_code=status_code,
             )
 
     def _check_valid_languages(