[Python-checkins] gh-107877: Update logging levels reference table with usage criteria. (#107894)

[vsajip]

https://github.com/python/cpython/commit/cc2cf85d03cf29994a707aae5cc9a349a4165b84
commit: cc2cf85d03cf29994a707aae5cc9a349a4165b84
branch: main
author: Vinay Sajip <vinay_sajip at yahoo.co.uk>
committer: vsajip <vinay_sajip at yahoo.co.uk>
date: 2023-08-13T14:19:41+01:00
summary:

gh-107877: Update logging levels reference table with usage criteria. (#107894)

Co-authored-by: Alex Waygood <Alex.Waygood at Gmail.com>

files:
M Doc/library/logging.rst

diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index 4c6e74ff66a11..b582c918df023 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -397,21 +397,39 @@ have specific values relative to the predefined levels. If you define a level
 with the same numeric value, it overwrites the predefined value; the predefined
 name is lost.
 
-+-----------------------+---------------+
-| Level                 | Numeric value |
-+=======================+===============+
-| .. py:data:: CRITICAL | 50            |
-+-----------------------+---------------+
-| .. py:data:: ERROR    | 40            |
-+-----------------------+---------------+
-| .. py:data:: WARNING  | 30            |
-+-----------------------+---------------+
-| .. py:data:: INFO     | 20            |
-+-----------------------+---------------+
-| .. py:data:: DEBUG    | 10            |
-+-----------------------+---------------+
-| .. py:data:: NOTSET   | 0             |
-+-----------------------+---------------+
++-----------------------+---------------+-------------------------------------+
+| Level                 | Numeric value | What it means / When to use it      |
++=======================+===============+=====================================+
+| .. py:data:: NOTSET   | 0             | When set on a logger, indicates that|
+|                       |               | ancestor loggers are to be consulted|
+|                       |               | to determine the effective level.   |
+|                       |               | If that still resolves to           |
+|                       |               | :const:`!NOTSET`, then all events   |
+|                       |               | are logged. When set on a handler,  |
+|                       |               | all events are handled.             |
++-----------------------+---------------+-------------------------------------+
+| .. py:data:: DEBUG    | 10            | Detailed information, typically only|
+|                       |               | of interest to a developer trying to|
+|                       |               | diagnose a problem.                 |
++-----------------------+---------------+-------------------------------------+
+| .. py:data:: INFO     | 20            | Confirmation that things are working|
+|                       |               | as expected.                        |
++-----------------------+---------------+-------------------------------------+
+| .. py:data:: WARNING  | 30            | An indication that something        |
+|                       |               | unexpected happened, or that a      |
+|                       |               | problem might occur in the near     |
+|                       |               | future (e.g. 'disk space low'). The |
+|                       |               | software is still working as        |
+|                       |               | expected.                           |
++-----------------------+---------------+-------------------------------------+
+| .. py:data:: ERROR    | 40            | Due to a more serious problem, the  |
+|                       |               | software has not been able to       |
+|                       |               | perform some function.              |
++-----------------------+---------------+-------------------------------------+
+| .. py:data:: CRITICAL | 50            | A serious error, indicating that the|
+|                       |               | program itself may be unable to     |
+|                       |               | continue running.                   |
++-----------------------+---------------+-------------------------------------+
 
 
 .. _handler: