Add error_message to DocumentStatus, improve DocumentTranslationException message

Author: daniel-jones-dev

CHANGELOG.md

@@ -5,6 +5,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [Unreleased]
+### Added
+* Add `error_message` property to `DocumentStatus`, describing the error in case of document translation failure.
+### Changed
+### Deprecated
+### Removed
+### Fixed
+### Security
+
+
 ## [1.5.1] - 2022-04-11
 ### Fixed
 * Fix bug in CLI languages command causing some target languages to be omitted.
@@ -138,6 +148,7 @@ Version increased to avoid conflicts with old packages on PyPI.
 Initial version.
 
 
+[Unreleased]: https://github.com/DeepLcom/deepl-python/compare/v1.5.1...HEAD
 [1.5.1]: https://github.com/DeepLcom/deepl-python/compare/v1.5.0...v1.5.1
 [1.5.0]: https://github.com/DeepLcom/deepl-python/compare/v1.4.1...v1.5.0
 [1.4.1]: https://github.com/DeepLcom/deepl-python/compare/v1.4.0...v1.4.1

deepl/translator.py

@@ -77,6 +77,8 @@ class DocumentStatus:
         completes in seconds, or None if unknown.
     :param billed_characters: Number of characters billed for this document, or
         None if unknown or before translation is complete.
+    :param error_message: A short description of the error, or None if no error
+        has occurred.
     """
 
     class Status(Enum):
@@ -87,11 +89,16 @@ class Status(Enum):
         ERROR = "error"
 
     def __init__(
-        self, status: Status, seconds_remaining=None, billed_characters=None
+        self,
+        status: Status,
+        seconds_remaining=None,
+        billed_characters=None,
+        error_message=None,
     ):
         self._status = self.Status(status)
         self._seconds_remaining = seconds_remaining
         self._billed_characters = billed_characters
+        self._error_message = error_message
 
     def __str__(self) -> str:
         return self.status.value
@@ -116,6 +123,10 @@ def seconds_remaining(self) -> Optional[int]:
     def billed_characters(self) -> Optional[int]:
         return self._billed_characters
 
+    @property
+    def error_message(self) -> Optional[int]:
+        return self._error_message
+
 
 class GlossaryInfo:
     """Information about a glossary, excluding the entry list.
@@ -850,8 +861,10 @@ def translate_document(
             raise DocumentTranslationException(str(e), handle) from e
 
         if not status.ok:
+            error_message = status.error_message or "unknown error"
             raise DocumentTranslationException(
-                "Error occurred while translating document", handle
+                f"Error occurred while translating document: {error_message}",
+                handle,
             )
 
     def translate_document_upload(
@@ -923,7 +936,10 @@ def translate_document_get_status(
         status = json["status"]
         seconds_remaining = json.get("seconds_remaining", None)
         billed_characters = json.get("billed_characters", None)
-        return DocumentStatus(status, seconds_remaining, billed_characters)
+        error_message = json.get("error_message", None)
+        return DocumentStatus(
+            status, seconds_remaining, billed_characters, error_message
+        )
 
     def translate_document_download(
         self,

tests/test_translate_document.py

@@ -71,7 +71,7 @@ def test_translate_document_with_waiting(
 
 
 @needs_mock_server
-def test_translate_document(
+def test_translate_large_document(
     translator, example_large_document_path, example_large_document_translation
 ):
     with io.BytesIO() as output_file:
@@ -107,12 +107,11 @@ def test_translate_document_formality(
     assert "Wie geht es dir?" == output_document_path.read_text()
 
 
-@needs_mock_server
-def test_document_failure(
-    translator, server, example_document_path, output_document_path
+def test_document_failure_during_translation(
+    translator, example_document_path, output_document_path
 ):
-    server.set_doc_failure(1)
-
+    # Translating text from DE to DE will trigger error
+    example_document_path.write_text(example_text["DE"])
     with pytest.raises(
         deepl.exceptions.DocumentTranslationException,
     ) as exc_info:
@@ -122,6 +121,7 @@ def test_document_failure(
 
     # Ensure that document translation error contains document handle
     exception = exc_info.value
+    assert "Source and target language" in str(exception)
     assert exception.document_handle is not None
     match = re.compile("ID: [0-9A-F]{32}, key: [0-9A-F]{64}")
     assert match.search(str(exception)) is not None