Raise DocumentNotReadyException when attempting to download a document before it has been translated

Author: daniel-jones-dev

CHANGELOG.md

@@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Add `--glossary-id` argument for CLI document command.
 ### Changed
 * Improve README.
+* Raise `DocumentNotReadyException` when attempting to download a document before it has been translated. Previously the
+  base class `DeepLException` was thrown.
 ### Deprecated
 ### Removed
 ### Fixed

deepl/__init__.py

@@ -10,6 +10,7 @@
     AuthorizationException,
     ConnectionException,
     DeepLException,
+    DocumentNotReadyException,
     DocumentTranslationException,
     GlossaryNotFoundException,
     TooManyRequestsException,

deepl/exceptions.py

@@ -54,3 +54,9 @@ class GlossaryNotFoundException(DeepLException):
     """The specified glossary was not found."""
 
     pass
+
+
+class DocumentNotReadyException(DeepLException):
+    """The translation of the specified document is not yet complete."""
+
+    pass

deepl/translator.py

@@ -4,6 +4,7 @@
 
 from . import http_client, util
 from .exceptions import (
+    DocumentNotReadyException,
     GlossaryNotFoundException,
     QuotaExceededException,
     TooManyRequestsException,
@@ -494,6 +495,7 @@ def _raise_for_status(
         content: str,
         json: Optional[dict],
         glossary: bool = False,
+        downloading_document: bool = False,
     ):
         message = ""
         if json is not None and "message" in json:
@@ -522,6 +524,11 @@ def _raise_for_status(
                 "Too many requests, DeepL servers are currently experiencing "
                 f"high load{message}"
             )
+        elif status_code == http.HTTPStatus.SERVICE_UNAVAILABLE:
+            if downloading_document:
+                raise DocumentNotReadyException(f"Document not ready{message}")
+            else:
+                raise DeepLException(f"Service unavailable{message}")
         else:
             status_name = (
                 http.client.responses[status_code]
@@ -939,9 +946,9 @@ def translate_document_download(
             url, data=data, stream=True
         )
 
-        if status_code == http.HTTPStatus.SERVICE_UNAVAILABLE:
-            raise DeepLException("Document not ready for download")
-        self._raise_for_status(status_code, "<file>", json)
+        self._raise_for_status(
+            status_code, "<file>", json, downloading_document=True
+        )
 
         if output_file:
             for chunk in response.iter_content(chunk_size=chunk_size):

tests/test_translate_document.py

@@ -157,7 +157,9 @@ def test_translate_document_low_level(
     assert status.ok and not status.done
 
     # Calling download() before document is ready will fail
-    with pytest.raises(deepl.DeepLException, match="Document not ready"):
+    with pytest.raises(
+        deepl.DocumentNotReadyException, match="Document not ready"
+    ):
         with open(output_document_path, "wb") as output_file:
             translator.translate_document_download(handle, output_file)