Release v1.5.11

Make response parsing lenient: never throw because a field is missing or a
different type than expected. The enterprise endpoint can return songs with no
score (also missing isrc/upc/label, and some fields on YouTube-sourced entries).
Those fields are now optional/nullable and degrade instead of raising.

Kept legitimate failures: API status=error, undecodable JSON, transport
errors, and caller-input errors (unknown provider, missing token).

Author: Mikhail Samin's Claude

src/audd/_version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the package version. Hatch reads this."""
 
-__version__ = "1.5.10"
+__version__ = "1.5.11"

src/audd/advanced.py

@@ -15,7 +15,7 @@
     AudDSerializationError,
     raise_from_error_response,
 )
-from audd.models import LyricsResult
+from audd.models import LyricsResult, _coerce_model_list
 
 API_BASE = "https://api.audd.io"
 
@@ -29,7 +29,7 @@ def find_lyrics(self, query: str) -> list[LyricsResult]:
         body = self.raw_request("findLyrics", {"q": query})
         if body.get("status") == "error":
             raise_from_error_response(body, http_status=200, request_id=None)
-        return [LyricsResult.model_validate(r) for r in (body.get("result") or [])]
+        return _coerce_model_list(body.get("result"), LyricsResult)
 
     def raw_request(
         self,
@@ -64,7 +64,7 @@ async def find_lyrics(self, query: str) -> list[LyricsResult]:
         body = await self.raw_request("findLyrics", {"q": query})
         if body.get("status") == "error":
             raise_from_error_response(body, http_status=200, request_id=None)
-        return [LyricsResult.model_validate(r) for r in (body.get("result") or [])]
+        return _coerce_model_list(body.get("result"), LyricsResult)
 
     async def raw_request(
         self,

src/audd/client.py

@@ -188,17 +188,26 @@ def _decode_or_raise(resp: HTTPResponse) -> dict[str, Any]:
 def _decode_recognize(resp: HTTPResponse) -> RecognitionResult | None:
     body = _decode_or_raise(resp)
     result = body.get("result")
-    if result is None:
+    # No-match responses carry result: null (or, rarely, a non-object falsy
+    # value). Treat anything that isn't a dict as "no match" rather than raising.
+    if not isinstance(result, dict):
         return None
     return RecognitionResult.model_validate(result)
 
 
 def _decode_enterprise(resp: HTTPResponse) -> list[EnterpriseMatch]:
     body = _decode_or_raise(resp)
-    chunks_raw = body.get("result") or []
+    chunks_raw = body.get("result")
     out: list[EnterpriseMatch] = []
+    # A successful response must never raise on a missing/odd-typed result.
+    # Skip anything that isn't a chunk object instead of aborting the parse.
+    if not isinstance(chunks_raw, list):
+        return out
     for chunk_dict in chunks_raw:
-        chunk = EnterpriseChunkResult.model_validate(chunk_dict)
+        try:
+            chunk = EnterpriseChunkResult.model_validate(chunk_dict)
+        except Exception:  # noqa: BLE001 — degrade, never raise on response parse
+            continue
         out.extend(chunk.songs)
     return out
 

src/audd/models.py

@@ -6,7 +6,7 @@
 from typing import Any, Literal, TextIO
 from urllib.parse import urlparse
 
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, field_validator
 
 # Streaming providers reachable via the lis.tn `?<provider>` redirect helper.
 _STREAMING_PROVIDERS: tuple[str, ...] = (
@@ -37,6 +37,28 @@ class _Forward(BaseModel):
     model_config = ConfigDict(extra="allow", populate_by_name=True, str_strip_whitespace=False)
 
 
+def _coerce_model_list(value: Any, model: type[BaseModel]) -> list[Any]:
+    """Best-effort list-of-model coercion that never raises.
+
+    A successful API response must parse even when a list field is missing,
+    is not a list, or carries a malformed element. Missing/None/non-list →
+    empty list; each element that fails validation is skipped rather than
+    aborting the whole parse.
+    """
+    if not isinstance(value, list):
+        return []
+    out: list[Any] = []
+    for item in value:
+        if isinstance(item, model):
+            out.append(item)
+            continue
+        try:
+            out.append(model.model_validate(item))
+        except Exception:  # noqa: BLE001 — degrade, never raise on response parse
+            continue
+    return out
+
+
 class AppleMusicMetadata(_Forward):
     artistName: str | None = None
     url: str | None = None
@@ -77,14 +99,14 @@ class NapsterMetadata(_Forward):
 
 
 class MusicBrainzEntry(_Forward):
-    id: str
+    id: str | None = None
     score: int | str | None = None
     title: str | None = None
     length: int | None = None
 
 
 class RecognitionResult(_Forward):
-    timecode: str
+    timecode: str | None = None
     audio_id: int | None = None
     artist: str | None = None
     title: str | None = None
@@ -100,6 +122,13 @@ class RecognitionResult(_Forward):
     napster: NapsterMetadata | None = None
     musicbrainz: list[MusicBrainzEntry] | None = None
 
+    @field_validator("musicbrainz", mode="before")
+    @classmethod
+    def _coerce_musicbrainz(cls, v: Any) -> Any:
+        if v is None:
+            return None
+        return _coerce_model_list(v, MusicBrainzEntry)
+
     def __repr__(self) -> str:
         parts: list[str] = []
         if self.artist:
@@ -254,8 +283,8 @@ def preview_url(self) -> str | None:
 
 
 class EnterpriseMatch(_Forward):
-    score: int
-    timecode: str
+    score: int | None = None
+    timecode: str | None = None
     artist: str | None = None
     title: str | None = None
     album: str | None = None
@@ -315,14 +344,19 @@ def streaming_urls(self) -> dict[str, str]:
 
 
 class EnterpriseChunkResult(_Forward):
-    songs: list[EnterpriseMatch]
-    offset: str
+    songs: list[EnterpriseMatch] = []
+    offset: str | None = None
+
+    @field_validator("songs", mode="before")
+    @classmethod
+    def _coerce_songs(cls, v: Any) -> Any:
+        return _coerce_model_list(v, EnterpriseMatch)
 
 
 class Stream(_Forward):
-    radio_id: int
-    url: str
-    stream_running: bool
+    radio_id: int | None = None
+    url: str | None = None
+    stream_running: bool | None = None
     longpoll_category: str | None = None
 
 
@@ -334,9 +368,9 @@ class StreamCallbackSong(_Forward):
     (variant releases, different masters, regional editions).
     """
 
