Deprecate DocumentTranslationException.document_request, use document_handle instead

Author: daniel-jones-dev

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Add support for HTML tag handling in `translate_text()`.
 ### Changed
 ### Deprecated
+* `DocumentTranslationException.document_request` is deprecated, use `document_handle` instead.
 ### Removed
 ### Fixed
 ### Security

deepl/exceptions.py

@@ -28,7 +28,12 @@ class TooManyRequestsException(DeepLException):
 
 
 class ConnectionException(DeepLException):
-    """Connection to the DeepL API failed."""
+    """Connection to the DeepL API failed.
+
+    :param message: Message describing the error that occurred.
+    :param should_retry: True if the request would normally be retried
+        following this error, otherwise false.
+    """
 
     def __init__(
         self,
@@ -40,16 +45,28 @@ def __init__(
 
 
 class DocumentTranslationException(DeepLException):
-    """Error occurred while translating document."""
+    """Error occurred while translating document.
+
+    :param message: Message describing the error that occurred.
+    :param document_handle: The document handle of the associated document.
+    """
 
-    def __init__(self, message, document_request):
+    def __init__(self, message, document_handle):
         super().__init__(message)
-        self.document_request = document_request
+        self.document_handle = document_handle
 
     def __str__(self):
-        return (
-            f"{super().__str__()}, document request: {self.document_request}"
+        return f"{super().__str__()}, document handle: {self.document_handle}"
+
+    @property
+    def document_request(self):
+        """Deprecated, use document_handle instead."""
+        import warnings
+
+        warnings.warn(
+            "document_request is deprecated", DeprecationWarning, stacklevel=2
         )
+        return self.document_handle
 
 
 class GlossaryNotFoundException(DeepLException):

tests/test_translate_document.py

@@ -1,6 +1,7 @@
 # Copyright 2022 DeepL SE (https://www.deepl.com)
 # Use of this source code is governed by an MIT
 # license that can be found in the LICENSE file.
+import re
 
 from .conftest import example_text, needs_mock_server, needs_real_server
 import deepl
@@ -112,16 +113,21 @@ def test_document_failure(
 ):
     server.set_doc_failure(1)
 
-    # Ensure that the document ID and key are printed if an error occurs during
-    # document translation
     with pytest.raises(
         deepl.exceptions.DocumentTranslationException,
-        match="ID: [0-9A-F]{32}, key: [0-9A-F]{64}",
-    ):
+    ) as exc_info:
         translator.translate_document_from_filepath(
             example_document_path, output_document_path, target_lang="DE"
         )
 
+    # Ensure that document translation error contains document handle
+    exception = exc_info.value
+    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
+    # document_request is a deprecated alias for document_handle
+    assert exception.document_request is not None
+
 
 def test_invalid_document(translator, tmpdir):
     tmpdir = pathlib.Path(tmpdir)