From 84111aa8ee5dc02da32c82a4db37c3d783aaec8c Mon Sep 17 00:00:00 2001
From: J0J0 Todos <jojo@peek-a-boo.at>
Date: Sun, 15 Mar 2026 21:51:07 +0100
Subject: [PATCH] Add extra_debug utility to beets.logging

---
 beets/logging.py | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/beets/logging.py b/beets/logging.py
index 0fc3a13e7..0d5f7b1df 100644
--- a/beets/logging.py
+++ b/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