Package epydoc :: Module log
[hide private]
[frames] | no frames]

Source Code for Module epydoc.log

  1  # epydoc -- Logging 
  2  # 
  3  # Copyright (C) 2005 Edward Loper 
  4  # Author: Edward Loper <[email protected]> 
  5  # URL: <http://epydoc.sf.net> 
  6  # 
  7  # $Id: log.py 1488 2007-02-14 00:34:27Z edloper $ 
  8   
  9  """ 
 10  Functions used to report messages and progress updates to the user. 
 11  These functions are delegated to zero or more registered L{Logger} 
 12  objects, which are responsible for actually presenting the information 
 13  to the user.  Different interfaces are free to create and register 
 14  their own C{Logger}s, allowing them to present this information in the 
 15  manner that is best suited to each interface. 
 16   
 17  @note: I considered using the standard C{logging} package to provide 
 18  this functionality.  However, I found that it would be too difficult 
 19  to get that package to provide the behavior I want (esp. with respect 
 20  to progress displays; but also with respect to message blocks). 
 21   
 22  @group Message Severity Levels: DEBUG, INFO, WARNING, ERROR, FATAL 
 23  """ 
 24  __docformat__ = 'epytext en' 
 25   
 26  import sys, os 
 27   
 28  DEBUG = 10 
 29  INFO = 20 
 30  DOCSTRING_WARNING = 25 
 31  WARNING = 30 
 32  ERROR = 40 
 33  FATAL = 40 
 34   
 35  ###################################################################### 
 36  # Logger Base Class 
 37  ###################################################################### 
38 -class Logger:
39 """ 40 An abstract base class that defines the interface for X{loggers}, 41 which are used by epydoc to report information back to the user. 42 Loggers are responsible for tracking two types of information: 43 44 - Messages, such as warnings and errors. 45 - Progress on the current task. 46 47 This abstract class allows the command-line interface and the 48 graphical interface to each present this information to the user 49 in the way that's most natural for each interface. To set up a 50 logger, create a subclass of C{Logger} that overrides all methods, 51 and register it using L{register_logger}. 52 """ 53 #//////////////////////////////////////////////////////////// 54 # Messages 55 #//////////////////////////////////////////////////////////// 56
57 - def log(self, level, message):
58 """ 59 Display a message. 60 61 @param message: The message string to display. C{message} may 62 contain newlines, but does not need to end in a newline. 63 @param level: An integer value indicating the severity of the 64 message. 65 """
66
67 - def close(self):
68 """ 69 Perform any tasks needed to close this logger. 70 """
71 72 #//////////////////////////////////////////////////////////// 73 # Message blocks 74 #//////////////////////////////////////////////////////////// 75
76 - def start_block(self, header):
77 """ 78 Start a new message block. Any calls to L{info()}, 79 L{warning()}, or L{error()} that occur between a call to 80 C{start_block} and a corresponding call to C{end_block} will 81 be grouped together, and displayed with a common header. 82 C{start_block} can be called multiple times (to form nested 83 blocks), but every call to C{start_block} I{must} be balanced 84 by a call to C{end_block}. 85 """
86
87 - def end_block(self):
88 """ 89 End a warning block. See L{start_block} for details. 90 """
91 92 #//////////////////////////////////////////////////////////// 93 # Progress bar 94 #//////////////////////////////////////////////////////////// 95
96 - def start_progress(self, header=None):
97 """ 98 Begin displaying progress for a new task. C{header} is a 99 description of the task for which progress is being reported. 100 Each call to C{start_progress} must be followed by a call to 101 C{end_progress} (with no intervening calls to 102 C{start_progress}). 103 """
104
105 - def end_progress(self):
106 """ 107 Finish off the display of progress for the current task. See 108 L{start_progress} for more information. 109 """
110
111 - def progress(self, percent, message=''):
112 """ 113 Update the progress display. 114 115 @param percent: A float from 0.0 to 1.0, indicating how much 116 progress has been made. 117 @param message: A message indicating the most recent action 118 that contributed towards that progress. 119 """
120
121 -class SimpleLogger(Logger):
122 - def __init__(self, threshold=WARNING):
123 self.threshold = threshold
124 - def log(self, level, message):
125 if level >= self.threshold: print message
126 127 ###################################################################### 128 # Logger Registry 129 ###################################################################### 130 131 _loggers = [] 132 """ 133 The list of registered logging functions. 134 """ 135
136 -def register_logger(logger):
137 """ 138 Register a logger. Each call to one of the logging functions 139 defined by this module will be delegated to each registered 140 logger. 141 """ 142 _loggers.append(logger)
143
144 -def remove_logger(logger):
145 _loggers.remove(logger)
146 147 ###################################################################### 148 # Logging Functions 149 ###################################################################### 150 # The following methods all just delegate to the corresponding 151 # methods in the Logger class (above) for each registered logger. 152
153 -def fatal(*messages):
154 """Display the given fatal message.""" 155 message = ' '.join(['%s' % (m,) for m in messages]) 156 for logger in _loggers: logger.log(FATAL, message)
157
158 -def error(*messages):
159 """Display the given error message.""" 160 message = ' '.join(['%s' % (m,) for m in messages]) 161 for logger in _loggers: logger.log(ERROR, message)
162
163 -def warning(*messages):
164 """Display the given warning message.""" 165 message = ' '.join(['%s' % (m,) for m in messages]) 166 for logger in _loggers: logger.log(WARNING, message)
167
168 -def docstring_warning(*messages):
169 """Display the given docstring warning message.""" 170 message = ' '.join(['%s' % (m,) for m in messages]) 171 for logger in _loggers: logger.log(DOCSTRING_WARNING, message)
172
173 -def info(*messages):
174 """Display the given informational message.""" 175 message = ' '.join(['%s' % (m,) for m in messages]) 176 for logger in _loggers: logger.log(INFO, message)
177
178 -def debug(*messages):
179 """Display the given debugging message.""" 180 message = ' '.join(['%s' % (m,) for m in messages]) 181 for logger in _loggers: logger.log(DEBUG, message)
182
183 -def start_block(header):
184 for logger in _loggers: logger.start_block(header)
185 start_block.__doc__ = Logger.start_block.__doc__ 186
187 -def end_block():
188 for logger in _loggers: logger.end_block()
189 end_block.__doc__ = Logger.end_block.__doc__ 190
191 -def start_progress(header=None):
192 for logger in _loggers: logger.start_progress(header)
193 start_progress.__doc__ = Logger.start_progress.__doc__ 194
195 -def end_progress():
196 for logger in _loggers: logger.end_progress()
197 end_progress.__doc__ = Logger.end_progress.__doc__ 198
199 -def progress(percent, message=''):
200 for logger in _loggers: logger.progress(percent, '%s' % message)
201 progress.__doc__ = Logger.progress.__doc__ 202
203 -def close():
204 for logger in _loggers: logger.close()
205