Skip to content

loggers.py

Logging functions.

LoggerAdapter ¤

A logger adapter to prefix messages.

__init__(self, prefix, logger) special ¤

Initialize the object.

Parameters:

Name Type Description Default
prefix str

The string to insert in front of every message.

required
logger

The logger instance.

required
Source code in mkdocstrings/loggers.py
def __init__(self, prefix: str, 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

process(self, msg, kwargs) ¤

Process the message.

Parameters:

Name Type Description Default
msg str

The message:

required
kwargs

Remaining arguments.

required

Returns:

Type Description
Tuple[str, Any]

The processed message.

Source code in mkdocstrings/loggers.py
def process(self, msg: str, kwargs) -> Tuple[str, Any]:
    """Process the message.

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

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

TemplateLogger ¤

A wrapper class to allow logging in templates.

Attributes:

Name Type Description
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.

__init__(self, logger) special ¤

Initialize the object.

Parameters:

Name Type Description Default
logger LoggerAdapter

A logger adapter.

required
Source code in mkdocstrings/loggers.py
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(name) ¤

Return a pre-configured logger.

Parameters:

Name Type Description Default
name str

The name to use with logging.getLogger.

required

Returns:

Type Description
LoggerAdapter

A logger configured to work well in MkDocs.

Source code in mkdocstrings/loggers.py
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}")
    logger.addFilter(warning_filter)
    return LoggerAdapter(name, logger)

get_template_logger() ¤

Return a logger usable in templates.

Returns:

Type Description
TemplateLogger

A template logger.

Source code in mkdocstrings/loggers.py
def get_template_logger() -> TemplateLogger:
    """Return a logger usable in templates.

    Returns:
        A template logger.
    """
    return TemplateLogger(get_logger("mkdocstrings.templates"))

get_template_logger_function(logger_func) ¤

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

Parameters:

Name Type Description Default
logger_func Callable

The logger function to use within the wrapper.

required

Returns:

Type Description
Callable

A function.

Source code in mkdocstrings/loggers.py
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.
    """

    @contextfunction
    def wrapper(context: Context, msg: Optional[str] = None) -> str:
        """Log a message.

        Arguments:
            context: The template context, automatically provided by Jinja.
            msg: The message to log.

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

    return wrapper

get_template_path(context) ¤

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

Parameters:

Name Type Description Default
context Context

The template context.

required

Returns:

Type Description
str

The relative path to the template.

Source code in mkdocstrings/loggers.py
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.
    """
    filename = context.environment.get_template(context.name).filename
    if filename:
        try:
            return str(Path(filename).relative_to(TEMPLATES_DIR))
        except ValueError:
            return filename
    return context.name
Back to top