-    artist: str
-    title: str
-    score: int
+    artist: str | None = None
+    title: str | None = None
+    score: int | None = None
     album: str | None = None
     release_date: str | None = None
     label: str | None = None
@@ -349,6 +383,13 @@ class StreamCallbackSong(_Forward):
     napster: NapsterMetadata | None = None
     musicbrainz: list[MusicBrainzEntry] | None = None
 
+    @field_validator("musicbrainz", mode="before")
+    @classmethod
+    def _coerce_musicbrainz(cls, v: Any) -> Any:
+        if v is None:
+            return None
+        return _coerce_model_list(v, MusicBrainzEntry)
+
 
 class StreamCallbackMatch(_Forward):
     """One recognition event from a stream callback or longpoll.
@@ -362,30 +403,35 @@ class StreamCallbackMatch(_Forward):
     :py:attr:`pydantic.BaseModel.model_extra`.
     """
 
-    radio_id: int
+    radio_id: int | None = None
     timestamp: str | None = None
     play_length: int | None = None
-    song: StreamCallbackSong
+    song: StreamCallbackSong | None = None
     alternatives: list[StreamCallbackSong] = []
     raw_response: dict[str, Any] | None = None
 
+    @field_validator("alternatives", mode="before")
+    @classmethod
+    def _coerce_alternatives(cls, v: Any) -> Any:
+        return _coerce_model_list(v, StreamCallbackSong)
+
 
 class StreamCallbackNotification(_Forward):
     """Stream lifecycle event (e.g. ``stream stopped``, ``can't connect``)."""
 
