From 9f878ddc6973b4f7674d96a078da0928fe5a2a05 Mon Sep 17 00:00:00 2001 From: Jacob Heflin Date: Tue, 6 May 2025 12:43:51 -0500 Subject: [PATCH 1/4] added more description to logging and a python example --- docs/source/user/runtime_view.rst | 51 +++++++++++++++++++++++++++++-- 1 file changed, 48 insertions(+), 3 deletions(-) diff --git a/docs/source/user/runtime_view.rst b/docs/source/user/runtime_view.rst index b9308cbe..a3977291 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 set as trace and below are enabled if the severity of +the 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. For completeness, info includes info, warn, error, critical, and +warn includes warn, error, critical, and error includes error and critical, +and critical only includes critical. + + +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,43 @@ 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. +******************** +Python Example +******************** + +.. tabs:: + + .. tab:: Python + + .. code-block:: python + + import parallelzone as pz + + 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") + + # OUTPUT: + # [2025-05-06 11:29:54.722] [Rank 0] [critical] Hello + + log.set_severity(severity.trace) + + for level in severities: + log.log(level, "Hello") + + # OUTPUT: + # [2025-05-06 11:33:05.203] [Rank 0] [trace] Hello + # [2025-05-06 11:33:05.203] [Rank 0] [debug] Hello + # [2025-05-06 11:33:05.203] [Rank 0] [info] Hello + # [2025-05-06 11:33:05.203] [Rank 0] [warning] Hello + # [2025-05-06 11:33:05.203] [Rank 0] [error] Hello + # [2025-05-06 11:33:05.203] [Rank 0] [critical] Hello + .. note:: Notice that we did not discuss where the log message gets printed. This is From 4cdab8f4a8cd7ac0d3a81da91ea97c78beb8c8d2 Mon Sep 17 00:00:00 2001 From: Jacob Heflin Date: Tue, 6 May 2025 15:48:24 -0500 Subject: [PATCH 2/4] Added test_logging.py to doc_snippets and adjusted documenation for reST compliance --- docs/source/user/runtime_view.rst | 52 +++++++---------------- tests/python/doc_snippets/test_logging.py | 29 +++++++++++++ 2 files changed, 45 insertions(+), 36 deletions(-) create mode 100644 tests/python/doc_snippets/test_logging.py diff --git a/docs/source/user/runtime_view.rst b/docs/source/user/runtime_view.rst index a3977291..0dac4603 100644 --- a/docs/source/user/runtime_view.rst +++ b/docs/source/user/runtime_view.rst @@ -148,12 +148,12 @@ meanings): Severity increases from "trace" to "critical" such that "trace" is the least important and "critical" is the most severe log statements. This means that -all logging statements set as trace and below are enabled if the severity of -the 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. For completeness, info includes info, warn, error, critical, and -warn includes warn, error, critical, and error includes error and critical, -and critical only includes critical. +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 @@ -180,42 +180,22 @@ 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. -******************** -Python Example -******************** +************ +Code Example +************ + +Here is an example in both Python and C++ that shows the differences in output +when different severities are set: .. tabs:: .. tab:: Python - .. code-block:: python - - import parallelzone as pz - - 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") - - # OUTPUT: - # [2025-05-06 11:29:54.722] [Rank 0] [critical] Hello - - log.set_severity(severity.trace) - - for level in severities: - log.log(level, "Hello") + .. literalinclude:: ../../../tests/python/doc_snippets/test_logging.py + :language: python + :lines: 10-22 + :dedent: 8 - # OUTPUT: - # [2025-05-06 11:33:05.203] [Rank 0] [trace] Hello - # [2025-05-06 11:33:05.203] [Rank 0] [debug] Hello - # [2025-05-06 11:33:05.203] [Rank 0] [info] Hello - # [2025-05-06 11:33:05.203] [Rank 0] [warning] Hello - # [2025-05-06 11:33:05.203] [Rank 0] [error] Hello - # [2025-05-06 11:33:05.203] [Rank 0] [critical] Hello .. note:: diff --git a/tests/python/doc_snippets/test_logging.py b/tests/python/doc_snippets/test_logging.py new file mode 100644 index 00000000..b91b14c2 --- /dev/null +++ b/tests/python/doc_snippets/test_logging.py @@ -0,0 +1,29 @@ +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) From 563fabf1e18c9ec61e240495739129b602dcb39b Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 6 May 2025 20:50:31 +0000 Subject: [PATCH 3/4] Committing clang-format changes --- tests/python/doc_snippets/test_logging.py | 25 +++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/tests/python/doc_snippets/test_logging.py b/tests/python/doc_snippets/test_logging.py index b91b14c2..5f183767 100644 --- a/tests/python/doc_snippets/test_logging.py +++ b/tests/python/doc_snippets/test_logging.py @@ -1,6 +1,21 @@ +# 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): @@ -9,12 +24,10 @@ def test_logging(self): log = pz.runtime.RuntimeView().logger() severity = pz.Logger.severity - severities = [severity.trace, - severity.debug, - severity.info, - severity.warn, - severity.error, - severity.critical] + severities = [ + severity.trace, severity.debug, severity.info, severity.warn, + severity.error, severity.critical + ] log.set_severity(severity.critical) From 47e53f491bc0b23e80fb4210b87b7fcda0fe42c8 Mon Sep 17 00:00:00 2001 From: Jacob Heflin Date: Tue, 6 May 2025 16:49:22 -0500 Subject: [PATCH 4/4] Cleaned up documentation additions --- docs/source/user/runtime_view.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/source/user/runtime_view.rst b/docs/source/user/runtime_view.rst index 0dac4603..745c3f46 100644 --- a/docs/source/user/runtime_view.rst +++ b/docs/source/user/runtime_view.rst @@ -189,11 +189,16 @@ 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: 10-22 + :lines: 24-40 :dedent: 8