Standard plugin logger

[pawamoy]

I find myself duplicating this code in every MkDocs plugin I create:

"""Logging functions."""

from __future__ import annotations

import logging
from typing import Any, MutableMapping


class PluginLogger(logging.LoggerAdapter):
    """A logger adapter to prefix messages with the originating package name."""

    def __init__(self, prefix: str, logger: logging.Logger):
        """Initialize the object.

        Arguments:
            prefix: The string to insert in front of every message.
            logger: The logger instance.
        """
        super().__init__(logger, {})
        self.prefix = prefix

    def process(self, msg: str, kwargs: MutableMapping[str, Any]) -> tuple[str, Any]:
        """Process the message.

        Arguments:
            msg: The message:
            kwargs: Remaining arguments.

        Returns:
            The processed message.
        """
        return f"{self.prefix}: {msg}", kwargs


def get_logger(name: str) -> PluginLogger:
    """Return a logger for plugins.

    Arguments:
        name: The name to use with `logging.getLogger`.

    Returns:
        A logger configured to work well in MkDocs,
            prefixing each message with the plugin package name.
    """
    logger = logging.getLogger(f"mkdocs.plugins.{name}")
    return PluginLogger(name.split(".", 1)[0], logger)

This way I can simply get a logger with logger = get_logger(__name__), and log normally with logger.info("..."), while all messages are correctly picked up by MkDocs logging system, and all messages are prefixed with the plugin package name.

It's a bit annoying to see different styles of logging in MkDocs output depending on the plugin. Some of them don't even hook into MkDocs' logger. It would be nice to offer and advertise a standard way to log things from plugins. Logs would be uniform across all plugins 🙂

Let me know what you think and I can open a PR if you like the idea.

Also, if there's already a way and I missed it, let me know! There were many new, cool features/refactor implemented and I'm not yet familiar with all of them 🙂

Finally, if this is not deemed worth it, I'm happy to provide this as a mkdocs-logging library.

[oprypin]

Looks good! Let's get it into MkDocs.

Just not sure if all plugins will want the prefix to be present in all messages. But it's good for consistency to be opinionated. So nothing to change.

But a nitpick on this initial code:

• PluginLogger has no behavior specific to plugins - should not have the word "plugin"
• get_logger has behavior specific to plugins - maybe should have the word "plugin"

[pawamoy]

Yeah I noticed the names are off, we can change them.

OK great! Well, plugin authors have no obligation to use this if they don't like it.

Also the thing is, as a user, I definitely want to see from what plugin log messages are coming (or even, that they actually come from a plugin). So yeah I think it's good to "enforce" the prefix.

Will send a PR soon. Thanks!