#
# @file  log.py
# @brief Debug logging support for Morg.
#

#
# Copyright (C) 2014 The Morg Project Developers
#
# See wiki/copyright.wiki in the top-level directory of the Morg source
# distribution for the full list of authors who have contributed to this
# project.
#

#
# This file is part of Morg.
#
# Morg is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your
# option) any later version.
#
# Morg is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License
# along with Morg. If not, see <http://www.gnu.org/licenses/>.
#

#------------------------------- IMPORTS --------------------------------

# Morg
import morg_error

# Standard library
import logging
import os

#----------------------------- EXCEPTIONS -------------------------------

class logging_error(morg_error.error_base):
    '''For reporting logging-related errors.'''
    pass

#--------------------------- INITIALIZATION -----------------------------

def init(log_level, log_file):
    '''Initialize Morg's debug logging.

    @param log_level (int) The logging level specified by user.
    @param log_file (string) Where to send debug messages.

    If <tt>level</tt> is <tt>logging.NOTSET</tt>, this function will use
    a null handler so that no log messages are emitted by any part of
    Morg. Otherwise, it will setup Python's logging module to send
    messages to the specified log file.

    @note Any non-existent directories in the path to the log file will
    be created automatically.

    '''
    if (log_level == logging.NOTSET):
        logging.basicConfig(stream = 'logging.NullHandler')
    else:
        try:
            os.makedirs(os.path.dirname(log_file))
        except OSError:
            pass
        try:
            fmt = ('%(asctime)s.%(msecs)03d %(levelname)-9s' +
                   '%(name)-18s%(lineno)-5s%(funcName)s\n  ' +
                   '  %(message)s')
            logging.basicConfig(filename = log_file,
                                filemode = 'w',
                                level    = log_level,
                                format   = fmt,
                                datefmt  = '%Y-%m-%d %H:%M:%S')
        except IOError:
            raise logging_error('unable to create log file {}'.
                                format(log_file))

#------------------------------------------------------------------------

##############################################
# Editor config:                             #
##############################################
# Local Variables:                           #
# indent-tabs-mode: nil                      #
# py-indent-offset: 4                        #
# python-indent: 4                           #
# End:                                       #
##############################################
# vim: set expandtab shiftwidth=4 tabstop=4: #
##############################################
