Introduce Info.name property and add types to match details functions

beets/autotag/__init__.py

@@ -30,7 +30,7 @@
 from .match import Proposal, Recommendation, tag_album, tag_item
 
 if TYPE_CHECKING:
-    from collections.abc import Mapping, Sequence
+    from collections.abc import Sequence
 
     from beets.library import Album, Item, LibModel
 
@@ -210,11 +210,13 @@ def apply_album_metadata(album_info: AlbumInfo, album: Album):
     correct_list_fields(album)
 
 
-def apply_metadata(album_info: AlbumInfo, mapping: Mapping[Item, TrackInfo]):
+def apply_metadata(
+    album_info: AlbumInfo, mapping: list[tuple[Item, TrackInfo]]
+):
     """Set the items' metadata to match an AlbumInfo object using a
     mapping from Items to TrackInfo objects.
     """
-    for item, track_info in mapping.items():
+    for item, track_info in mapping:
         # Artist or artist credit.
         if config["artist_credit"]:
             item.artist = (

beets/autotag/distance.py

@@ -422,7 +422,7 @@ def track_distance(
 def distance(
     items: Sequence[Item],
     album_info: AlbumInfo,
-    mapping: dict[Item, TrackInfo],
+    mapping: list[tuple[Item, TrackInfo]],
 ) -> Distance:
     """Determines how "significant" an album metadata change would be.
     Returns a Distance object. `album_info` is an AlbumInfo object
@@ -518,7 +518,7 @@ def distance(
 
     # Tracks.
     dist.tracks = {}
-    for item, track in mapping.items():
+    for item, track in mapping:
         dist.tracks[track] = track_distance(item, track, album_info.va)
         dist.add("tracks", dist.tracks[track].distance)
 

beets/autotag/hooks.py

@@ -17,10 +17,14 @@
 from __future__ import annotations
 
 from copy import deepcopy
-from typing import TYPE_CHECKING, Any, NamedTuple, TypeVar
+from dataclasses import dataclass
+from functools import cached_property
+from typing import TYPE_CHECKING, Any, TypeVar
 
 from typing_extensions import Self
 
+from beets.util import cached_classproperty
+
 if TYPE_CHECKING:
     from beets.library import Item
 
@@ -54,6 +58,10 @@ def __hash__(self) -> int:  # type: ignore[override]
 class Info(AttrDict[Any]):
     """Container for metadata about a musical entity."""
 
+    @cached_property
+    def name(self) -> str:
+        raise NotImplementedError
+
     def __init__(
         self,
         album: str | None = None,
@@ -95,6 +103,10 @@ class AlbumInfo(Info):
     user items, and later to drive tagging decisions once selected.
     """
 
+    @cached_property
+    def name(self) -> str:
+        return self.album or ""
+
     def __init__(
         self,
         tracks: list[TrackInfo],
@@ -167,6 +179,10 @@ class TrackInfo(Info):
     stand alone for singleton matching.
     """
 
+    @cached_property
+    def name(self) -> str:
+        return self.title or ""
+
     def __init__(
         self,
         *,
@@ -214,16 +230,28 @@ def __init__(
 
 
 # Structures that compose all the information for a candidate match.
+@dataclass
+class Match:
+    distance: Distance
+    info: Info
 
+    @cached_classproperty
+    def type(cls) -> str:
+        return cls.__name__.removesuffix("Match")  # type: ignore[attr-defined]
 
-class AlbumMatch(NamedTuple):
-    distance: Distance
+
+@dataclass
+class AlbumMatch(Match):
     info: AlbumInfo
-    mapping: dict[Item, TrackInfo]
+    mapping: list[tuple[Item, TrackInfo]]
     extra_items: list[Item]
     extra_tracks: list[TrackInfo]
 
+    @cached_property
+    def items(self) -> list[Item]:
+        return [i for i, _ in self.mapping]
 
-class TrackMatch(NamedTuple):
-    distance: Distance
+
+@dataclass
+class TrackMatch(Match):
     info: TrackInfo

beets/autotag/match.py

@@ -69,7 +69,7 @@ class Proposal(NamedTuple):
 def assign_items(
     items: Sequence[Item],
     tracks: Sequence[TrackInfo],
-) -> tuple[dict[Item, TrackInfo], list[Item], list[TrackInfo]]:
+) -> tuple[list[tuple[Item, TrackInfo]], list[Item], list[TrackInfo]]:
     """Given a list of Items and a list of TrackInfo objects, find the
     best mapping between them. Returns a mapping from Items to TrackInfo
     objects, a set of extra Items, and a set of extra TrackInfo
@@ -86,14 +86,15 @@ def assign_items(
     # Each item in `assigned_item_idxs` list corresponds to a track in the
     # `tracks` list. Each value is either an index into the assigned item in
     # `items` list, or -1 if that track has no match.
-    mapping = {
-        items[iidx]: t
+    mapping = [
+        (items[iidx], t)
         for iidx, t in zip(assigned_item_idxs, tracks)
         if iidx != -1
-    }
-    extra_items = list(set(items) - mapping.keys())
+    ]
+    mapping.sort(key=lambda it: (it[0].disc, it[0].track, it[0].title))
+    extra_items = list(set(items) - {i for i, _ in mapping})
     extra_items.sort(key=lambda i: (i.disc, i.track, i.title))
-    extra_tracks = list(set(tracks) - set(mapping.values()))
+    extra_tracks = list(set(tracks) - {t for _, t in mapping})
     extra_tracks.sort(key=lambda t: (t.index, t.title))
     return mapping, extra_items, extra_tracks
 
@@ -239,7 +240,7 @@ def _add_candidate(
 def tag_album(
     items,
     search_artist: str | None = None,
-    search_album: str | None = None,
+    search_name: str | None = None,
     search_ids: list[str] = [],
 ) -> tuple[str, str, Proposal]:
     """Return a tuple of the current artist name, the current album
@@ -295,10 +296,10 @@ def tag_album(
                     )
 
         # Search terms.
-        if not (search_artist and search_album):
+        if not (search_artist and search_name):
             # No explicit search terms -- use current metadata.
-            search_artist, search_album = cur_artist, cur_album
-        log.debug("Search terms: {} - {}", search_artist, search_album)
+            search_artist, search_name = cur_artist, cur_album
+        log.debug("Search terms: {} - {}", search_artist, search_name)
 
         # Is this album likely to be a "various artist" release?
         va_likely = (
@@ -310,7 +311,7 @@ def tag_album(
 
         # Get the results from the data sources.
         for matched_candidate in metadata_plugins.candidates(
-            items, search_artist, search_album, va_likely
+            items, search_artist, search_name, va_likely
         ):
             _add_candidate(items, candidates, matched_candidate)
 
@@ -324,7 +325,7 @@ def tag_album(
 def tag_item(
     item,
     search_artist: str | None = None,
-    search_title: str | None = None,
+    search_name: str | None = None,
     search_ids: list[str] | None = None,
 ) -> Proposal:
     """Find metadata for a single track. Return a `Proposal` consisting
@@ -366,12 +367,12 @@ def tag_item(
 
     # Search terms.
     search_artist = search_artist or item.artist
-    search_title = search_title or item.title
-    log.debug("Item search terms: {} - {}", search_artist, search_title)
+    search_name = search_name or item.title
+    log.debug("Item search terms: {} - {}", search_artist, search_name)
 
     # Get and evaluate candidate metadata.
     for track_info in metadata_plugins.item_candidates(
-        item, search_artist, search_title
+        item, search_artist, search_name
     ):
         dist = track_distance(item, track_info, incl_artist=True)
         candidates[track_info.track_id] = hooks.TrackMatch(dist, track_info)

beets/importer/tasks.py

@@ -244,18 +244,18 @@ def imported_items(self):
         matched items.
         """
         if self.choice_flag in (Action.ASIS, Action.RETAG):
-            return list(self.items)
+            return self.items
         elif self.choice_flag == Action.APPLY and isinstance(
             self.match, autotag.AlbumMatch
         ):
-            return list(self.match.mapping.keys())
+            return self.match.items
         else:
             assert False
 
     def apply_metadata(self):
         """Copy metadata from match info to the items."""
         if config["import"]["from_scratch"]:
-            for item in self.match.mapping:
+            for item in self.match.items:
                 item.clear()
 
         autotag.apply_metadata(self.match.info, self.match.mapping)