1  # epydoc -- Logging 
  2  # 
  3  # Copyright (C) 2005 Edward Loper 
  4  # Author: Edward Loper <edloper@loper.org> 
  5  # URL: <http://epydoc.sf.net> 
  6  # 
  7  # $Id: log.py 1075 2006-03-21 07:43:58Z 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      #//////////////////////////////////////////////////////////// 
 68      # Message blocks 
 69      #//////////////////////////////////////////////////////////// 
 70       
 71 -    def start_block(self, header): 
 72          """ 
 73          Start a new message block.  Any calls to L{info}, L{warn}, or 
 74          L{error} that occur between a call to C{start_block} and a 
 75          corresponding call to C{end_block} will be grouped together, 
 76          and displayed with a common header.  C{start_block} can be 
 77          called multiple times (to form nested blocks), but every call 
 78          to C{start_block} I{must} be balanced by a call to 
 79          C{end_block}. 
 80          """ 
 81           
 82 -    def end_block(self): 
 83          """ 
 84          End a warning block.  See L{start_block} for details. 
 85          """ 
 86   
 87      #//////////////////////////////////////////////////////////// 
 88      # Progress bar 
 89      #//////////////////////////////////////////////////////////// 
 90       
 91 -    def start_progress(self, header=None): 
 92          """ 
 93          Begin displaying progress for a new task.  C{header} is a 
 94          description of the task for which progress is being reported. 
 95          Each call to C{start_progress} must be followed by a call to 
 96          C{end_progress} (with no intervening calls to 
 97          C{start_progress}). 
 98          """ 
 99   
100 -    def end_progress(self): 
101          """ 
102          Finish off the display of progress for the current task.  See 
103          L{start_progress} for more information. 
104          """ 
105   
106 -    def progress(self, percent, message=''): 
107          """ 
108          Update the progress display. 
109           
110          @param progress: A float from 0.0 to 1.0, indicating how much 
111              progress has been made. 
112          @param message: A message indicating the most recent action 
113              that contributed towards that progress. 
114          """ 
115   
116 -class SimpleLogger(Logger): 
117 -    def __init__(self, threshold=WARNING): 
118          self.threshold = threshold 
119 -    def log(self, level, message): 
120          if level >= self.threshold: print message 
121           
122  ###################################################################### 
123  # Logger Registry 
124  ###################################################################### 
125   
126  _loggers = [] 
127  """ 
128  The list of registered logging functions. 
129  """ 
130   
131 -def register_logger(logger): 
132      """ 
133      Register a logger.  Each call to one of the logging functions 
134      defined by this module will be delegated to each registered 
135      logger. 
136      """ 
137      _loggers.append(logger) 
138   
139 -def remove_logger(logger): 
140      _loggers.remove(logger) 
141   
142  ###################################################################### 
143  # Logging Functions 
144  ###################################################################### 
145  # The following methods all just delegate to the corresponding  
146  # methods in the Logger class (above) for each registered logger. 
147   
148 -def fatal(*messages): 
149      """Display the given fatal message.""" 
150      message = ' '.join(['%s' % (m,) for m in messages]) 
151      for logger in _loggers: logger.log(FATAL, message) 
152       
153 -def error(*messages): 
154      """Display the given error message.""" 
155      message = ' '.join(['%s' % (m,) for m in messages]) 
156      for logger in _loggers: logger.log(ERROR, message) 
157       
158 -def warning(*messages): 
159      """Display the given warning message.""" 
160      message = ' '.join(['%s' % (m,) for m in messages]) 
161      for logger in _loggers: logger.log(WARNING, message) 
162       
163 -def docstring_warning(*messages): 
164      """Display the given docstring warning message.""" 
165      message = ' '.join(['%s' % (m,) for m in messages]) 
166      for logger in _loggers: logger.log(DOCSTRING_WARNING, message) 
167       
168 -def info(*messages): 
169      """Display the given informational message.""" 
170      message = ' '.join(['%s' % (m,) for m in messages]) 
171      for logger in _loggers: logger.log(INFO, message) 
172       
173 -def debug(*messages): 
174      """Display the given debugging message.""" 
175      message = ' '.join(['%s' % (m,) for m in messages]) 
176      for logger in _loggers: logger.log(DEBUG, message) 
177       
178 -def start_block(header): 
179      for logger in _loggers: logger.start_block(header) 
180  start_block.__doc__ = Logger.start_block.__doc__ 
181       
182 -def end_block(): 
183      for logger in _loggers: logger.end_block() 
184  end_block.__doc__ = Logger.end_block.__doc__ 
185       
186 -def start_progress(header=None): 
187      for logger in _loggers: logger.start_progress(header) 
188  start_progress.__doc__ = Logger.start_progress.__doc__ 
189       
190 -def end_progress(): 
191      for logger in _loggers: logger.end_progress() 
192  end_progress.__doc__ = Logger.end_progress.__doc__ 
193       
194 -def progress(percent, message=''): 
195      for logger in _loggers: logger.progress(percent, '%s' % message) 
196  progress.__doc__ = Logger.progress.__doc__ 
197