logmod.py

"""Contain function to display or store logging messages."""
import logging
import sys
import os
import datetime as dt
from typing import Union, Optional
import common


def logs(
        show_level: Optional[Union[int, str]] = None,
        save_level: Optional[Union[int, str]] = None,
        program_name: Optional[str] = None,
        path: Optional[str] = None,
        threads: bool = False,
        multiproc: bool = False,
        show_color: bool = True
) -> None:
    """
    Initialize the logger.

    Parameters
    ----------
    show_level : int or {'debug', 'info', warning', 'error', 'exception'},
        optional. Pass a log level to display logs of that level and above.
    save_level : int or {'debug', 'info', warning', 'error', 'exception'},
        optional. Pass a log level to store logs of that level and above to
        a file on disk. If no path is passed the default `_cache` folder will
        be used.
    program_name : str, optional
        When saving logs to disk this string will be used in the filename.
    path : str, optional
        Path where log files will be stored. Defaults to the `_cache` folder.
    threads : bool, default False
        Add the thread name to log messages. Useful when using threading.
    multiproc : bool, default False
        Add the process name to log messages. Useful when using
        multiprocessing.
    show_color : bool, default True
        If you have the coloredlogs package installed the messages will be
        colored.

    Note that log levels can be one of the listed strings or an integer between
    1 and 100. If you want to get all possible log messages, use a log level of
    1.
    """
    logger_root = logging.getLogger()
    fmt_items = ('%(asctime)s',
                 '%(levelname)-8s',
                 '%(threadName)s' if threads else None,
                 '%(processName)s' if multiproc else None,
                 '%(name)s',
                 '%(message)s')
    fmt = ' - '.join((item for item in fmt_items if item is not None))
    formatter = logging.Formatter(fmt)
    logging.addLevelName(5, "VERBOSE")
    logger_root.setLevel(5)

    if show_level and show_color:
        try:
            import coloredlogs
        except ImportError:
            show_color = False
        else:
            coloredlogs.install(fmt=fmt,
                                level=_convert_logging_level(show_level),
                                stream=sys.stdout)
    if show_level and not show_color:
        stream_handler = logging.StreamHandler()
        stream_handler.setLevel(_convert_logging_level(show_level))
        stream_handler.setFormatter(formatter)
        logger_root.addHandler(stream_handler)
    if save_level:
        if program_name is None:
            program_name = 'noname'
        date_str = dt.datetime.utcnow().strftime('%Y-%m-%d_%H-%M-%S')
        log_filename = 'log_{}_{}.log'.format(program_name, date_str)
        if path is None:
            path = common.log_dir
        file_handler = logging.FileHandler(filename=os.path.join(path,
                                                                 log_filename))
        file_handler.setFormatter(formatter)
        file_handler.setLevel(_convert_logging_level(save_level))
        logger_root.addHandler(file_handler)
    _logging_level_threshold()


def _logging_level_threshold():
    """
    Set the level threshold for a couple of internal and external modules.
    """
    for mod_name in ['requests', 'matplotlib', 'numexpr.utils',
                     'urllib3.connectionpool', 'PIL.TiffImagePlugin']:
        logging.getLogger(mod_name).setLevel(logging.WARNING)


def _convert_logging_level(level: Union[int, str]) -> int:
    """Convert the user-provided level to a logging level integer."""
    if isinstance(level, int):
        assert 0 < level <= 50, 'Logging level must be between 0 and 50.'
        return level
    if not hasattr(logging, level.upper()):
        raise ValueError('Unknown logging level name: {}.'.format(level))
    return getattr(logging, level.upper())