fix: raise DeepLException on malformed spoken-terms responses

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

Author: hive-bot

deepl/deepl_client.py

@@ -42,14 +42,18 @@
 from typing import (
     Any,
     BinaryIO,
+    Callable,
     Dict,
     Iterable,
     List,
     Optional,
     TextIO,
+    TypeVar,
     Union,
 )
 
+_T = TypeVar("_T")
+
 
 class DeepLClient(Translator):
     def __init__(
@@ -750,7 +754,7 @@ def create_spoken_terms(
             "v3/spoken-terms", json=request_data
         )
         self._raise_for_status(status, content, json)
-        return SpokenTerms.from_json(json)
+        return self._parse_spoken_terms_response(SpokenTerms.from_json, json)
 
     def list_spoken_terms(self) -> List[SpokenTerms]:
         """Retrieves all spoken-terms collections.
@@ -764,7 +768,10 @@ def list_spoken_terms(self) -> List[SpokenTerms]:
             if (json and isinstance(json, dict))
             else []
         )
-        return [SpokenTerms.from_json(item) for item in spoken_terms]
+        return self._parse_spoken_terms_response(
+            lambda items: [SpokenTerms.from_json(item) for item in items],
+            spoken_terms,
+        )
 
     def get_spoken_terms(
         self, spoken_terms: Union[str, SpokenTerms]
@@ -780,7 +787,7 @@ def get_spoken_terms(
             f"v3/spoken-terms/{spoken_terms_id}", method="GET"
         )
         self._raise_for_status(status, content, json)
-        return SpokenTerms.from_json(json)
+        return self._parse_spoken_terms_response(SpokenTerms.from_json, json)
 
     def update_spoken_terms(
         self,
@@ -816,7 +823,7 @@ def update_spoken_terms(
             json=request_data,
         )
         self._raise_for_status(status, content, json)
-        return SpokenTerms.from_json(json)
+        return self._parse_spoken_terms_response(SpokenTerms.from_json, json)
 
     def get_spoken_terms_entries(
         self, spoken_terms: Union[str, SpokenTerms], lang: str
@@ -834,7 +841,9 @@ def get_spoken_terms_entries(
             method="GET",
         )
         self._raise_for_status(status, content, json)
-        return SpokenTermsEntries.from_json(json)
+        return self._parse_spoken_terms_response(
+            SpokenTermsEntries.from_json, json
+        )
 
     def replace_spoken_terms_list(
         self,
@@ -859,7 +868,9 @@ def replace_spoken_terms_list(
             json=self._spoken_terms_json(entries),
         )
         self._raise_for_status(status, content, json)
-        return SpokenTermsList.from_json(json)
+        return self._parse_spoken_terms_response(
+            SpokenTermsList.from_json, json
+        )
 
     def delete_spoken_terms(
         self, spoken_terms: Union[str, SpokenTerms]
@@ -891,6 +902,17 @@ def delete_spoken_terms_list(
         )
         self._raise_for_status(status, content, json)
 
+    @staticmethod
+    def _parse_spoken_terms_response(
+        parse: Callable[[Any], _T], json: Any
+    ) -> _T:
+        try:
+            return parse(json)
+        except (AttributeError, KeyError, TypeError, ValueError) as e:
+            raise DeepLException(
+                f"Malformed spoken-terms response: {e!r}"
+            ) from e
+
     @staticmethod
     def _spoken_terms_json(entries: SpokenTermsEntries) -> dict:
         # Terms are sent newline-separated: a term with a newline would

tests/offline/test_spoken_terms.py

@@ -90,3 +90,58 @@ def test_rejects_a_whitespace_only_term(mocked):
         make_deepl_client().create_spoken_terms(
             "terms", [deepl.SpokenTermsEntries("en", ["a", "  "])]
         )
+
+
+@pytest.mark.parametrize(
+    "method, path, body, call",
+    [
+        (
+            "POST",
+            "v3/spoken-terms",
+            {"name": "terms"},
+            lambda c: c.create_spoken_terms("terms", []),
+        ),
+        (
+            "GET",
+            "v3/spoken-terms/st-1",
+            {**SPOKEN_TERMS_JSON, "creation_time": "yesterday"},
+            lambda c: c.get_spoken_terms("st-1"),
+        ),
+        (
+            "PATCH",
+            "v3/spoken-terms/st-1",
+            "not json",
+            lambda c: c.update_spoken_terms("st-1", name="renamed"),
+        ),
+        (
+            "GET",
+            "v3/spoken-terms",
+            {"spoken_terms": [{"name": "terms"}]},
+            lambda c: c.list_spoken_terms(),
+        ),
+        (
+            "GET",
+            "v3/spoken-terms/st-1/entries",
+            "not json",
+            lambda c: c.get_spoken_terms_entries("st-1", "en"),
+        ),
+        (
+            "PUT",
+            "v3/spoken-terms/st-1/term-lists",
+            {"lang": "en", "entry_count": "many"},
+            lambda c: c.replace_spoken_terms_list(
+                "st-1", deepl.SpokenTermsEntries("en", ["a"])
+            ),
+        ),
+    ],
+)
+def test_raises_deepl_exception_on_a_malformed_response(
+    mocked, method, path, body, call
+):
+    if isinstance(body, dict):
+        mocked.add(method, url(path), json=body)
+    else:
+        mocked.add(method, url(path), body=body)
+
+    with pytest.raises(deepl.DeepLException, match="Malformed"):
+        call(make_deepl_client())