Skip to content

loggers ¤

Logging functions.

Classes:

Functions:

LoggerAdapter ¤

LoggerAdapter(prefix: str, logger: Logger)

Bases: LoggerAdapter

A logger adapter to prefix messages.

This adapter also adds an additional parameter to logging methods called once: if True, the message will only be logged once.

Examples:

In Python code:

>>> logger = get_logger("myplugin")
>>> logger.debug("This is a debug message.")
>>> logger.info("This is an info message.", once=True)

In Jinja templates (logger available in context as log):

{{ log.debug("This is a debug message.") }}
{{ log.info("This is an info message.", once=True) }}

Parameters:

  • prefix ¤

    (str) –

    The string to insert in front of every message.

  • logger ¤

    (Logger) –

    The logger instance.

Methods:

  • log –

    Log a message.

  • process –

    Process the message.

Source code in src/mkdocstrings/loggers.py 
48
49
50
51
52
53
54
55
56
57
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
    self._logged: set[tuple[LoggerAdapter, str]] = set()

log ¤

log(
    level: int, msg: object, *args: object, **kwargs: object
) -> None

Log a message.

Parameters:

  • level ¤

    (int) –

    The logging level.

  • msg ¤

    (object) –

    The message.

  • *args ¤

    (object, default: () ) –

    Additional arguments passed to parent method.

  • **kwargs ¤

    (object, default: {} ) –

    Additional keyword arguments passed to parent method.

Source code in src/mkdocstrings/loggers.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def log(self, level: int, msg: object, *args: object, **kwargs: object) -> None:
    """Log a message.

    Arguments:
        level: The logging level.
        msg: The message.
        *args: Additional arguments passed to parent method.
        **kwargs: Additional keyword arguments passed to parent method.
    """
    if kwargs.pop("once", False):
        if (key := (self, str(msg))) in self._logged:
            return
        self._logged.add(key)
    super().log(level, msg, *args, **kwargs)  # type: ignore[arg-type]

process ¤

process(
    msg: str, kwargs: MutableMapping[str, Any]
) -> tuple[str, Any]

Process the message.

Parameters:

Returns:

Source code in src/mkdocstrings/loggers.py 
59
60
61
62
63
64
65
66
67
68
69
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

TemplateLogger ¤

TemplateLogger(logger: LoggerAdapter)

A wrapper class to allow logging in templates.

The logging methods provided by this class all accept two parameters:

  • msg: The message to log.
  • once: If True, the message will only be logged once.

Methods:

  • debug –

    Function to log a DEBUG message.

  • info –

    Function to log an INFO message.

  • warning –

    Function to log a WARNING message.

  • error –

    Function to log an ERROR message.

  • critical –

    Function to log a CRITICAL message.

Parameters:

Source code in src/mkdocstrings/loggers.py 
104
105
106
107
108
109
110
111
112
113
114
def __init__(self, logger: LoggerAdapter):
    """Initialize the object.

    Arguments:
        logger: A logger adapter.
    """
    self.debug = get_template_logger_function(logger.debug)
    self.info = get_template_logger_function(logger.info)
    self.warning = get_template_logger_function(logger.warning)
    self.error = get_template_logger_function(logger.error)
    self.critical = get_template_logger_function(logger.critical)

get_logger ¤

get_logger(name: str) -> LoggerAdapter

Return a pre-configured logger.

Parameters:

  • name ¤

    (str) –

    The name to use with logging.getLogger.

Returns:

Source code in src/mkdocstrings/loggers.py 
167
168
169
170
171
172
173
174
175
176
177
def get_logger(name: str) -> LoggerAdapter:
    """Return a pre-configured logger.

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

    Returns:
        A logger configured to work well in MkDocs.
    """
    logger = logging.getLogger(f"mkdocs.plugins.{name}")
    return LoggerAdapter(name.split(".", 1)[0], logger)

get_template_logger ¤

get_template_logger(
    handler_name: str | None = None,
) -> TemplateLogger

Return a logger usable in templates.

Parameters:

  • handler_name ¤

    (str | None, default: None ) –

    The name of the handler.

Returns:

Source code in src/mkdocstrings/loggers.py 
180
181
182
183
184
185
186
187
188
189
190
def get_template_logger(handler_name: str | None = None) -> TemplateLogger:
    """Return a logger usable in templates.

    Parameters:
        handler_name: The name of the handler.

    Returns:
        A template logger.
    """
    handler_name = handler_name or "base"
    return TemplateLogger(get_logger(f"mkdocstrings_handlers.{handler_name}.templates"))

get_template_logger_function ¤

get_template_logger_function(
    logger_func: Callable,
) -> Callable

Create a wrapper function that automatically receives the Jinja template context.

Parameters:

  • logger_func ¤

    (Callable) –

    The logger function to use within the wrapper.

Returns:

Source code in src/mkdocstrings/loggers.py 
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
def get_template_logger_function(logger_func: Callable) -> Callable:
    """Create a wrapper function that automatically receives the Jinja template context.

    Arguments:
        logger_func: The logger function to use within the wrapper.

    Returns:
        A function.
    """

    @pass_context
    def wrapper(context: Context, msg: str | None = None, **kwargs: Any) -> str:
        """Log a message.

        Arguments:
            context: The template context, automatically provided by Jinja.
            msg: The message to log.
            **kwargs: Additional arguments passed to the logger function.

        Returns:
            An empty string.
        """
        template_path = get_template_path(context)
        logger_func(f"{template_path}: {msg or 'Rendering'}", **kwargs)
        return ""

    return wrapper

get_template_path ¤

get_template_path(context: Context) -> str

Return the path to the template currently using the given context.

Parameters:

  • context ¤

    (Context) –

    The template context.

Returns:

  • str –

    The relative path to the template.

Source code in src/mkdocstrings/loggers.py 
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
def get_template_path(context: Context) -> str:
    """Return the path to the template currently using the given context.

    Arguments:
        context: The template context.

    Returns:
        The relative path to the template.
    """
    context_name: str = str(context.name)
    filename = context.environment.get_template(context_name).filename
    if filename:
        for template_dir in TEMPLATES_DIRS:
            with suppress(ValueError):
                return str(Path(filename).relative_to(template_dir))
        with suppress(ValueError):
            return str(Path(filename).relative_to(Path.cwd()))
        return filename
    return context_name