docutils.utils.Reporter

class documentation

class Reporter: (source)

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__`	: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...
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'): (source)

: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. - `debug`: Show debug (level=0) system messages? - `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). - `encoding`: The output encoding. - `error_handler`: The error handler for stderr output encoding.

def attach_observer(self, observer): (source)

The `observer` parameter is a function or bound method which takes one argument, a `nodes.system_message` instance.

def debug(self, *args, **kwargs): (source)

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): (source)

Undocumented

def error(self, *args, **kwargs): (source)

Level-3, "ERROR": an error that should be addressed. If ignored, the output will contain errors.

def info(self, *args, **kwargs): (source)

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): (source)

Undocumented

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

Undocumented

def severe(self, *args, **kwargs): (source)

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): (source)

Return a system_message object. Raise an exception or generate a warning if appropriate.

def warning(self, *args, **kwargs): (source)

Level-2, "WARNING": an issue that should be addressed. If ignored, there may be unpredictable problems with the output.

DEBUG_LEVEL = (source)

Undocumented

ERROR_LEVEL = (source)

Undocumented

INFO_LEVEL = (source)

Undocumented

SEVERE_LEVEL = (source)

Undocumented

WARNING_LEVEL = (source)

Undocumented

levels = (source)

List of names for system message levels, indexed by level.

debug_flag = (source)

Show debug (level=0) system messages?

encoding = (source)

The output character encoding.

error_handler = (source)

The character encoding error handler.

halt_level = (source)

The level at or above which `SystemMessage` exceptions will be raised, halting execution.

max_level = (source)

The highest level system message generated so far.

observers: list = (source)

List of bound methods or functions to call with each system_message created.

report_level = (source)

The level at or above which warning output will be sent to `self.stream`.

source = (source)

The path to or description of the source data.

stream = (source)

Where warning output is sent.