class documentation

class Reporter(object):

View In Hierarchy

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 as instance attributes.

When a system message is generated, its level is compared to the stored thresholds, and a warning or error is generated as appropriate. Debug messages are produced if the stored debug switch is on, independently of other thresholds. Message output is sent to the stored warning stream if not set to ''.

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 __init__ No summary
Method attach​_observer The observer parameter is a function or bound method which takes one argument, a nodes.system_message instance.
Method debug 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.
Method detach​_observer Undocumented
Method error Level-3, "ERROR": an error that should be addressed. If ignored, the output will contain errors.
Method info 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.
Method notify​_observers Undocumented
Method set​_conditions Undocumented
Method severe 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.
Method system​_message Return a system_message object.
Method warning Level-2, "WARNING": an issue that should be addressed. If ignored, there may be unpredictable problems with the output.
Constant DEBUG​_LEVEL Undocumented
Constant ERROR​_LEVEL Undocumented
Constant INFO​_LEVEL Undocumented
Constant SEVERE​_LEVEL Undocumented
Constant WARNING​_LEVEL Undocumented
Class Variable levels List of names for system message levels, indexed by level.
Instance Variable debug​_flag Show debug (level=0) system messages?
Instance Variable encoding The output character encoding.
Instance Variable error​_handler The character encoding error handler.
Instance Variable halt​_level The level at or above which SystemMessage exceptions will be raised, halting execution.
Instance Variable max​_level The highest level system message generated so far.
Instance Variable observers List of bound methods or functions to call with each system_message created.
Instance Variable report​_level The level at or above which warning output will be sent to self.stream.
Instance Variable source The path to or description of the source data.
Instance Variable stream Where warning output is sent.
def __init__(self, source, report_level, halt_level, stream=None, debug=False, encoding=None, error_handler='backslashreplace'):
Parameters
sourceThe path to or description of the source data.
report​_levelThe level at or above which warning output will be sent to stream.
halt​_levelThe level at or above which SystemMessage exceptions will be raised, halting execution.
streamWhere warning output is sent. Can be file-like (has a .write method), a string (file name, opened for writing), '' (empty string) or False (for discarding all stream messages) or None (implies sys.stderr; default).
debugShow debug (level=0) system messages?
encodingThe output encoding.
error​_handlerThe error handler for stderr output encoding.
def attach_observer(self, observer):
The observer parameter is a function or bound method which takes one argument, a nodes.system_message instance.
def 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.
def detach_observer(self, observer):

Undocumented

def error(self, *args, **kwargs):
Level-3, "ERROR": an error that should be addressed. If ignored, the output will contain errors.
def 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.
def notify_observers(self, message):

Undocumented

def set_conditions(self, category, report_level, halt_level, stream=None, debug=False):

Undocumented

def 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.
def system_message(self, level, message, *children, **kwargs):

Return a system_message object.

Raise an exception or generate a warning if appropriate.

def warning(self, *args, **kwargs):
Level-2, "WARNING": an issue that should be addressed. If ignored, there may be unpredictable problems with the output.
DEBUG_LEVEL =

Undocumented

ERROR_LEVEL =

Undocumented

INFO_LEVEL =

Undocumented

SEVERE_LEVEL =

Undocumented

WARNING_LEVEL =

Undocumented

levels =
List of names for system message levels, indexed by level.
debug_flag =
Show debug (level=0) system messages?
encoding =
The output character encoding.
error_handler =
The character encoding error handler.
halt_level =
The level at or above which SystemMessage exceptions will be raised, halting execution.
max_level =
The highest level system message generated so far.
observers: list =
List of bound methods or functions to call with each system_message created.
report_level =
The level at or above which warning output will be sent to self.stream.
source =
The path to or description of the source data.
stream =
Where warning output is sent.