lastgenre: Plugin tuning log (-vvv) (#6007)

beetsplug/lastgenre/__init__.py

@@ -106,7 +106,6 @@ class LastGenrePlugin(plugins.BeetsPlugin):
                 "separator": ", ",
                 "prefer_specific": False,
                 "title_case": True,
-                "extended_debug": False,
                 "pretend": False,
             }
         )
@@ -162,6 +161,11 @@ class LastGenrePlugin(plugins.BeetsPlugin):
             flatten_tree(genres_tree, [], c14n_branches)
         return c14n_branches, canonicalize
 
+    def _tunelog(self, msg, *args, **kwargs):
+        """Log tuning messages at DEBUG level when verbosity level is high enough."""
+        if config["verbose"].as_number() >= 3:
+            self._log.debug(msg, *args, **kwargs)
+
     @property
     def sources(self) -> tuple[str, ...]:
         """A tuple of allowed genre sources. May contain 'track',
@@ -293,8 +297,7 @@ class LastGenrePlugin(plugins.BeetsPlugin):
             self._genre_cache[key] = self.fetch_genre(method(*args))
 
         genre = self._genre_cache[key]
-        if self.config["extended_debug"]:
-            self._log.debug("last.fm (unfiltered) {} tags: {}", entity, genre)
+        self._tunelog("last.fm (unfiltered) {} tags: {}", entity, genre)
         return genre
 
     def fetch_album_genre(self, obj):
@@ -554,13 +557,6 @@ class LastGenrePlugin(plugins.BeetsPlugin):
             dest="album",
             help="match albums instead of items (default)",
         )
-        lastgenre_cmd.parser.add_option(
-            "-d",
-            "--debug",
-            action="store_true",
-            dest="extended_debug",
-            help="extended last.fm debug logging",
-        )
         lastgenre_cmd.parser.set_defaults(album=True)
 
         def lastgenre_func(lib, opts, args):

docs/changelog.rst

@@ -14,6 +14,10 @@ New features:
   album artist are the same in ftintitle.
 - :doc:`plugins/play`: Added `$playlist` marker to precisely edit the playlist
       filepath into the command calling the player program.
+- :doc:`plugins/lastgenre`: For tuning plugin settings ``-vvv`` can be passed
+      to receive extra verbose logging around last.fm results and how they are
+      resolved. The ``extended_debug`` config setting and ``--debug`` option
+      have been removed.
 
 Bug fixes:
 

docs/plugins/lastgenre.rst

@@ -197,11 +197,6 @@ file. The available options are:
   internal whitelist, or ``no`` to consider all genres valid. Default: ``yes``.
 - **title_case**: Convert the new tags to TitleCase before saving. Default:
   ``yes``.
-- **extended_debug**: Add additional debug logging messages that show what
-  last.fm tags were fetched for tracks, albums and artists. This is done before
-  any canonicalization and whitelist filtering is applied. It's useful for
-  tuning the plugin's settings and understanding how it works, but it can be
-  quite verbose. Default: ``no``.
 
 Running Manually
 ----------------
@@ -219,3 +214,13 @@ or store any changes.
 
 To disable automatic genre fetching on import, set the ``auto`` config option to
 false.
+
+Tuning Logs
+-----------
+
+To enable tuning logs, run ``beet -vvv lastgenre ...`` or ``beet -vvv import
+...``. This enables additional messages at the ``DEBUG`` log level, showing for
+example what data was received from last.fm at each stage of genre fetching
+(artist, album, and track levels) before any canonicalization or whitelist
+filtering is applied. Tuning logs are useful for adjusting the plugin’s settings
+and understanding its behavior, though they can be quite verbose.