docutils.utils.Reporter Class Reference

Inheritance diagram for docutils.utils.Reporter:

Collaboration diagram for docutils.utils.Reporter:

Public Member Functions
	__init__ (self, source, report_level, halt_level, stream=None, debug=False, encoding=None, error_handler='backslashreplace')
	set_conditions (self, category, report_level, halt_level, stream=None, debug=False)
	attach_observer (self, observer)
	detach_observer (self, observer)
	notify_observers (self, message)
	system_message (self, level, message, *children, **kwargs)
	debug (self, *args, **kwargs)
	info (self, *args, **kwargs)
	warning (self, *args, **kwargs)
	error (self, *args, **kwargs)
	severe (self, *args, **kwargs)

Public Attributes
	source
	error_handler
	debug_flag
	report_level
	halt_level
	stream
	encoding
	observers
	max_level
	DEBUG_LEVEL
	INFO_LEVEL
	WARNING_LEVEL
	ERROR_LEVEL

Static Public Attributes
str	levels = 'DEBUG INFO WARNING ERROR SEVERE'.split()
	SEVERE_LEVEL

Detailed Description

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.

Constructor & Destructor Documentation

__init__()

docutils.utils.Reporter.__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.
    - `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.

Reimplemented in sphinx.util.docutils.NullReporter, and sphinx.util.docutils.LoggingReporter.

Member Function Documentation

attach_observer()

docutils.utils.Reporter.attach_observer	(		self,
			observer
	)

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

debug()

docutils.utils.Reporter.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()

docutils.utils.Reporter.error	(		self,
		*	args,
		**	kwargs
	)

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

info()

docutils.utils.Reporter.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()

docutils.utils.Reporter.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()

docutils.utils.Reporter.system_message	(		self,
			level,
			message,
		*	children,
		**	kwargs
	)

Return a system_message object.

Raise an exception or generate a warning if appropriate.

warning()

docutils.utils.Reporter.warning	(		self,
		*	args,
		**	kwargs
	)

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

---

The documentation for this class was generated from the following file:

• docs/help/help-venv/lib/python3.12/site-packages/docutils/utils/__init__.py