Source code for core_mixins.logger

# -*- coding: utf-8 -*-

"""
This module provides a function to create a logger, that is ready to
successfully log information in AWS Lambdas or ECS where
without the appropriate configuration your logs will
not show up in CloudWatch.
"""

from __future__ import annotations

import logging
import sys
import typing


# pylint: disable=too-many-arguments,too-many-positional-arguments


def get_logger(
    logger_name: typing.Optional[str] = None,
    log_level: int = logging.INFO,
    propagate: bool = True,
    stream_handler: typing.Optional[typing.TextIO] = sys.stdout,
    formatter: str = "[%(levelname)s] %(message)s",
    reset_handlers: bool = False,
) -> logging.Logger:
    """
    It returns a logger or create it if it doesn't exist. If the logger name
    is not specified, it returns the root logger....

    A handler is only added when the logger has none yet, so repeated
    module-level calls (e.g. ``logger = get_logger(__name__)``) never
    accumulate duplicate handlers.  Pass ``reset_handlers=True`` to
    intentionally replace the existing handler (e.g. to change the
    formatter or stream).

    :param logger_name: Logger's name or None for root logger.
    :param log_level:  The logging level (CRITICAL = 50, ERROR = 40, WARNING = 30, INFO = 20)

    :param stream_handler:
        A handler which writes logging records, appropriately
        formatted to a stream.

    :param formatter:
        It specifies the layout of log records in the final output. It defines the structure
        of log messages by specifying a format string that includes placeholders for
        various attributes of a log record, such as timestamp, log level,
        logger name, and the log message itself...

    :param propagate:
        It determines whether a log message should be passed to the handlers of
        higher-level (ancestor) loggers.This can be useful in situations where you want
        to control the flow of log messages and avoid duplication in the
        log output (like Lambda Functions)...

    :param reset_handlers:
        When ``True``, existing handlers are removed before adding the new
        one, allowing the logger to be reconfigured with a different
        stream or formatter.

    :return: The logger.
    """

    logger = logging.getLogger(logger_name)
    logger.propagate = propagate
    logger.setLevel(log_level)

    if reset_handlers:
        logger.handlers = []

    if not logger.handlers:
        handler = logging.StreamHandler(stream=stream_handler)
        handler.setFormatter(logging.Formatter(formatter))
        handler.setLevel(log_level)
        logger.addHandler(handler)

    return logger