Fix autotagger results penalisation due to the data source field (beetbox#6077)

This PR refactors the metadata source plugin architecture to fix
incorrect data source penalty calculations during import matching.

**Key Changes:**

- **Fixed distance calculation**: Removed `track_distance()` and
`album_distance()` methods from `MetadataSourcePlugin`. Data source
mismatch penalty is now calculated directly in
`beets/autotag/distance.py`, same as most of the rest of field-based
penalties.

- **Plugin registration**: Metadata source plugins now register
themselves in `_instance_by_data_source` dict on instantiation, enabling
efficient penalty lookups.

- **Renamed configuration options**:
  - `source_weight` → `data_source_mismatch_penalty` (plugin-level)
- `match.distance_weights.source` → `match.distance_weights.data_source`
(global matching)

- **Documentation**: added a `yaml` block with default configuration
values to each metadata source documentation page. Included the renamed
penalty field in each to underline that it's available for each data
source.

Author: snejus

beets/autotag/distance.py

@@ -345,6 +345,12 @@ def add_string(self, key: str, str1: str | None, str2: str | None):
         dist = string_dist(str1, str2)
         self.add(key, dist)
 
+    def add_data_source(self, before: str | None, after: str | None) -> None:
+        if before != after and (
+            before or len(metadata_plugins.find_metadata_source_plugins()) > 1
+        ):
+            self.add("data_source", metadata_plugins.get_penalty(after))
+
 
 @cache
 def get_track_length_grace() -> float:
@@ -408,8 +414,7 @@ def track_distance(
     if track_info.medium and item.disc:
         dist.add_expr("medium", item.disc != track_info.medium)
 
-    # Plugins.
-    dist.update(metadata_plugins.track_distance(item, track_info))
+    dist.add_data_source(item.get("data_source"), track_info.data_source)
 
     return dist
 
@@ -525,7 +530,6 @@ def distance(
     for _ in range(len(items) - len(mapping)):
         dist.add("unmatched_tracks", 1.0)
 
-    # Plugins.
-    dist.update(metadata_plugins.album_distance(items, album_info, mapping))
+    dist.add_data_source(likelies["data_source"], album_info.data_source)
 
     return dist

beets/config_default.yaml

@@ -166,7 +166,7 @@ match:
         missing_tracks: medium
         unmatched_tracks: medium
     distance_weights:
-        source: 2.0
+        data_source: 2.0
         artist: 3.0
         album: 3.0
         media: 1.0

beets/metadata_plugins.py

@@ -9,10 +9,11 @@
 
 import abc
 import re
-import warnings
+from functools import cache, cached_property
 from typing import TYPE_CHECKING, Generic, Literal, Sequence, TypedDict, TypeVar
 
 import unidecode
+from confuse import NotFoundError
 from typing_extensions import NotRequired
 
 from beets.util import cached_classproperty
@@ -23,36 +24,14 @@
 if TYPE_CHECKING:
     from collections.abc import Iterable
 
-    from confuse import ConfigView
-
-    from .autotag import Distance
     from .autotag.hooks import AlbumInfo, Item, TrackInfo
 
 
+@cache
 def find_metadata_source_plugins() -> list[MetadataSourcePlugin]:
-    """Returns a list of MetadataSourcePlugin subclass instances
-
-    Resolved from all currently loaded beets plugins.
-    """
-
-    all_plugins = find_plugins()
-    metadata_plugins: list[MetadataSourcePlugin | BeetsPlugin] = []
-    for plugin in all_plugins:
-        if isinstance(plugin, MetadataSourcePlugin):
-            metadata_plugins.append(plugin)
-        elif hasattr(plugin, "data_source"):
-            # TODO: Remove this in the future major release, v3.0.0
-            warnings.warn(
-                f"{plugin.__class__.__name__} is used as a legacy metadata source. "
-                "It should extend MetadataSourcePlugin instead of BeetsPlugin. "
-                "Support for this will be removed in the v3.0.0 release!",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-            metadata_plugins.append(plugin)
-
-    # typeignore: BeetsPlugin is not a MetadataSourcePlugin (legacy support)
-    return metadata_plugins  # type: ignore[return-value]
+    """Return a list of all loaded metadata source plugins."""
+    # TODO: Make this an isinstance(MetadataSourcePlugin, ...) check in v3.0.0
+    return [p for p in find_plugins() if hasattr(p, "data_source")]  # type: ignore[misc]
 
 
 @notify_info_yielded("albuminfo_received")
@@ -95,46 +74,17 @@ def track_for_id(_id: str) -> TrackInfo | None:
     return None
 
 
-def track_distance(item: Item, info: TrackInfo) -> Distance:
-    """Returns the track distance for an item and trackinfo.
-
-    Returns a Distance object is populated by all metadata source plugins
-    that implement the :py:meth:`MetadataSourcePlugin.track_distance` method.
-    """
-    from beets.autotag.distance import Distance
-
-    dist = Distance()
-    for plugin in find_metadata_source_plugins():
-        dist.update(plugin.track_distance(item, info))
-    return dist
-
-
-def album_distance(
-    items: Sequence[Item],
-    album_info: AlbumInfo,
-    mapping: dict[Item, TrackInfo],
-) -> Distance:
-    """Returns the album distance calculated by plugins."""
-    from beets.autotag.distance import Distance
-
-    dist = Distance()
-    for plugin in find_metadata_source_plugins():
-        dist.update(plugin.album_distance(items, album_info, mapping))
-    return dist
-
-
-def _get_distance(
-    config: ConfigView, data_source: str, info: AlbumInfo | TrackInfo
-) -> Distance:
-    """Returns the ``data_source`` weight and the maximum source weight
-    for albums or individual tracks.
-    """
-    from beets.autotag.distance import Distance
-
-    dist = Distance()
-    if info.data_source == data_source:
-        dist.add("source", config["source_weight"].as_number())
-    return dist
+@cache
+def get_penalty(data_source: str | None) -> float:
+    """Get the penalty value for the given data source."""
+    return next(
+        (
+            p.data_source_mismatch_penalty
+            for p in find_metadata_source_plugins()
+            if p.data_source == data_source
+        ),
+        MetadataSourcePlugin.DEFAULT_DATA_SOURCE_MISMATCH_PENALTY,
+    )
 
 
 class MetadataSourcePlugin(BeetsPlugin, metaclass=abc.ABCMeta):
@@ -145,12 +95,29 @@ class MetadataSourcePlugin(BeetsPlugin, metaclass=abc.ABCMeta):
     and tracks, and to retrieve album and track information by ID.
     """
 
+    DEFAULT_DATA_SOURCE_MISMATCH_PENALTY = 0.5
+
+    @cached_classproperty
+    def data_source(cls) -> str:
+        """The data source name for this plugin.
+
+        This is inferred from the plugin name.
+        """
+        return cls.__name__.replace("Plugin", "")  # type: ignore[attr-defined]
+
+    @cached_property
+    def data_source_mismatch_penalty(self) -> float:
+        try:
+            return self.config["source_weight"].as_number()
+        except NotFoundError:
+            return self.config["data_source_mismatch_penalty"].as_number()
+
     def __init__(self, *args, **kwargs) -> None:
         super().__init__(*args, **kwargs)
         self.config.add(
             {
                 "search_limit": 5,
-                "source_weight": 0.5,
+                "data_source_mismatch_penalty": self.DEFAULT_DATA_SOURCE_MISMATCH_PENALTY,  # noqa: E501
             }
         )
 
@@ -224,35 +191,6 @@ def tracks_for_ids(self, ids: Sequence[str]) -> Iterable[TrackInfo | None]:
 
         return (self.track_for_id(id) for id in ids)
 
-    def album_distance(
-        self,
-        items: Sequence[Item],
-        album_info: AlbumInfo,
-        mapping: dict[Item, TrackInfo],
-    ) -> Distance:
-        """Calculate the distance for an album based on its items and album info."""
-        return _get_distance(
-            data_source=self.data_source, info=album_info, config=self.config
-        )
-
-    def track_distance(
-        self,
-        item: Item,
-        info: TrackInfo,
-    ) -> Distance:
-        """Calculate the distance for a track based on its item and track info."""
-        return _get_distance(
-            data_source=self.data_source, info=info, config=self.config
-        )
-
-    @cached_classproperty
-    def data_source(cls) -> str:
-        """The data source name for this plugin.
-
-        This is inferred from the plugin name.
-        """
-        return cls.__name__.replace("Plugin", "")  # type: ignore[attr-defined]
-
     def _extract_id(self, url: str) -> str | None:
         """Extract an ID from a URL for this metadata source plugin.
 

beets/plugins.py

@@ -20,6 +20,7 @@
 import inspect
 import re
 import sys
+import warnings
 from collections import defaultdict
 from functools import wraps
 from importlib import import_module
@@ -160,19 +161,46 @@ class BeetsPlugin(metaclass=abc.ABCMeta):
     import_stages: list[ImportStageFunc]
 
     def __init_subclass__(cls) -> None:
-        # Dynamically copy methods to BeetsPlugin for legacy support
-        # TODO: Remove this in the future major release, v3.0.0
+        """Enable legacy metadata‐source plugins to work with the new interface.
+
+        When a plugin subclass of BeetsPlugin defines a `data_source` attribute
+        but does not inherit from MetadataSourcePlugin, this hook:
+
+        1. Skips abstract classes.
+        2. Warns that the class should extend MetadataSourcePlugin (deprecation).
+        3. Copies any nonabstract methods from MetadataSourcePlugin onto the
+           subclass to provide the full plugin API.
+
+        This compatibility layer will be removed in the v3.0.0 release.
+        """
+        # TODO: Remove in v3.0.0
         if inspect.isabstract(cls):
             return
 
         from beets.metadata_plugins import MetadataSourcePlugin
 
-        abstractmethods = MetadataSourcePlugin.__abstractmethods__
+        if issubclass(cls, MetadataSourcePlugin) or not hasattr(
+            cls, "data_source"
+        ):
+            return
+
+        warnings.warn(
+            f"{cls.__name__} is used as a legacy metadata source. "
+            "It should extend MetadataSourcePlugin instead of BeetsPlugin. "
+            "Support for this will be removed in the v3.0.0 release!",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+
         for name, method in inspect.getmembers(
-            MetadataSourcePlugin, predicate=inspect.isfunction
+            MetadataSourcePlugin,
+            predicate=lambda f: (
+                inspect.isfunction(f)
+                and f.__name__ not in MetadataSourcePlugin.__abstractmethods__
+                and not hasattr(cls, f.__name__)
+            ),
         ):
-            if name not in abstractmethods and not hasattr(cls, name):
-                setattr(cls, name, method)
+            setattr(cls, name, method)
 
     def __init__(self, name: str | None = None):
         """Perform one-time plugin setup."""
@@ -197,6 +225,37 @@ def __init__(self, name: str | None = None):
         if not any(isinstance(f, PluginLogFilter) for f in self._log.filters):
             self._log.addFilter(PluginLogFilter(self))
 
+        # In order to verify the config we need to make sure the plugin is fully
+        # configured (plugins usually add the default configuration *after*
+        # calling super().__init__()).
+        self.register_listener("pluginload", self.verify_config)
+
+    def verify_config(self, *_, **__) -> None:
+        """Verify plugin configuration.
+
+        If deprecated 'source_weight' option is explicitly set by the user, they
+        will see a warning in the logs. Otherwise, this must be configured by
+        a third party plugin, thus we raise a deprecation warning which won't be
+        shown to user but will be visible to plugin developers.
+        """
+        # TODO: Remove in v3.0.0
+        if (
+            not hasattr(self, "data_source")
+            or "source_weight" not in self.config
+        ):
+            return
+
+        message = (
+            "'source_weight' configuration option is deprecated and will be"
+            " removed in v3.0.0. Use 'data_source_mismatch_penalty' instead"
+        )
+        for source in self.config.root().sources:
+            if "source_weight" in (source.get(self.name) or {}):
+                if source.filename:  # user config
+                    self._log.warning(message)
+                else:  # 3rd-party plugin config
+                    warnings.warn(message, DeprecationWarning, stacklevel=0)
+
     def commands(self) -> Sequence[Subcommand]:
         """Should return a list of beets.ui.Subcommand objects for
         commands that should be added to beets' CLI.

beets/test/helper.py

@@ -58,7 +58,6 @@
 from beets.util import (
     MoveOperation,
     bytestring_path,
-    cached_classproperty,
     clean_module_tempdir,
     syspath,
 )
@@ -495,7 +494,6 @@ def load_plugins(self, *plugins: str) -> None:
         # FIXME this should eventually be handled by a plugin manager
         plugins = (self.plugin,) if hasattr(self, "plugin") else plugins
         self.config["plugins"] = plugins
-        cached_classproperty.cache.clear()
         beets.plugins.load_plugins()
 
     def unload_plugins(self) -> None:

beets/util/__init__.py

@@ -836,9 +836,10 @@ def get_most_common_tags(
         "country",
         "media",
         "albumdisambig",
+        "data_source",
     ]
     for field in fields:
-        values = [item[field] for item in items if item]
+        values = [item.get(field) for item in items if item]
         likelies[field], freq = plurality(values)
         consensus[field] = freq == len(values)
 

beetsplug/beatport.py

@@ -328,7 +328,6 @@ def __init__(self):
                 "apikey": "57713c3906af6f5def151b33601389176b37b429",
                 "apisecret": "b3fe08c93c80aefd749fe871a16cd2bb32e2b954",
                 "tokenfile": "beatport_token.json",
-                "source_weight": 0.5,
             }
         )
         self.config["apikey"].redact = True

beetsplug/discogs.py

@@ -129,7 +129,6 @@ def __init__(self):
                 "apikey": API_KEY,
                 "apisecret": API_SECRET,
                 "tokenfile": "discogs_token.json",
-                "source_weight": 0.5,
                 "user_token": "",
                 "separator": ", ",
                 "index_tracks": False,

docs/changelog.rst

@@ -45,6 +45,10 @@ Bug fixes:
   an import of another :class:`beets.plugins.BeetsPlugin` class. :bug:`6033`
 - :doc:`/plugins/fromfilename`: Fix :bug:`5218`, improve the code (refactor
   regexps, allow for more cases, add some logging), add tests.
+- Metadata source plugins: Fixed data source penalty calculation that was
+  incorrectly applied during import matching. The ``source_weight``
+  configuration option has been renamed to ``data_source_mismatch_penalty`` to
+  better reflect its purpose. :bug:`6066`
 
 For packagers:
 
@@ -66,12 +70,22 @@ Other changes:
   disambiguation stripping.
 - When installing ``beets`` via git or locally the version string now reflects
   the current git branch and commit hash. :bug:`4448`
+- :ref:`match-config`: ``match.distance_weights.source`` configuration has been
+  renamed to ``match.distance_weights.data_source`` for consistency with the
+  name of the field it refers to.
 
 For developers and plugin authors:
 
 - Typing improvements in ``beets/logging.py``: ``getLogger`` now returns
   ``BeetsLogger`` when called with a name, or ``RootLogger`` when called without
   a name.
+- The ``track_distance()`` and ``album_distance()`` methods have been removed
+  from ``MetadataSourcePlugin``. Distance calculation for data source mismatches
+  is now handled automatically by the core matching logic. This change
+  simplifies the plugin architecture and fixes incorrect penalty calculations.
+  :bug:`6066`
+- Metadata source plugins are now registered globally when instantiated, which
+  makes their handling slightly more efficient.
 
 2.4.0 (September 13, 2025)
 --------------------------