Skip to content

Fine-tune logging notes in contributing.rst. #12094

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 11, 2018
Merged

Fine-tune logging notes in contributing.rst. #12094

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
efdd8d7
Fine-tune logging notes in contributing.rst.
anntzer Sep 11, 2018
9867019
Fix typo...
jklymak Sep 11, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 15 additions & 13 deletions doc/devel/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -449,29 +449,31 @@ 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 <https://docs.python.org/3/howto/logging.html#logging-basic-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`.

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 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

.. _custom_backend:

Expand Down