import logging


def initialise_logger(name, 
                      logfile, 
                      file_format_str = '%(asctime)s - %(name)s - %(levelname)s - %(message)s',
                      print_to_console = False,
                      console_format_str = '%(asctime)s - %(name)s - %(levelname)s - %(message)s',
                      level = "INFO"):
    """
    Initialise a logger object (from the logging module), to write logs to 
    a specified logfile.

    Parameters
    ----------
    name : str
        logger name.
    logfile : str
        name/path to the log file.
        
    file_format_str : str, optional
        Specifies the format of the log messages to the log file 
        (see documentation of logging module). 
        The default is '%(asctime)s - %(name)s - %(levelname)s - %(message)s'.
        
    print_to_console : bool, optional
        Switch to print log messages to console. The default is True.
    console_format_str : str, optional
        When `print_to_console == True`, this specifies the format of the log 
        messages to the console (see documentation of logging module). 
        The default is '%(asctime)s - %(name)s - %(levelname)s - %(message)s'.
    
    Returns
    -------
    logger : logger object

    """
    # basic configurations
    #=====================
    logging.basicConfig(level=getattr(logging,level))
    logger = logging.getLogger(name)
    
    # file log handler
    #=================
    file_log_handler = logging.FileHandler(logfile)
    file_log_handler.setFormatter(logging.Formatter(file_format_str))
    logger.addHandler(file_log_handler)
    
    # console log handler
    #====================
    if print_to_console:
        console_log_handler = logging.StreamHandler()
        console_log_handler.setFormatter(logging.Formatter(console_format_str))
        logger.addHandler(console_log_handler)
    
    return logger