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

[vsajip]

https://github.com/python/cpython/commit/e2420c5cae7a173c5242b3507979010a933e53a7
commit: e2420c5cae7a173c5242b3507979010a933e53a7
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: vsajip <vinay_sajip at yahoo.co.uk>
date: 2023-08-13T14:43:14+01:00
summary:

[3.11] gh-107877: Update logging levels reference table with usage criteria. (GH-107894) (GH-107921)

gh-107877: Update logging levels reference table with usage criteria. (GH-107894)
(cherry picked from commit cc2cf85d03cf29994a707aae5cc9a349a4165b84)

files:
M Doc/library/logging.rst

diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index 954681efb4436..09dc887ee2415 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -385,21 +385,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: