1
2
3
4
5
6
7
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
37
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
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
68 """
69 Perform any tasks needed to close this logger.
70 """
71
72
73
74
75
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
88 """
89 End a warning block. See L{start_block} for details.
90 """
91
92
93
94
95
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
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
123 self.threshold = threshold
124 - def log(self, level, message):
125 if level >= self.threshold: print message
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
146
147
148
149
150
151
152
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
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
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
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
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
185 start_block.__doc__ = Logger.start_block.__doc__
186
189 end_block.__doc__ = Logger.end_block.__doc__
190
193 start_progress.__doc__ = Logger.start_progress.__doc__
194
197 end_progress.__doc__ = Logger.end_progress.__doc__
198
201 progress.__doc__ = Logger.progress.__doc__
202
205