From d362bf5026057fbe19ee4da293892a6319f380cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0ar=C5=ABnas=20Nejus?= Date: Mon, 23 Mar 2026 19:16:14 +0000 Subject: [PATCH] Document extra_debug logging method for plugin authors Update changelog and plugin logging docs to describe the new `BeetsLogger.extra_debug` method, which emits DEBUG messages only at verbosity level 3 or higher (-vvv). --- docs/changelog.rst | 7 ++++--- docs/dev/plugins/other/logging.rst | 11 ++++++++--- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index cea7cd42b..9b834ee6f 100644 --- a/docs/changelog.rst +++ b/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 ~~~~~~~~~~~~~ diff --git a/docs/dev/plugins/other/logging.rst b/docs/dev/plugins/other/logging.rst index c44e690c4..ae751ca42 100644 --- a/docs/dev/plugins/other/logging.rst +++ b/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