Add summary variants of the media item models (#296)

Author: marcelveldt

music_assistant_models/media_items/__init__.py

@@ -42,39 +42,65 @@
     MediaItemPalette,
 )
 from .provider_mapping import ProviderMapping
+from .summary import (
+    AlbumSummary,
+    ArtistSummary,
+    AudiobookSummary,
+    GenreSummary,
+    ItemMappingSummary,
+    MediaItemMetadataSummary,
+    MediaItemSummaryType,
+    PlaylistSummary,
+    PodcastSummary,
+    RadioSummary,
+    SummaryDialect,
+    TrackSummary,
+)
 
 __all__ = [
     "Album",
+    "AlbumSummary",
     "Artist",
+    "ArtistSummary",
     "AudioFormat",
     "AudioMetadata",
     "AudioSource",
     "Audiobook",
+    "AudiobookSummary",
     "BrowseFolder",
     "Genre",
+    "GenreSummary",
     "ItemMapping",
+    "ItemMappingSummary",
     "MediaItem",
     "MediaItemChapter",
     "MediaItemCollection",
     "MediaItemImage",
     "MediaItemLink",
     "MediaItemMetadata",
+    "MediaItemMetadataSummary",
     "MediaItemPalette",
+    "MediaItemSummaryType",
     "MediaItemType",
     "Metadata",
     "MetadataProvider",
     "MetadataProviderStatus",
     "MetadataProviderType",
     "PlayableMediaItemType",
     "Playlist",
+    "PlaylistSummary",
     "PlaylistTrack",
     "Podcast",
     "PodcastEpisode",
+    "PodcastSummary",
     "ProviderMapping",
     "Radio",
+    "RadioSummary",
     "RecommendationFolder",
     "SoundEffect",
+    "SummaryDialect",
     "Track",
+    "TrackSummary",
     "UniqueList",
 ]
 

music_assistant_models/media_items/media_item.py

@@ -407,7 +407,7 @@ def __post_serialize__(self, d: dict[str, Any]) -> dict[str, Any]:
         """Adjust dict object after it has been serialized."""
         self._resolve_translation(d)
         # TEMP 2025-03-14: convert None duration to fake number for backwards compatibility
-        d["duration"] = 0 if d["duration"] is None else d["duration"]
+        d["duration"] = d.get("duration") or 0
         return d
 
 

music_assistant_models/media_items/summary.py

