diff --git a/docs/source/user/runtime_view.rst b/docs/source/user/runtime_view.rst index b9308cbe..745c3f46 100644 --- a/docs/source/user/runtime_view.rst +++ b/docs/source/user/runtime_view.rst @@ -147,9 +147,17 @@ meanings): - critical - Something went wrong, but recovery is not possible Severity increases from "trace" to "critical" such that "trace" is the least -important and "critical" is the most severe log statements. In practice, the -value of a computed result usually falls under debug or trace. There's at least -two ways to do that: +important and "critical" is the most severe log statements. This means that +all logging statements with severity trace and above are enabled if the +severity ofthe logger is set to trace. If the logger is set to debug, all +debug, info, warn, error, and critical message logs are enabled, while trace +message logs are not. As another example, info severity includes info, warn, +error, critical logging statements, and warn includes warn, error, and critical +loggingstatements. + + +In practice, the value of a computed result usually falls under debug or +trace. There's at least two ways to do that: .. tabs:: @@ -172,6 +180,28 @@ level has its own corresponding method. The second example shows how to use the more general ``log`` method. This particular overload of the ``log`` method allows you to specify (at runtime if you like) the severity of the message. +************ +Code Example +************ + +Here is an example in both Python and C++ that shows the differences in output +when different severities are set: + +.. tabs:: + + .. tab:: C++ + .. code-block:: C++ + + // TODO + + .. tab:: Python + + .. literalinclude:: ../../../tests/python/doc_snippets/test_logging.py + :language: python + :lines: 24-40 + :dedent: 8 + + .. note:: Notice that we did not discuss where the log message gets printed. This is diff --git a/tests/python/doc_snippets/test_logging.py b/tests/python/doc_snippets/test_logging.py new file mode 100644 index 00000000..5f183767 --- /dev/null +++ b/tests/python/doc_snippets/test_logging.py @@ -0,0 +1,42 @@ +# Copyright 2025 NWChemEx-Project +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import parallelzone as pz +import unittest + + +class TestLoggerTestCase(unittest.TestCase): + + def test_logging(self): + rv = pz.runtime.RuntimeView() + my_rs = rv.my_resource_set() + + log = pz.runtime.RuntimeView().logger() + severity = pz.Logger.severity + severities = [ + severity.trace, severity.debug, severity.info, severity.warn, + severity.error, severity.critical + ] + + log.set_severity(severity.critical) + + for level in severities: + log.log(level, "Hello") + + log.set_severity(severity.trace) + + for level in severities: + log.log(level, "Hello") + + self.assertIsNotNone(my_rs)