feat: add extra_body_parameters to the spoken-terms write methods

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

Author: hive-bot

CHANGELOG.md

@@ -57,7 +57,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `update_spoken_terms()`, `get_spoken_terms_entries()`,
   `replace_spoken_terms_list()`, `delete_spoken_terms()` and
   `delete_spoken_terms_list()`, with the `SpokenTerms`, `SpokenTermsList` and
-  `SpokenTermsEntries` types.
+  `SpokenTermsEntries` types. `create_spoken_terms()`, `update_spoken_terms()`
+  and `replace_spoken_terms_list()` accept `extra_body_parameters`. Collection
+  IDs are URL-encoded in the request path, terms are stripped of leading and
+  trailing whitespace before they are validated and sent, and a malformed
+  response raises `DeepLException`.
 - Added the style profile API (`/v3/style_profiles`) to the `DeepLClient`
   class: `list_style_profiles()`, `create_style_profile()`,
   `get_style_profile()`, `update_style_profile()` and

README.md

@@ -646,7 +646,10 @@ term, then checks it like a glossary term (`validate_glossary_term()`): an
 empty term or one with a control character, such as a newline, raises
 `ValueError`. The API validates the rest (at most 300 characters per list, no
 duplicates). Methods that take a collection accept either its ID or a
-`SpokenTerms` object.
+`SpokenTerms` object. `create_spoken_terms()`, `update_spoken_terms()` and
+`replace_spoken_terms_list()` accept the keyword argument
+`extra_body_parameters`: a dictionary of extra fields to send in the JSON
+request body, replacing fields the library sets with the same key.
 
 ```python
 # Create a collection with an English term list

deepl/deepl_client.py

@@ -730,6 +730,8 @@ def create_spoken_terms(
         self,
         name: str,
         term_lists: List[SpokenTermsEntries],
+        *,
+        extra_body_parameters: Optional[Dict[str, Any]] = None,
     ) -> SpokenTerms:
         """Creates a spoken-terms collection with the given name and term
         lists, one per language. Spoken terms improve the transcription of
@@ -738,18 +740,22 @@ def create_spoken_terms(
         :param name: User-defined name to attach to the collection.
         :param term_lists: List of SpokenTermsEntries, each containing the
             terms of one language.
+        :param extra_body_parameters: (Optional) Additional key/value pairs
+            to send in the JSON request body; they replace fields the library
+            sets with the same key.
         :return: SpokenTerms containing information about the created
             collection.
         :raises ValueError: If a term, after stripping leading and trailing
             whitespace, is empty or contains a control character, as
             validate_glossary_term() checks.
         """
-        request_data = {
+        request_data: Dict[str, Any] = {
             "name": name,
             "term_lists": [
                 self._spoken_terms_json(entries) for entries in term_lists
             ],
         }
+        request_data.update(extra_body_parameters or {})
         status, content, json = self._api_call(
             "v3/spoken-terms", json=request_data
         )
@@ -795,6 +801,7 @@ def update_spoken_terms(
         *,
         name: Optional[str] = None,
         term_lists: Optional[List[SpokenTermsEntries]] = None,
+        extra_body_parameters: Optional[Dict[str, Any]] = None,
     ) -> SpokenTerms:
         """Updates a spoken-terms collection: renames it and/or merges the
         given terms into the existing term list of each given language.
@@ -803,6 +810,9 @@ def update_spoken_terms(
         :param name: (Optional) New name of the collection.
         :param term_lists: (Optional) List of SpokenTermsEntries whose terms
             are merged into the term list of the same language.
+        :param extra_body_parameters: (Optional) Additional key/value pairs
+            to send in the JSON request body; they replace fields the library
+            sets with the same key.
         :return: SpokenTerms containing information about the updated
             collection.
         :raises ValueError: If a term, after stripping leading and trailing
@@ -817,6 +827,7 @@ def update_spoken_terms(
             request_data["term_lists"] = [
                 self._spoken_terms_json(entries) for entries in term_lists
             ]
+        request_data.update(extra_body_parameters or {})
         status, content, json = self._api_call(
             f"v3/spoken-terms/{spoken_terms_id}",
             method="PATCH",
@@ -849,23 +860,30 @@ def replace_spoken_terms_list(
         self,
         spoken_terms: Union[str, SpokenTerms],
         entries: SpokenTermsEntries,
+        *,
+        extra_body_parameters: Optional[Dict[str, Any]] = None,
     ) -> SpokenTermsList:
         """Replaces the term list of one language in a spoken-terms
         collection, or adds it if the collection has no list for the
         language.
 
         :param spoken_terms: SpokenTerms or ID of the collection.
         :param entries: SpokenTermsEntries with the language and its terms.
+        :param extra_body_parameters: (Optional) Additional key/value pairs
+            to send in the JSON request body; they replace fields the library
+            sets with the same key.
         :return: SpokenTermsList containing information about the term list.
         :raises ValueError: If a term, after stripping leading and trailing
             whitespace, is empty or contains a control character, as
             validate_glossary_term() checks.
         """
         spoken_terms_id = self._spoken_terms_id(spoken_terms)
+        request_data = self._spoken_terms_json(entries)
+        request_data.update(extra_body_parameters or {})
         status, content, json = self._api_call(
             f"v3/spoken-terms/{spoken_terms_id}/term-lists",
             method="PUT",
-            json=self._spoken_terms_json(entries),
+            json=request_data,
         )
         self._raise_for_status(status, content, json)
         return self._parse_spoken_terms_response(

tests/offline/test_spoken_terms.py

@@ -145,3 +145,35 @@ def test_raises_deepl_exception_on_a_malformed_response(
 
     with pytest.raises(deepl.DeepLException, match="Malformed"):
         call(make_deepl_client())
+
+
+def test_sends_extra_body_parameters_last(mocked):
+    mocked.post(
+        url("v3/spoken-terms"),
+        json=SPOKEN_TERMS_JSON,
+        status=201,
+        match=json_request({"name": "override", "term_lists": [], "x": 1}),
+    )
+    mocked.patch(
+        url("v3/spoken-terms/st-1"),
+        json=SPOKEN_TERMS_JSON,
+        match=json_request({"name": "renamed", "x": True}),
+    )
+    mocked.put(
+        url("v3/spoken-terms/st-1/term-lists"),
+        json={"lang": "de", "entry_count": 1},
+        match=json_request({"lang": "de", "entries": "a", "x": None}),
+    )
+    client = make_deepl_client()
+
+    client.create_spoken_terms(
+        "terms", [], extra_body_parameters={"name": "override", "x": 1}
+    )
+    client.update_spoken_terms(
+        "st-1", name="renamed", extra_body_parameters={"x": True}
+    )
+    client.replace_spoken_terms_list(
+        "st-1",
+        deepl.SpokenTermsEntries("en", ["a"]),
+        extra_body_parameters={"lang": "de", "x": None},
+    )