docs: document the document translation changes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: hive-bot

CHANGELOG.md

@@ -70,6 +70,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `translate_text()` accepts `source_lang` and `target_lang` positionally after
   the text, for example `translate_text("Hello", None, "DE")`. Keyword use is
   unchanged; omitting `target_lang` still raises `TypeError`.
+- Added the `document_id` property to `DocumentStatus`, read from the status
+  response of `translate_document_get_status()` (falling back to the handle's
+  document ID).
+- `translate_document()`, `translate_document_from_filepath()` and
+  `translate_document_upload()` now also accept `source_lang` and
+  `target_lang` as positional arguments after the input (and output)
+  arguments, for example `translate_document_upload(file, "EN", "DE")`.
+  Keyword use is unchanged.
 
 ### Changed
 - HTTP 404 responses raise `NotFoundException` instead of `DeepLException`
@@ -89,6 +97,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `download_translation_memory_export()` is now 64 KiB instead of 1 byte, so
   downloads into `output_file` no longer write one byte per call. The written
   content is unchanged; an explicit `chunk_size` still applies.
+- `DocumentStatus.status` is now typed `Union[DocumentStatus.Status, str]`: a
+  status value the API returns that this version does not know is kept as a
+  string instead of raising `ValueError`. Type-checked code that reads
+  `status.status.value` may need an `isinstance(..., DocumentStatus.Status)`
+  guard; `str(status)` returns the status string in both cases.
+- `translate_document_wait_until_done()` now raises `DeepLException` with the
+  API's error message when the document translation fails, instead of
+  returning the `DocumentStatus` with status `error`.
+- `translate_document()` and `translate_document_from_filepath()` now also
+  wrap upload failures in `DocumentTranslationException`, with
+  `document_handle` set to `None` and the original exception as `__cause__`.
+  Invalid arguments still raise `ValueError` or `TypeError`.
 
 ### Deprecated
 - `Translator` is deprecated in favour of `DeepLClient`, which supports all its
@@ -140,6 +160,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `None` in that case.
 - Fixed `translate_text()` raising `IndexError` when the response holds fewer
   translations than texts sent. It now raises `DeepLException`.
+- Fixed `translate_document_get_status()` raising `ValueError` and
+  `translate_document_wait_until_done()` stopping when the API returns a
+  document status this version does not know. `DocumentStatus.status` keeps
+  such a status as a string, and polling continues.
+- Fixed `translate_document()` and `translate_document_from_filepath()`
+  sending `formality=default` when `formality` was not set. It is now sent
+  only when given.
+- Fixed `translate_document_get_status()` and `translate_document_download()`
+  not URL-encoding the document ID in the request path.
+- Fixed `translate_document_upload()` returning an empty `DocumentHandle` when
+  the response lacks `document_id` or `document_key`, and raising
+  `AttributeError` when the response body is not a JSON object. Both now
+  raise `DeepLException`.
+- Fixed the type annotation of `DocumentStatus.error_message`, which is a
+  string, not an integer.
 - Fixed the `DeprecationWarning` messages of `Usage.Detail.limit_exceeded` and
   `Usage.any_limit_exceeded`, which named the replacement instead of the
   deprecated property. They now read "limit_exceeded is deprecated, use

README.md

@@ -310,7 +310,10 @@ functions, the first and second arguments correspond to the input and output
 files respectively.
 
 Just as for the `translate_text()` function, the `source_lang` and
-`target_lang` arguments specify the source and target language codes.
+`target_lang` arguments specify the source and target language codes. They
+may be passed as keywords or positionally after the input and output files,
+for example `translate_document_from_filepath(input_path, output_path, "EN",
+"DE")`.
 
 There are additional optional arguments to control translation, see
 [Document translation options](#document-translation-options) below.
@@ -338,16 +341,17 @@ try:
         )
 
 except deepl.DocumentTranslationException as error:
-    # If an error occurs during document translation after the document was
-    # already uploaded, a DocumentTranslationException is raised. The
-    # document_handle property contains the document handle that may be used to
-    # later retrieve the document from the server, or contact DeepL support.
-    doc_id = error.document_handle.id
-    doc_key = error.document_handle.key
-    print(f"Error after uploading ${error}, id: ${doc_id} key: ${doc_key}")
-except deepl.DeepLException as error:
-    # Errors during upload raise a DeepLException
-    print(error)
+    # If an error occurs during document translation, a
+    # DocumentTranslationException is raised. If the document was already
+    # uploaded, the document_handle property contains the document handle that
+    # may be used to later retrieve the document from the server, or contact
+    # DeepL support. If the upload itself failed, document_handle is None.
+    if error.document_handle is not None:
+        doc_id = error.document_handle.document_id
+        doc_key = error.document_handle.document_key
+        print(f"Error after uploading {error}, id: {doc_id} key: {doc_key}")
+    else:
+        print(f"Error during upload: {error}")
 ```
 
 `translate_document()` and `translate_document_from_filepath()` are convenience
@@ -360,6 +364,15 @@ these steps individually, you can instead use the following functions directly:
   `translate_document_wait_until_done()`), and
 - `translate_document_download()`
 
+`translate_document_get_status()` returns a `DocumentStatus` with the
+`document_id`, `status`, `seconds_remaining`, `billed_characters` and
+`error_message` of the document, and the `done` (translation succeeded) and
+`ok` (translation has not failed) properties. A status value this library
+version does not know is kept as a string in `status`.
+`translate_document_wait_until_done()` polls the status until the translation
+is done and returns the final `DocumentStatus`; if the translation fails it
+raises a `DeepLException` with the API's error message.
+
 `translate_document_download()` writes the translated document to the
 file-like object given as `output_file`, in chunks of `chunk_size` bytes
 (default 64 KiB). Calling it without `output_file` returns the streaming