From f7a49532331d819d6f7b129abd280c2a13eeea22 Mon Sep 17 00:00:00 2001
From: Xavier Robin <xavier.robin@unibas.ch>
Date: Thu, 3 Oct 2019 18:15:34 +0200
Subject: [PATCH] doc: Document the use of LogLevel enums
---
modules/base/doc/logging.rst | 102 ++++++++++++++++++++++++++++-------
1 file changed, 84 insertions(+), 18 deletions(-)
diff --git a/modules/base/doc/logging.rst b/modules/base/doc/logging.rst
index 6b2b4ca3c..0baea68f3 100644
--- a/modules/base/doc/logging.rst
+++ b/modules/base/doc/logging.rst
@@ -41,32 +41,44 @@ OpenStructure has a logging system going beyond what print statements can offer.
Verbosity Level
--------------------------------------------------------------------------------
+Several verbosity levels are available. Verbosity levels are represented
+by an enumeration of integer values. They are wrapped to objects with
+memorable names by the :class:`LogLevel` class. The available levels are
+are summarized in the table below.
+
+=========== ================ ===================
+Level name Verbosity value LogLevel object
+=========== ================ ===================
+Error 0 LogLevel.Error
+Warning 1 LogLevel.Warning
+Script 2 LogLevel.Script
+Info 3 LogLevel.Info
+Verbose 4 LogLevel.Verbose
+Debug 5 LogLevel.Debug
+Trace 6 LogLevel.Trace
+=========== ================ ===================
+
You can change the verbosity level with the following two methods:
.. function:: PushVerbosityLevel(verbosity)
- Change the verbosity level to the given integer value. All log events which
+ Change the verbosity level to the given integer value or :class:`LogLevel`
+ enumeration object. All log events which
have a severity above *verbosity* will not be shown. By default, the log level
is 2, meaning that errors, warnings and script logging events are visible. By
- setting it to -1, you can disable all logging. The table below shows the
- mapping between the verbosity level names and their numeric values:
-
- =========== ================
- Level name Verbosity value
- =========== ================
- (disabled) -1
- Error 0
- Warning 1
- Script 2
- Info 3
- Verbose 4
- Debug 5
- Trace 6
- =========== ================
+ setting it to -1, you can disable all logging.
:param verbosity: Desired verbosity level
:type verbosity: :class:`int`
+ .. code-block:: python
+
+ # Display warnings and errors:
+ ost.PushVerbosityLevel(ost.LogLevel.Warning)
+
+ # Disable all logging:
+ ost.PushVerbosityLevel(-1)
+
.. function:: PopVerbosityLevel()
Change the log level back to the previous verbosity level. It is an error to
@@ -78,11 +90,65 @@ You can change the verbosity level with the following two methods:
:return: The current verbosity level
:rtype: :class:`int`
+ The :class:`LogLevel` class allows to map these integer values
+ to more a human-readable objects
+
+ .. code-block:: python
+
+ print ost.GetVerbosityLevel()
+ # Outputs: 2
+
+ print ost.LogLevel.values[ost.GetVerbosityLevel()]
+ # Outputs: Script
+
.. class:: LogLevel
Enumerates the logging levels (see :ref:`picking-logging-level`). Values:
- Error, Warning, Script, Info, Verbose, Debug, Trace
+ .. attribute:: Error, Warning, Script, Info, Verbose, Debug, Trace
+
+ The enumerated LogLevel object, which wraps the corresponding integer
+ value. Note that these attributes are LogLevel objects themselves.
+
+ :type: :class:`LogLevel`
+
+ .. code-block:: python
+
+ ost.LogLevel.Info
+ # Outputs: ost._ost_base.LogLevel.Info
+
+ print ost.LogLevel.Info
+ # Outputs: Info
+
+ int(ost.LogLevel.Info)
+ # Outputs: 3
+
+ .. attribute:: name
+
+ The name of the level
+
+ :type: :class:`str`
+
+ .. code-block:: python
+
+ ost.LogLevel.Info.name
+ # Outputs: 'Info'
+
+
+ .. attribute:: names
+
+ A dictionary mapping the log level names to the corresponding
+ LogLevel enumerated object.
+
+ :type: :class:`dict`
+
+ .. attribute:: values
+
+ A dictionary mapping the log level integer to the corresponding
+ LogLevel enumerated object.
+
+ :type: :class:`dict`
+
Log sinks
--------------------------------------------------------------------------------
@@ -231,4 +297,4 @@ terminal (or the python shell in DNG). The logger also prints the current time.
py_logger=PyLogger()
ost.PushLogSink(py_logger)
- ost.LogInfo("amazing logging system")
\ No newline at end of file
+ ost.LogInfo("amazing logging system")
--
GitLab