Add extra_debug utility to beets.logging

beets/logging.py

@@ -66,6 +66,7 @@ __all__ = [
     "Logger",
     "NullHandler",
     "StreamHandler",
+    "extra_debug",
     "getLogger",
 ]
 
@@ -193,6 +194,19 @@ my_manager = copy(Logger.manager)
 my_manager.loggerClass = BeetsLogger
 
 
+def extra_debug(log: BeetsLogger, msg: str, *args: Any, **kwargs: Any) -> None:
+    """Log a message at DEBUG level only when verbosity level is >= 3.
+
+    Intended for high-verbosity tuning/diagnostic messages that would be too
+    noisy at normal debug level.
+    """
+    # Lazy import to avoid circular dependency (beets.__init__ -> beets.logging)
+    from beets import config
+
+    if config["verbose"].as_number() >= 3:
+        log.debug(msg, *args, **kwargs)
+
+
 @overload
 def getLogger(name: str) -> BeetsLogger: ...
 @overload