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. This should
70 be safe to call multiple times.
71 """
72
73
74
75
76
78 """
79 Start a new message block. Any calls to L{info()},
80 L{warning()}, or L{error()} that occur between a call to
81 C{start_block} and a corresponding call to C{end_block} will
82 be grouped together, and displayed with a common header.
83 C{start_block} can be called multiple times (to form nested
84 blocks), but every call to C{start_block} I{must} be balanced
85 by a call to C{end_block}.
86 """
87
89 """
90 End a warning block. See L{start_block} for details.
91 """
92
93
94
95
96
98 """
99 Begin displaying progress for a new task. C{header} is a
100 description of the task for which progress is being reported.
101 Each call to C{start_progress} must be followed by a call to
102 C{end_progress} (with no intervening calls to
103 C{start_progress}).
104 """
105
107 """
108 Finish off the display of progress for the current task. See
109 L{start_progress} for more information.
110 """
111
112 - def progress(self, percent, message=''):
113 """
114 Update the progress display.
115
116 @param percent: A float from 0.0 to 1.0, indicating how much
117 progress has been made.
118 @param message: A message indicating the most recent action
119 that contributed towards that progress.
120 """
121
124 self.threshold = threshold
125 - def log(self, level, message):
126 if level >= self.threshold: print message
138 """
139 Register a logger. Each call to one of the logging functions
140 defined by this module will be delegated to each registered
141 logger.
142 """
143 _loggers.append(logger)
144
148
149
150
151
152
153
154
156 """Display the given fatal message."""
157 message = ' '.join(['%s' % (m,) for m in messages])
158 for logger in _loggers: logger.log(FATAL, message)
159
161 """Display the given error message."""
162 message = ' '.join(['%s' % (m,) for m in messages])
163 for logger in _loggers: logger.log(ERROR, message)
164
166 """Display the given warning message."""
167 message = ' '.join(['%s' % (m,) for m in messages])
168 for logger in _loggers: logger.log(WARNING, message)
169
171 """Display the given docstring warning message."""
172 message = ' '.join(['%s' % (m,) for m in messages])
173 for logger in _loggers: logger.log(DOCSTRING_WARNING, message)
174
175 -def info(*messages):
176 """Display the given informational message."""
177 message = ' '.join(['%s' % (m,) for m in messages])
178 for logger in _loggers: logger.log(INFO, message)
179
181 """Display the given debugging message."""
182 message = ' '.join(['%s' % (m,) for m in messages])
183 for logger in _loggers: logger.log(DEBUG, message)
184
187 start_block.__doc__ = Logger.start_block.__doc__
188
191 end_block.__doc__ = Logger.end_block.__doc__
192
195 start_progress.__doc__ = Logger.start_progress.__doc__
196
199 end_progress.__doc__ = Logger.end_progress.__doc__
200
203 progress.__doc__ = Logger.progress.__doc__
204
207