-    radio_id: int
+    radio_id: int | None = None
     stream_running: bool | None = None
-    notification_code: int
-    notification_message: str
+    notification_code: int | None = None
+    notification_message: str | None = None
     # Outer ``time`` field on the callback envelope (epoch seconds).
     # Sits next to the ``notification`` block in the JSON, not inside it.
     time: int | None = None
     raw_response: dict[str, Any] | None = None
 
 
 class LyricsResult(_Forward):
-    artist: str
-    title: str
+    artist: str | None = None
+    title: str | None = None
     lyrics: str | None = None
     song_id: int | None = None
     media: str | None = None

src/audd/streams.py

@@ -29,6 +29,7 @@
     Stream,
     StreamCallbackMatch,
     StreamCallbackNotification,
+    _coerce_model_list,
 )
 
 API_BASE = "https://api.audd.io"
@@ -577,8 +578,8 @@ def delete(self, radio_id: int) -> None:
         self._post("deleteStream", {"radio_id": str(radio_id)}, self._mutating)
 
     def list(self) -> list[Stream]:
-        result = self._post("getStreams", {}, self._read) or []
-        return [Stream.model_validate(s) for s in result]
+        result = self._post("getStreams", {}, self._read)
+        return _coerce_model_list(result, Stream)
 
     def handle_callback(
         self, request: Any,
@@ -718,8 +719,8 @@ async def delete(self, radio_id: int) -> None:
         await self._post("deleteStream", {"radio_id": str(radio_id)}, self._mutating)
 
     async def list(self) -> list[Stream]:
-        result = await self._post("getStreams", {}, self._read) or []
-        return [Stream.model_validate(s) for s in result]
+        result = await self._post("getStreams", {}, self._read)
+        return _coerce_model_list(result, Stream)
 
     async def handle_callback(
         self, request: Any,

tests/unit/test_client.py

@@ -140,6 +140,45 @@ def test_recognize_enterprise_returns_list_of_matches() -> None:
     assert matches[0].artist == "X"
 
 
+@respx.mock
+def test_recognize_enterprise_song_without_score_parses() -> None:
+    """Enterprise endpoint legitimately returns songs with no score (and no
+    isrc/upc/label) — e.g. YouTube-sourced entries. The decode path must not
+    raise; the match parses with score is None."""
+    respx.post("https://enterprise.audd.io/").mock(
+        return_value=httpx.Response(200, json={
+            "status": "success",
+            "result": [{
+                "songs": [{
+                    "timecode": "00:11", "artist": "X", "title": "Y",
+                    "song_link": "https://youtu.be/abc",
+                }],
+                "offset": "00:00",
+            }],
+        }),
+    )
+    matches = AudD(api_token="t-test").recognize_enterprise("https://example.mp3", limit=1)
+    assert len(matches) == 1
+    assert matches[0].score is None
+    assert matches[0].isrc is None
+    assert matches[0].artist == "X"
+
+
+@respx.mock
+def test_recognize_missing_timecode_parses() -> None:
+    """A recognition result missing timecode must parse, not raise."""
+    respx.post("https://api.audd.io/").mock(
+        return_value=httpx.Response(200, json={
+            "status": "success",
+            "result": {"artist": "X", "title": "Y"},
+        }),
+    )
+    result = AudD(api_token="t-test").recognize("https://example.mp3")
+    assert isinstance(result, RecognitionResult)
+    assert result.timecode is None
+    assert result.artist == "X"
+
+
 @respx.mock
 def test_recognize_enterprise_unauthorized_raises_subscription_error() -> None:
     respx.post("https://enterprise.audd.io/").mock(