From f8887d48b6b3677bc7462d0bcddfa8a2da6d9c20 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=A0ar=C5=ABnas=20Nejus?= <snejus@protonmail.com>
Date: Tue, 7 Oct 2025 14:19:26 +0100
Subject: [PATCH] Add deprecation warning for <plugin>.source_weight

---
 beets/metadata_plugins.py    |  6 +++++-
 beets/plugins.py             | 31 +++++++++++++++++++++++++++++++
 docs/plugins/index.rst       |  6 ++++++
 docs/plugins/musicbrainz.rst |  2 +-
 4 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/beets/metadata_plugins.py b/beets/metadata_plugins.py
index 5e0d8570d..b865167e4 100644
--- a/beets/metadata_plugins.py
+++ b/beets/metadata_plugins.py
@@ -13,6 +13,7 @@ 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
@@ -106,7 +107,10 @@ class MetadataSourcePlugin(BeetsPlugin, metaclass=abc.ABCMeta):
 
     @cached_property
     def data_source_mismatch_penalty(self) -> float:
-        return self.config["data_source_mismatch_penalty"].as_number()
+        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)
diff --git a/beets/plugins.py b/beets/plugins.py
index 5d3e39cc7..7fa0e660a 100644
--- a/beets/plugins.py
+++ b/beets/plugins.py
@@ -225,6 +225,37 @@ class BeetsPlugin(metaclass=abc.ABCMeta):
         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.
diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst
index 1e1ed43da..7b595ac86 100644
--- a/docs/plugins/index.rst
+++ b/docs/plugins/index.rst
@@ -50,6 +50,8 @@ Using Metadata Source Plugins
 We provide several :ref:`autotagger_extensions` that fetch metadata from online
 databases. They share the following configuration options:
 
+.. _data_source_mismatch_penalty:
+
 - **data_source_mismatch_penalty**: Penalty applied to matches during import.
   Any decimal number between 0 and 1. Default: ``0.5``.
 
@@ -66,6 +68,10 @@ databases. They share the following configuration options:
   By default, all sources are equally preferred with each having
   ``data_source_mismatch_penalty`` set to ``0.5``.
 
+- **source_weight**
+
+  .. deprecated:: 2.5 Use `data_source_mismatch_penalty`_ instead.
+
 - **search_limit**: Maximum number of search results to consider. Default:
   ``5``.
 
diff --git a/docs/plugins/musicbrainz.rst b/docs/plugins/musicbrainz.rst
index 110d9b92c..5ac287368 100644
--- a/docs/plugins/musicbrainz.rst
+++ b/docs/plugins/musicbrainz.rst
@@ -78,7 +78,7 @@ limited_ to one request per second.
 enabled
 +++++++
 
-.. deprecated:: 2.3 Add ``musicbrainz`` to the ``plugins`` list instead.
+.. deprecated:: 2.4 Add ``musicbrainz`` to the ``plugins`` list instead.
 
 This option allows you to disable using MusicBrainz as a metadata source. This
 applies if you use plugins that fetch data from alternative sources and should