From efdd8d73d458a7a337388812a22f1843e8355ad9 Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Tue, 11 Sep 2018 15:38:56 +0200 Subject: [PATCH 1/2] Fine-tune logging notes in contributing.rst. - Note that warnings.warn displays warnings only once, and suggest to use it for things that should be modified in the source (it's not for no reason that it displays the corresponding line in the source...). - Suggest not logging at INFO level for normal code paths. --- doc/devel/contributing.rst | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index b40a46a6fa92..8aea2028d5a9 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -449,16 +449,15 @@ Then they will receive messages like:: Which logging level to use? ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There are five levels at which you can emit messages. -`logging.critical` and `logging.error` -are really only there for errors that will end the use of the library but -not kill the interpreter. `logging.warning` overlaps with the -``warnings`` library. The -`logging tutorial `_ -suggests that the difference -between `logging.warning` and `warnings.warn` is that -`warnings.warn` be used for things the user must change to stop -the warning, whereas `logging.warning` can be more persistent. +There are five levels at which you can emit messages. `logging.critical` and +`logging.error` are really only there for errors that will end the use of the +library but not kill the interpreter. `logging.warning` overlaps with the +`warnings` library. The `logging tutorial`_ suggests that the difference +between `logging.warning` and `warnings.warn` is that `warnings.warn` should +be used for things the user must change to stop the warning (typically in the +source), whereas `logging.warning` can be more persistent. Moreover, note +that `warnings.warn` will by default only emit a given warning *once*, whereas +`logging.warning` will display the message every time it is called. By default, `logging` displays all log messages at levels higher than `logging.WARNING` to `sys.stderr`. @@ -466,12 +465,15 @@ By default, `logging` displays all log messages at levels higher than Calls to `logging.info` are not displayed by default. They are for information that the user may want to know if the program behaves oddly. For instance, if an object isn't drawn because its position is ``NaN``, -that can usually be ignored, but a mystified user could set +that can usually be ignored, but a mystified user could call ``logging.basicConfig(level=logging.INFO)`` and get an error message that says why. -`logging.debug` is the least likely to be displayed, and hence can -be the most verbose. +`logging.debug` is the least likely to be displayed, and hence can be the most +verbose. "Expected" code paths (e.g., reporting normal intermediat steps of +layouting or rendering) should only log at this level. + +.. _logging tutorial: https://docs.python.org/3/howto/logging.html#logging-basic-tutorial .. _custom_backend: From 98670198d592a2ebf7f398a83ba043447403182c Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Tue, 11 Sep 2018 12:28:26 -0700 Subject: [PATCH 2/2] Fix typo... --- doc/devel/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 8aea2028d5a9..edf5d2228fd3 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -470,7 +470,7 @@ that can usually be ignored, but a mystified user could call says why. `logging.debug` is the least likely to be displayed, and hence can be the most -verbose. "Expected" code paths (e.g., reporting normal intermediat steps of +verbose. "Expected" code paths (e.g., reporting normal intermediate steps of layouting or rendering) should only log at this level. .. _logging tutorial: https://docs.python.org/3/howto/logging.html#logging-basic-tutorial