Modified comments style and added IOError exception handle sentences.

git-svn-id: svn://bind10.isc.org/svn/bind10/branches/trac176@1962 e5f2f494-b856-4b98-b285-d166d9295462

src/lib/python/isc/log/log.py

@@ -13,14 +13,20 @@
 # NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 # WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
+"""
+This module is to convert python logging module over
+to log4python.
+Copyright (C) 2010  Internet Systems Consortium.
+To use, simply 'import isc.log.log' and log away!
+"""
 import os
 import syslog
 import logging
 import logging.handlers
 
-#########################################################################
-# LEVELS: logging levels mapping
-#########################################################################
+"""
+LEVELS: logging levels mapping
+"""
 LEVELS = {'debug' : logging.DEBUG,
        	  'info' : logging.INFO,
           'warning' : logging.WARNING,
@@ -29,72 +35,55 @@ LEVELS = {'debug' : logging.DEBUG,
 
 formatter = logging.Formatter("%(name)s: %(levelname)s: %(message)s")
 time_formatter = logging.Formatter("%(asctime)s: %(name)s: %(levelname)s: %(message)s")
-#########################################################################
-# NullHandler: define a do-nothing handler 
-#########################################################################
-class NullHandler(logging.Handler):
-    def emit(self, record):
-        pass
-
-#########################################################################
-# RotatingFileHandler: replace RotatingFileHandler with a custom handler 
-#########################################################################
-class RotatingFileHandler(logging.handlers.RotatingFileHandler):
 
-    def __init__(self, filename, mode='a', maxBytes=0, backupCount=0, encoding=None):
-        logging.handlers.RotatingFileHandler.__init__(self, filename, mode, 
-                                                      maxBytes, backupCount,
-                                                      encoding)
-    #####################################################################
-    # shouldRollover 
-    #   Rewrite RotatingFileHandler.shouldRollover. 
-    #   If the log file is deleted, a new file will be created. 
-    #####################################################################
+class RotatingFileHandler(logging.handlers.RotatingFileHandler):
+    """
+    RotatingFileHandler: replace RotatingFileHandler with a custom handler 
+    """
     def shouldRollover(self, record):
-        if self.stream is None:                 # delay was set...
-            self.stream = self._open()
-
-        dfn = self.baseFilename                 # Is log file exist?
-        if not os.path.exists(dfn):
+        """
+        Rewrite RotatingFileHandler.shouldRollover. 
+       
+        If the log file is deleted at run-time, a new file will be created. 
+        """
+        dfn = self.baseFilename                 
+        if (self.stream) and (not os.path.exists(dfn)): #Is log file exist?
             self.stream.close()
             self.stream = self._open()
+        super(RotatingFileHandler, self).shouldRollover(record)
 
-        if self.maxBytes > 0:                   # are we rolling over?
-            msg = "%s\n" % self.format(record)
-            self.stream.seek(0, 2)  #due to non-posix-compliant Windows feature
-            if self.stream.tell() + len(msg) >= self.maxBytes:
-                return 1
-        return 0
-
-    ######################################################################
-    # handleError 
-    #   Rewrite RotatingFileHandler.handleError.
-    #   If raiseExceptions is false, exceptions get silently ignored.
-    ######################################################################
-    def handleError(self, record):
-        pass
-
-    ######################################################################
-    # update_config
-    #   update RotatingFileHandler configuration
-    #   input:
-    #         new log file name
-    #         max backup count
-    #         predetermined log file size
-    ######################################################################
     def update_config(self, file_name, backup_count, max_bytes):
+        """
+        Update RotatingFileHandler configuration.
+
+        input:
+            log file name
+            max backup count
+            predetermined log file size
+        """
+        try:
+            self._open(file_name)
+        except IOError:
+            print("The file path is not exist!")
+            return 
         self.baseFilename = file_name
         self.maxBytes = max_bytes
         self.backupCount = backup_count
 
-
-#########################################################################
-# SLHandler: Replace SysLogHandler with a custom handler due to python3.1
-#            SysLogHandler issue : http://bugs.python.org/issue8148
-#########################################################################
 class SLHandler(logging.Handler):    
+    """
+    Replace SysLogHandler with a custom handler 
+
+    A handler class which sends formatted logging records to a syslog
+    server. 
+    """
     def __init__(self, ident, logopt=0, facility=syslog.LOG_USER):        
-        logging.Handler.__init__(self)        
+        """
+        Initialize a handler.
+    
+        If facility is not specified, LOG_USER is used.
+        """
+        super(SLHandler, self).__init__(self)
         self.ident = ident        
         self.logopt = logopt        
         self.facility = facility        
@@ -107,12 +96,18 @@ class SLHandler(logging.Handler):
                 }   
         
     def encodeLevel(self, level):        
+        """
+        Encoding the priority.
+        """
         return self.mappings.get(level, syslog.LOG_INFO)    
    
-    def handleError(self, record):
-        pass
-
-    def emit(self, record):        
+    def emit(self, record):   
+        """
+        Emit a record.
+     
+        The record is formatted, and then sent to the syslog server. If
+        exception information is present, it is NOT sent to the server.
+        """
         syslog.openlog(self.ident, self.logopt, self.facility)        
         msg = self.format(record)        
         prio = self.encodeLevel(record.levelno)        
@@ -120,73 +115,121 @@ class SLHandler(logging.Handler):
         syslog.closelog()
 
 
-#########################################################################
-# ModuleLogger: rewrite logging.Logger 
-#########################################################################
 class ModuleLogger(logging.getLoggerClass()):
+    """
+    Override logging.logger behaviour
+    """
     def __init__(self, log_name, log_file, 
                  severity = 'debug', backup_count = 0, max_bytes = 0,
                  log_to_console = True):
+        """
+        Initializes the logger with some specific parameters
+        """
         logging.Logger.__init__(self, log_name)
 
         # Set up a specific logger with our desired output level
         logLevel = LEVELS.get(severity, logging.NOTSET)
         self.setLevel(logLevel)
         
-        null_handler = NullHandler()
-        self.addHandler(null_handler)
-
+        self.null_handler = None 
         self.rotating_handler = None
         self.stream_handler = None
         self.syslog_handler = None
+
+        self.add_null_handler()
         self.add_rotate_handler(log_file, max_bytes, backup_count)
         if log_to_console:
             self.add_stream_handler()
         else:
             self.add_syslog_handler()
 
+    def add_null_handler(self):
+        """
+        Add a null handler.
+        """
+        self.null_handler = logging.NullHandler()
+        self.addHandler(self.null_handler)
+
     def add_rotate_handler(self, log_file, max_bytes, backup_count):
-        # If logFile was specified
+        """
+        Add a rotate file handler.
+   
+        input:
+            log_file : the location of log file.Handler would't be created is log_file is empty
+            max_bytes : limit log growth
+            backup_count : max backup count
+        """
         if(log_file != 0  and log_file != ''):
-            # Add the log message handler to the logger
             try:
                 self.rotating_handler = RotatingFileHandler(filename = log_file, maxBytes = max_bytes, 
                                                             backupCount = backup_count)
-                # add formatter to ch
-                self.rotating_handler.setFormatter(time_formatter)
-                self.addHandler(self.rotating_handler)
             except IOError:
-                pass
+                self.rotating_handler = None
+                return
+            self.rotating_handler.setFormatter(time_formatter)
+            self.addHandler(self.rotating_handler)
 
     def add_stream_handler(self):
+        """
+        Add a stream handler.
+    
+        sys.stderr will be used for logging output.
+        """
         self.stream_handler = logging.StreamHandler()
         self.stream_handler.setFormatter(time_formatter)
         self.addHandler(self.stream_handler)
 
     def add_syslog_handler(self):
-        self.syslog_handler = SLHandler('BIND10')
+        """
+        Add a syslog handler.
+   
+        If facility is not specified, LOG_USER is used.
+        The default severity level is INFO.
+        """
+        self.syslog_handler = SLHandler('BIND10', facility=syslog.LOG_USER)
         self.syslog_handler.setFormatter(formatter)
         #set syslog handler level info
         self.syslog_handler.setLevel(logging.INFO)
         self.addHandler(self.syslog_handler)
 
     def update_rotate_handler(self, log_file, max_bytes, backup_count):
+        """
+        If rotate handler has been added to the logger, update its configuration,
+        else add it to logger.
+    
+        If log file is empty, the handler will be removed.
+        """
         if (self.rotating_handler in self.handlers):
-            # If logFile was specified
             if(log_file != 0 and log_file != ''):
                 self.rotating_handler.update_config(log_file, max_bytes, backup_count)
             else:
                 self.rotating_handler.flush()
                 self.rotating_handler.close()
                 self.removeHandler(self.rotating_handler)
+        else:
+            self.add_rotate_handler(log_file, max_bytes, backup_count)
+
 
     def update_config(self, file_name, level, max_bytes, backup_count):
+        """
+        Update logger's configuration.
+
+        We can update logger's log level and its rotate file handler's configuration.
+        """
         logLevel = LEVELS.get(level, logging.NOTSET)
         if(logLevel != self.getEffectiveLevel()):
             self.setLevel(logLevel)
         self.update_rotate_handler(file_name, backup_count, max_bytes)
 
     def log_message(self, level, msg, *args, **kwargs):
+        """
+        Log 'msg % args' with the integer severity 'level'.
+     
+        To pass exception information, use the keyword argument exc_info with
+        a true value, e.g.
+  
+        logger.log_message('info', "We have a %s", "mysterious problem", exc_info=1)
+        """
         logLevel = LEVELS.get(level, logging.NOTSET)
         self.log(logLevel, msg, *args, **kwargs)
 

src/lib/python/isc/log/tests/log_test.py

@@ -29,10 +29,13 @@ class TestLogging(unittest.TestCase):
         self.syslog_logger = ModuleLogger('SysLogger', '', 'info', 5, 1024, False)
 
     def test_logging_init(self):
+        self.assertNotEqual(self.file_stream_logger.null_handler, None)
         self.assertNotEqual(self.file_stream_logger.rotating_handler, None)
         self.assertNotEqual(self.file_stream_logger.stream_handler, None)
         self.assertEqual(self.file_stream_logger.syslog_handler, None)
 
+        ret = self.file_stream_logger.null_handler in self.file_stream_logger.handlers
+        self.assertTrue(ret)
         ret = self.file_stream_logger.rotating_handler in self.file_stream_logger.handlers
         self.assertTrue(ret)
         ret = self.file_stream_logger.stream_handler in self.file_stream_logger.handlers
@@ -42,9 +45,12 @@ class TestLogging(unittest.TestCase):
         logLevel = LEVELS.get('debug', logging.NOTSET)
         self.assertEqual(self.file_stream_logger.getEffectiveLevel(), logLevel)
 
+        self.assertNotEqual(self.syslog_logger.null_handler, None)
         self.assertEqual(self.syslog_logger.rotating_handler, None)
         self.assertEqual(self.syslog_logger.stream_handler, None)
         self.assertNotEqual(self.syslog_logger.syslog_handler, None)
+        ret = self.syslog_logger.null_handler in self.syslog_logger.handlers
+        self.assertTrue(ret)
         ret = self.syslog_logger.rotating_handler in self.syslog_logger.handlers
         self.assertFalse(ret)
         ret = self.syslog_logger.stream_handler in self.syslog_logger.handlers
@@ -55,6 +61,15 @@ class TestLogging(unittest.TestCase):
         logLevel = LEVELS.get('info', logging.NOTSET)
         self.assertEqual(self.syslog_logger.getEffectiveLevel(), logLevel)
 
+    def test_add_null_handler(self):
+        if(self.syslog_logger.null_handler in self.syslog_logger.handlers):
+            self.syslog_logger.removeHandler(self.syslog_logger.null_handler)
+
+        self.syslog_logger.add_null_handler()
+        ret = self.syslog_logger.null_handler in self.syslog_logger.handlers
+        self.assertTrue(ret)
+    
+
     def test_add_rotate_handler(self):
         if(self.syslog_logger.rotating_handler in self.syslog_logger.handlers):
             self.syslog_logger.removeHandler(self.syslog_logger.rotating_handler)