Add configurable search limit to Spotify and Deezer plugins, and make the option name consistent (#5960)

- Add configurable `search_limit` option to Deezer and Spotify plugins
(default 5) and enforce it when returning search results.
- Rename `musicbrainz.searchlimit` to `musicbrainz.search_limit` (old
key still read with deprecation warning; slated for removal in 3.0.0).
- Update docs and changelog to reflect the changes.

beets/metadata_plugins.py

@@ -148,7 +148,12 @@ class MetadataSourcePlugin(BeetsPlugin, metaclass=abc.ABCMeta):
 
     def __init__(self, *args, **kwargs) -> None:
         super().__init__(*args, **kwargs)
-        self.config.add({"source_weight": 0.5})
+        self.config.add(
+            {
+                "search_limit": 5,
+                "source_weight": 0.5,
+            }
+        )
 
     @abc.abstractmethod
     def album_for_id(self, album_id: str) -> AlbumInfo | None:

beetsplug/deezer.py

@@ -49,6 +49,9 @@ class DeezerPlugin(SearchApiMetadataSourcePlugin[IDResponse]):
     album_url = "https://api.deezer.com/album/"
     track_url = "https://api.deezer.com/track/"
 
+    def __init__(self) -> None:
+        super().__init__()
+
     def commands(self):
         """Add beet UI commands to interact with Deezer."""
         deezer_update_cmd = ui.Subcommand(
@@ -245,7 +248,10 @@ class DeezerPlugin(SearchApiMetadataSourcePlugin[IDResponse]):
         try:
             response = requests.get(
                 f"{self.search_url}{query_type}",
-                params={"q": query},
+                params={
+                    "q": query,
+                    "limit": self.config["search_limit"].get(),
+                },
                 timeout=10,
             )
             response.raise_for_status()

beetsplug/discogs.py

@@ -96,7 +96,6 @@ class DiscogsPlugin(MetadataSourcePlugin):
                 "separator": ", ",
                 "index_tracks": False,
                 "append_style_genre": False,
-                "search_limit": 5,
             }
         )
         self.config["apikey"].redact = True
@@ -250,7 +249,7 @@ class DiscogsPlugin(MetadataSourcePlugin):
 
         try:
             results = self.discogs_client.search(query, type="release")
-            results.per_page = self.config["search_limit"].as_number()
+            results.per_page = self.config["search_limit"].get()
             releases = results.page(1)
         except CONNECTION_ERRORS:
             self._log.debug(

beetsplug/musicbrainz.py

@@ -18,12 +18,14 @@ from __future__ import annotations
 
 import traceback
 from collections import Counter
+from contextlib import suppress
 from functools import cached_property
 from itertools import product
 from typing import TYPE_CHECKING, Any, Iterable, Sequence
 from urllib.parse import urljoin
 
 import musicbrainzngs
+from confuse.exceptions import NotFoundError
 
 import beets
 import beets.autotag.hooks
@@ -371,7 +373,6 @@ class MusicBrainzPlugin(MetadataSourcePlugin):
                 "https": False,
                 "ratelimit": 1,
                 "ratelimit_interval": 1,
-                "searchlimit": 5,
                 "genres": False,
                 "external_ids": {
                     "discogs": False,
@@ -383,6 +384,15 @@ class MusicBrainzPlugin(MetadataSourcePlugin):
                 "extra_tags": [],
             },
         )
+        # TODO: Remove in 3.0.0
+        with suppress(NotFoundError):
+            self.config["search_limit"] = self.config["match"][
+                "searchlimit"
+            ].get()
+            self._log.warning(
+                "'musicbrainz.searchlimit' option is deprecated and will be "
+                "removed in 3.0.0. Use 'musicbrainz.search_limit' instead."
+            )
         hostname = self.config["host"].as_str()
         https = self.config["https"].get(bool)
         # Only call set_hostname when a custom server is configured. Since
@@ -799,7 +809,7 @@ class MusicBrainzPlugin(MetadataSourcePlugin):
         )
         try:
             method = getattr(musicbrainzngs, f"search_{query_type}s")
-            res = method(limit=self.config["searchlimit"].get(int), **filters)
+            res = method(limit=self.config["search_limit"].get(), **filters)
         except musicbrainzngs.MusicBrainzError as exc:
             raise MusicBrainzAPIError(
                 exc, f"{query_type} search", filters, traceback.format_exc()

beetsplug/spotify.py

@@ -442,7 +442,11 @@ class SpotifyPlugin(
             response = self._handle_response(
                 "get",
                 self.search_url,
-                params={"q": query, "type": query_type},
+                params={
+                    "q": query,
+                    "type": query_type,
+                    "limit": self.config["search_limit"].get(),
+                },
             )
         except APIError as e:
             self._log.debug("Spotify API error: {}", e)

docs/changelog.rst

@@ -32,6 +32,8 @@ New features:
   ``played_ratio_threshold``, to allow configuring the percentage the song must
   be played for it to be counted as played instead of skipped.
 - :doc:`plugins/web`: Display artist and album as part of the search results.
+- :doc:`plugins/spotify` :doc:`plugins/deezer`: Add new configuration option
+  ``search_limit`` to limit the number of results returned by search queries.
 
 Bug fixes:
 
@@ -2552,7 +2554,7 @@ Major new features and bigger changes:
   analysis tool. Thanks to :user:`jmwatte`. :bug:`1343`
 - A new ``filesize`` field on items indicates the number of bytes in the file.
   :bug:`1291`
-- A new :ref:`searchlimit` configuration option allows you to specify how many
+- A new :ref:`search_limit` configuration option allows you to specify how many
   search results you wish to see when looking up releases at MusicBrainz during
   import. :bug:`1245`
 - The importer now records the data source for a match in a new flexible

docs/plugins/deezer.rst

@@ -27,7 +27,11 @@ Configuration
 -------------
 
 This plugin can be configured like other metadata source plugins as described in
-:ref:`metadata-source-plugin-configuration`.
+:ref:`metadata-source-plugin-configuration`. In addition, the following
+configuration options are provided.
+
+- **search_limit**: The maximum number of results to return from Deezer for each
+  search query. Default: ``5``.
 
 The default options should work as-is, but there are some options you can put in
 config.yaml under the ``deezer:`` section:

docs/plugins/musicbrainz.rst

@@ -27,7 +27,7 @@ Default
         https: no
         ratelimit: 1
         ratelimit_interval: 1.0
-        searchlimit: 5
+        search_limit: 5
         extra_tags: []
         genres: no
         external_ids:
@@ -82,16 +82,21 @@ make the import process quicker.
 
 Default: ``yes``.
 
-.. _searchlimit:
+.. _search_limit:
 
-searchlimit
-+++++++++++
+search_limit
+++++++++++++
 
 The number of matches returned when sending search queries to the MusicBrainz
 server.
 
 Default: ``5``.
 
+searchlimit
++++++++++++
+
+.. deprecated:: 2.4 Use `search_limit`_.
+
 .. _extra_tags:
 
 extra_tags

docs/plugins/spotify.rst

@@ -98,6 +98,8 @@ config.yaml under the ``spotify:`` section:
   enhance search results in some cases, but in general, it is not recommended.
   For instance ``artist:deadmau5 album:4×4`` will be converted to
   ``artist:deadmau5 album:4x4`` (notice ``×!=x``). Default: ``no``.
+- **search_limit**: The maximum number of results to return from Spotify for
+  each search query. Default: ``5``.
 
 Here's an example: