docutils.utils.Reporter

class documentation

class Reporter(object):

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
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), '' (empty string) or `False` (for discarding all stream messages) or `None` (implies `sys.stderr`; default).
debug	Show debug (level=0) system messages?
encoding	The output encoding.
error_handler	The 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.