Class Reporter
Info/warning/error reporter and system_message element generator.
Five levels of system messages are defined, along with corresponding
methods: debug(), info(), warning(), error(), and severe().
There is typically one Reporter object per process. A Reporter object is
instantiated with thresholds for reporting (generating warnings) and
halting processing (raising exceptions), a switch to turn debug output on
or off, and an I/O stream for warnings. These are stored in the default
reporting category, '' (zero-length string).
Multiple reporting categories may be set, each with its own reporting
and halting thresholds, debugging switch, and warning stream
(collectively a ConditionSet). Categories are hierarchical dotted-name
strings that look like attribute references: 'spam', 'spam.eggs',
'neeeow.wum.ping'. The 'spam' category is the ancestor of
'spam.bacon.eggs'. Unset categories inherit stored conditions from their
closest ancestor category that has been set.
When a system message is generated, the stored conditions from its
category (or ancestor if unset) are retrieved. The system message level
is compared to the thresholds stored in the category, and a warning or
error is generated as appropriate. Debug messages are produced iff the
stored debug switch is on. Message output is sent to the stored warning
stream.
The default category is '' (empty string). By convention, Writers should
retrieve reporting conditions from the 'writer' category (which, unless
explicitly set, defaults to the conditions of the default category).
The Reporter class also employs a modified form of the "Observer" pattern
[GoF95] to track system messages generated. The attach_observer method
should be called before parsing, with a bound method or function which
accepts system messages. The observer can be removed with
detach_observer, and another added in its place.
| [GoF95] | Gamma, Helm, Johnson, Vlissides. Design Patterns: Elements of
Reusable Object-Oriented Software. Addison-Wesley, Reading, MA, USA,
1995. |
| Method Summary |
| |
__init__(self,
source,
report_level,
halt_level,
stream,
debug,
encoding,
error_handler)
Initialize the ConditionSet forthe Reporter's default category. |
| |
__delitem__(self,
category)
|
| |
__getitem__(self,
category)
|
| |
attach_observer(self,
observer)
The observer parameter is a function or bound method which takes one
argument, a nodes.system_message instance. |
| |
debug(self,
*args,
**kwargs)
Level-0, "DEBUG": an internal reporting issue. |
| |
detach_observer(self,
observer)
|
| |
error(self,
*args,
**kwargs)
Level-3, "ERROR": an error that should be addressed. |
| |
get_conditions(self,
category)
|
| |
info(self,
*args,
**kwargs)
Level-1, "INFO": a minor issue that can be ignored. |
| |
notify_observers(self,
message)
|
| |
set_conditions(self,
category,
report_level,
halt_level,
stream,
debug)
|
| |
severe(self,
*args,
**kwargs)
Level-4, "SEVERE": a severe error that must be addressed. |
| |
system_message(self,
level,
message,
*children,
**kwargs)
Return a system_message object. |
| |
unset_conditions(self,
category)
|
| |
warning(self,
*args,
**kwargs)
Level-2, "WARNING": an issue that should be addressed. |
| Class Variable Summary |
list |
levels = ['DEBUG', 'INFO', 'WARNING', 'ERROR', 'SEVERE']
|
__init__(self,
source,
report_level,
halt_level,
stream=None,
debug=0,
encoding='ascii',
error_handler='replace')
(Constructor)
Initialize the ConditionSet forthe Reporter's default category. -
- Parameters:
source -
The path to or description of the source data.
report_level -
The level at or above which warning output will
be sent to stream.
halt_level -
The level at or above which SystemMessage
exceptions will be raised, halting execution.
stream -
Where warning output is sent. Can be file-like (has a
.write method), a string (file name, opened for writing), or
None (implies sys.stderr; default).
debug -
Show debug (level=0) system messages?
encoding -
The encoding for stderr output.
error_handler -
The error handler for stderr output encoding.
|
attach_observer(self,
observer)
The observer parameter is a function or bound method which takes one
argument, a nodes.system_message instance. -
|
debug(self,
*args,
**kwargs)
Level-0, "DEBUG": an internal reporting issue. Typically, there is no
effect on the processing. Level-0 system messages are handled
separately from the others. -
|
error(self,
*args,
**kwargs)
Level-3, "ERROR": an error that should be addressed. If ignored, the
output will contain errors. -
|
info(self,
*args,
**kwargs)
Level-1, "INFO": a minor issue that can be ignored. Typically there is
no effect on processing, and level-1 system messages are not reported. -
|
severe(self,
*args,
**kwargs)
Level-4, "SEVERE": a severe error that must be addressed. If ignored,
the output will contain severe errors. Typically level-4 system
messages are turned into exceptions which halt processing. -
|
system_message(self,
level,
message,
*children,
**kwargs)
Return a system_message object.
Raise an exception or generate a warning if appropriate.
-
|
warning(self,
*args,
**kwargs)
Level-2, "WARNING": an issue that should be addressed. If ignored,
there may be unpredictable problems with the output. -
|
levels
-
- Type:
-
list
- Value:
['DEBUG', 'INFO', 'WARNING', 'ERROR', 'SEVERE']
|
|