Merge d362bf5026 into 72b4c77161

docs/changelog.rst

@@ -71,9 +71,10 @@ For plugin developers
 - Colorisation, diff and layout utility helpers previously imported from
   :mod:`beets.ui` now live in :mod:`beets.util.color`, :mod:`beets.util.diff`,
   and :mod:`beets.util.layout`. Update external imports accordingly.
-- The ``tunelog`` logging helper that was exclusively available to the lastgenre
-  plugin is now usable througout beets and was renamed to ``extra_debug``.
-  Import it from the ``beets.logging`` module to use it.
+- The lastgenre ``tunelog`` helper was generalized into
+  :py:meth:`beets.logging.BeetsLogger.extra_debug`, which emits ``DEBUG``
+  messages only at verbosity level 3 or higher (for example ``-vvv``). Plugin
+  authors can use it via ``self._log.extra_debug(...)``.
 
 Other changes
 ~~~~~~~~~~~~~

docs/dev/plugins/other/logging.rst

@@ -3,14 +3,19 @@
 Logging
 =======
 
-Each plugin object has a ``_log`` attribute, which is a ``Logger`` from the
-`standard Python logging module`_. The logger is set up to `PEP 3101`_,
-str.format-style string formatting. So you can write logging calls like this:
+Each plugin object has a ``_log`` attribute, which behaves like a logger from
+the `standard Python logging module`_ but is provided by beets' ``BeetsLogger``
+class. The logger is set up to `PEP 3101`_, str.format-style string formatting.
+So you can write logging calls like this:
 
 .. code-block:: python
 
     self._log.debug("Processing {0.title} by {0.artist}", item)
 
+For especially noisy diagnostics, plugins can use
+``self._log.extra_debug(...)``. These messages are logged at ``DEBUG`` level
+only when beets is run with verbosity level 3 or higher, such as ``-vvv``.
+
 .. _pep 3101: https://peps.python.org/pep-3101/
 
 .. _standard python logging module: https://docs.python.org/3/library/logging.html