# -*- coding: utf-8 -*-
#
-# Copyright (C) 2007-2014 CEA/DEN, EDF R&D, OPEN CASCADE
+# Copyright (C) 2007-2021 CEA/DEN, EDF R&D, OPEN CASCADE
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
#=============================================================================
# Author : Guillaume Boulant (CSSI)
# Rewritten by Renaud Barate (EDF R&D)
-# Project : SALOME
-# Copyright : EDF 2001-2009
-# $Header$
#=============================================================================
+
+## \defgroup logger logger
+# \{
+# \details
+# This module defines a class which provides logging facility in Salome.
+# \}
+
"""
This module defines a class which provides logging facility in Salome:
"""
from salome.kernel import termcolor
import salome.kernel.logconfig
+## This class formats and displays log messages in Salome environment. It
+# inherits \b logging.Logger class defined in \b logging module from Python
+# library, so all methods from \b logging.Logger can be used here.
+# The format of the traces is:
+# LEVEL[keyword] : Message
+#
+# ,where \em LEVEL is the level of the message (\em DEBUG, \em INFO, etc.),
+# \em keyword is the name of the logger, and \em Message is the message to log.
+#
+# When creating a new Logger object, the parameter \em keyword defines the
+# name of the logger, \em level defines the logging level (default is
+# \b logging.DEBUG if KERNEL module is configured with --enable-debug option
+# or \b logging.WARNING otherwise), and \em color defines the color
+# of the log messages for this logger (log messages will appear in color
+# only when displayed on color - capable ASCII terminals). See module
+# \ref termcolor "salome.kernel.termcolor" for the color constants.
+#
+# By default, log messages will be displayed only on standard output. They
+# can also be recorded in a file (see method setLogFile()). For now,
+# the CORBA-based logging facility can not be used through this class.
+#
+# A source filename \em sourceFileName can be defined. If this argument is
+# specified, then the \em keyword is modified to the basename of the
+# \em sourceFileName
+#
+# Basic usage::
+# \code
+# from salome.kernel.logger import Logger
+# log = Logger("Test")
+# log.debug("Debug message")
+# log.info("Information message")
+# log.warning("Warning message")
+# log.error("Error message")
+# log.critical("Fatal error message")
+# \endcode
+# \ingroup logger
class Logger(logging.Logger):
"""
This class formats and displays log messages in Salome environment. It
self.addHandler(self._stdoutHandler)
self._fileHandler = None
+ ## Log all messages, including DEBUG level messages (equivalent to
+ # setLevel(logging.DEBUG)).
def showDebug(self):
"""
Log all messages, including DEBUG level messages (equivalent to
"""
self.setLevel(logging.DEBUG)
+ ## Define a log file to record the log messages (in addition to the
+ # standard output).
def setLogFile(self, logFilename):
"""
Define a log file to record the log messages (in addition to the
self._fileHandler.setFormatter(self._baseFormatter)
self.addHandler(self._fileHandler)
+ ## Set the color of log messages on color-capable terminals. If \em color
+ # is \b None, the default color will be used.
def setColor(self, color):
"""
Set the color of log messages on color-capable terminals. If `color`
stdoutFormatter = logging.Formatter(format)
self._stdoutHandler.setFormatter(stdoutFormatter)
+ ## Close the log file.
def closeLogFile(self):
"""Close the log file."""
if self._fileHandler is not None:
self._fileHandler.close()
self._fileHandler = None
+ ## Hide DEBUG level messages (equivalent to setLevel(logging.INFO)).
def hideDebug(self):
"""
Hide DEBUG level messages (equivalent to ``setLevel(logging.INFO)``).
@deprecated("Deprecated since version 5.1.5. Please replace with "
"Logger.critical(message)")
+
+ ## Log a message with CRITICAL level. This method only exists for
+ # backward compatibility and is equivalent to \b critical(message).
def fatal(self, message):
"""
Log a message with CRITICAL level. This method only exists for
"""
self.critical(message)
-
+## This utility class allows to log messages to a stream with no \b flush
+# method. This is useful to send log messages to \b PyOut objects.
+# \ingroup logger
class _UnFlushableLogStream:
"""
This utility class allows to log messages to a stream with no `flush`
def flush(self):
pass
-
+## This class extends Logger class and adds exception information
+# when DEBUG messages are recorded. It exists mainly for backward
+# compatibility, as the same thing can be done by calling
+# <em> Logger.debug(message, exc_info = True) </em>.
+# \ingroup logger
class ExtLogger(Logger):
"""
This class extends :class:`Logger` class and adds exception information
color = None, sourceFileName=None):
Logger.__init__(self, keyword, level, color, sourceFileName)
+ ## Log a DEBUG message with exception information (equivalent to
+ # <em> Logger.debug(message, exc_info = True) </em>).
def debug( self, message ):
"""
Log a DEBUG message with exception information (equivalent to
"""
Logger.debug(self, message, exc_info = True)
-
+## Test function for logger module
+# \ingroup logger
def TEST_Logger():
"""Test function for logger module"""
log = Logger("TST")