@@ -0,0 +1,158 @@
+"""
+Summary (slim) variants of the media item models, used for listings.
+
+These are drop-in subclasses of the regular media item models — same wire shape, same
+``media_type`` discriminator, deserializable with the regular classes — but carry only the
+fields a list view renders: identity, name(s), artist/album mappings, a single (thumb) image
+and a handful of per-type scalars. All unset (None) fields are omitted from the serialized
+output, provider mappings are empty and ``available`` is a plain (pre-computed) field instead
+of a derived property.
+
+The Music Assistant server returns these from the ``library_items`` API commands when the
+``summary`` flag is set; full items (with provider mappings, complete metadata, etc.) remain
+available through the regular ``get`` commands.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from mashumaro.config import BaseConfig
+from mashumaro.dialect import Dialect
+
+from music_assistant_models.unique_list import UniqueList
+
+from .media_item import (
+    Album,
+    Artist,
+    Audiobook,
+    Genre,
+    ItemMapping,
+    Playlist,
+    Podcast,
+    Radio,
+    Track,
+)
+from .metadata import MediaItemMetadata
+from .provider_mapping import ProviderMapping
+
+
+class _OmitNoneDialect(Dialect):
+    omit_none = True
+
+
+@dataclass(kw_only=True, eq=False)
+class MediaItemMetadataSummary(MediaItemMetadata):
+    """Metadata of a summary item, with None-valued fields omitted from serialized output."""
+
+    class Config(BaseConfig):
+        """Mashumaro serialization config."""
+
+        dialect = _OmitNoneDialect
+
+
+@dataclass(kw_only=True, eq=False)
+class ItemMappingSummary(ItemMapping):
+    """ItemMapping of a summary item, with None-valued fields omitted from serialized output."""
+
+    class Config(BaseConfig):
+        """Mashumaro serialization config."""
+
+        dialect = _OmitNoneDialect
+
+
+class SummaryDialect(Dialect):
+    """
+    Serialization dialect for summary items.
+
+    Omits None-valued fields and (de)serializes nested metadata as its summary variant.
+    """
+
+    omit_none = True
+    serialization_strategy = {  # noqa: RUF012
+        MediaItemMetadata: {
+            "serialize": lambda v: v.to_dict(),
+            "deserialize": lambda v: MediaItemMetadataSummary.from_dict(v),
+        },
+    }
+
+
+@dataclass(kw_only=True, eq=False)
+class _SummaryBase:
+    """
+    Mixin that turns a regular media item subclass into its summary variant.
+
+    Serialization omits None-valued fields, ``available`` is a plain field (filled by the
+    server from the — not serialized — provider mappings) and metadata is reduced to the
+    slim summary variant.
+    """
+
+    class Config(BaseConfig):
+        """Mashumaro serialization config."""
+
+        dialect = SummaryDialect
+
+    provider_mappings: set[ProviderMapping] = field(default_factory=set)
+    available: bool = True
+    metadata: MediaItemMetadata = field(default_factory=MediaItemMetadataSummary)
+
+
+@dataclass(kw_only=True, eq=False)
+class ArtistSummary(_SummaryBase, Artist):
+    """Summary variant of Artist, used for listings."""
+
+
+@dataclass(kw_only=True, eq=False)
+class AlbumSummary(_SummaryBase, Album):
+    """Summary variant of Album, used for listings."""
+
+    artists: UniqueList[ItemMappingSummary] = field(  # type: ignore[assignment]
+        default_factory=UniqueList
+    )
+
+
+@dataclass(kw_only=True, eq=False)
+class TrackSummary(_SummaryBase, Track):
+    """Summary variant of Track, used for listings."""
+
+    artists: UniqueList[ItemMappingSummary] = field(  # type: ignore[assignment]
+        default_factory=UniqueList
+    )
+    album: ItemMappingSummary | None = None
+
+
+@dataclass(kw_only=True, eq=False)
+class PlaylistSummary(_SummaryBase, Playlist):
+    """Summary variant of Playlist, used for listings."""
+
+
+@dataclass(kw_only=True, eq=False)
+class RadioSummary(_SummaryBase, Radio):
+    """Summary variant of Radio, used for listings."""
+
+
+@dataclass(kw_only=True, eq=False)
+class AudiobookSummary(_SummaryBase, Audiobook):
+    """Summary variant of Audiobook, used for listings."""
+
+
+@dataclass(kw_only=True, eq=False)
+class PodcastSummary(_SummaryBase, Podcast):
+    """Summary variant of Podcast, used for listings."""
+
+
+@dataclass(kw_only=True, eq=False)
+class GenreSummary(_SummaryBase, Genre):
+    """Summary variant of Genre, used for listings."""
+
+
+MediaItemSummaryType = (
+    ArtistSummary
+    | AlbumSummary
+    | TrackSummary
+    | PlaylistSummary
+    | RadioSummary
+    | AudiobookSummary
+    | PodcastSummary
+    | GenreSummary
+)

tests/test_summary_items.py

@@ -0,0 +1,149 @@
+"""Tests for the summary (slim) media item models."""
+
+from music_assistant_models.enums import ImageType, MediaType
+from music_assistant_models.media_items import (
+    AlbumSummary,
+    ArtistSummary,
+    AudiobookSummary,
+    GenreSummary,
+    ItemMappingSummary,
+    MediaItemImage,
+    MediaItemMetadataSummary,
+    Playlist,
+    PlaylistSummary,
+    PodcastSummary,
+    Radio,
+    RadioSummary,
+    Track,
+    TrackSummary,
+)
+from music_assistant_models.media_items.metadata import IMAGE_PROXY_ID_RESOLVER
+from music_assistant_models.unique_list import UniqueList
+
+
+def _track_summary() -> TrackSummary:
+    return TrackSummary(
+        item_id="123",
+        provider="library",
+        name="Test Track",
+        duration=185,
+        favorite=True,
+        artists=UniqueList(
+            [
+                ItemMappingSummary(
+                    media_type=MediaType.ARTIST,
+                    item_id="1",
+                    provider="library",
+                    name="Test Artist",
+                )
+            ]
+        ),
+        album=ItemMappingSummary(
+            media_type=MediaType.ALBUM,
+            item_id="2",
+            provider="library",
+            name="Test Album",
+            year=2001,
+        ),
+        metadata=MediaItemMetadataSummary(
+            images=UniqueList(
+                [MediaItemImage(type=ImageType.THUMB, path="/cover.jpg", provider="library")]
+            ),
+            explicit=True,
+        ),
+    )
+
+
+def test_summary_serialization_omits_none_fields() -> None:
+    """Serialized summary items must not contain any None-valued keys, at any level."""
+    d = _track_summary().to_dict()
+    assert not [k for k, v in d.items() if v is None]
+    assert not [k for k, v in d["metadata"].items() if v is None]
+    assert not [k for k, v in d["artists"][0].items() if v is None]
+    assert not [k for k, v in d["album"].items() if v is None]
+
+
+def test_summary_keeps_client_facing_fields() -> None:
+    """Fields clients switch on must survive serialization even when default-valued."""
+    d = _track_summary().to_dict()
+    assert d["media_type"] == "track"
+    assert d["available"] is True
+    assert d["provider_mappings"] == []
+    assert d["metadata"] == {
+        "images": [
+            {
+                "type": "thumb",
+                "path": "/cover.jpg",
+                "provider": "library",
+                "remotely_accessible": False,
+                "proxy_id": None,
+            }
+        ],
+        "explicit": True,
+    }
+
+
+def test_summary_roundtrips_through_regular_model() -> None:
+    """A serialized summary item must deserialize cleanly with the regular class."""
+    summary = _track_summary()
+    track = Track.from_dict(summary.to_dict())
+    assert track.name == summary.name
+    assert track.duration == summary.duration
+    assert track.favorite is True
+    assert track.artists[0].name == "Test Artist"
+    assert track.album is not None
+    assert track.album.name == "Test Album"
+    assert track.provider_mappings == set()
+
+
+def test_summary_is_instance_of_regular_model() -> None:
+    """Summary items are subtypes of their regular counterparts."""
+    assert isinstance(_track_summary(), Track)
+    assert isinstance(
+        PlaylistSummary(item_id="1", provider="library", name="pl"),
+        Playlist,
+    )
+
+
+def test_summary_equality_matches_regular_semantics() -> None:
+    """Summary items compare by identity (uri/external ids), like regular items."""
+    one = TrackSummary(item_id="123", provider="library", name="A")
+    other = TrackSummary(item_id="123", provider="library", name="B")
+    assert one == other
+    assert hash(one) == hash(other)
+
+
+def test_summary_image_proxy_id_injection() -> None:
+    """The image proxy_id resolver hook must fire for images nested in summary items."""
+    token = IMAGE_PROXY_ID_RESOLVER.set(lambda provider, _path: f"{provider}-proxy")
+    try:
+        d = _track_summary().to_dict()
+    finally:
+        IMAGE_PROXY_ID_RESOLVER.reset(token)
+    assert d["metadata"]["images"][0]["proxy_id"] == "library-proxy"
+
+
+def test_radio_summary_duration_backcompat() -> None:
+    """Radio's None->0 duration shim must not break on the omitted duration key."""
+    d = RadioSummary(item_id="1", provider="library", name="radio").to_dict()
+    assert d["duration"] == 0
+    # regular Radio keeps the same behavior
+    radio = Radio(item_id="1", provider="tunein", name="radio", provider_mappings=set())
+    assert radio.to_dict()["duration"] == 0
+
+
+def test_per_type_summaries_serialize_sparse() -> None:
+    """Every summary type serializes without None-valued keys."""
+    items = [
+        ArtistSummary(item_id="1", provider="library", name="artist"),
+        AlbumSummary(item_id="1", provider="library", name="album", year=2001),
+        PlaylistSummary(item_id="1", provider="library", name="playlist", owner="MA"),
+        RadioSummary(item_id="1", provider="library", name="radio"),
+        AudiobookSummary(item_id="1", provider="library", name="book", publisher="pub"),
+        PodcastSummary(item_id="1", provider="library", name="podcast"),
+        GenreSummary(item_id="1", provider="library", name="genre"),
+    ]
+    for item in items:
+        d = item.to_dict()
+        assert not [k for k, v in d.items() if v is None], type(item).__name__
+        assert d["media_type"] == item.media_type.value