#
# -----------------
# Copyright © 2024 ACK Cyfronet AGH, Poland.
# -----------------
#
import os
import logging

def getDefaultLogger(name):
    """
    Retrieves or creates a logger with the specified name and sets it up with a file handler.
    
    The logger is configured to write log messages to the file path specified by the
    'DEFAULT_LOG_PATH' environment variable. It uses the 'INFO' level as the default
    logging level and writes log entries in the following format:
    
    'YYYY-MM-DD HH:MM:SS,ms LEVEL logger_name message'
    
    If the logger does not already have handlers, a file handler is created, and the 
    logging output is appended to the file. The log format includes the timestamp with 
    milliseconds, log level, logger name, and the log message.

    Parameters:
    -----------
    name : str
        The name of the logger. This can be the name of the module or any identifier 
        that you want to associate with the logger.

    Returns:
    --------
    logger : logging.Logger
        A logger instance with the specified name. The logger is configured with a 
        file handler that writes to the file specified by the 'DEFAULT_LOG_PATH' 
        environment variable.
    
    Raises:
    -------
    KeyError:
        If the 'DEFAULT_LOG_PATH' environment variable is not set.
    
    Example:
    --------
    logger = getDefaultLogger(__name__)
    logger.info("This is an info message.")
    try:
        raise Exception('Exception for example.')
    except Exception as e:
        logger.error('An error occurred:', exc_info=True)  # Log with stack trace

    """
    logger = logging.getLogger(name)
    if not logger.hasHandlers():
        file_handler = logging.FileHandler(os.environ['APP_LOG_FILE'], mode='a')
        formatter = logging.Formatter('%(asctime)s,%(msecs)d %(levelname)s %(name)s %(message)s')
        file_handler.setFormatter(formatter)
        logger.addHandler(file_handler)
    logger.setLevel(logging.INFO)
    
    return logger