New submission from JJeffries
Changes by JJeffries
R. David Murray
I think it would be good to mention the numeric levels in the text as well (in parenthesis, perhaps), unless the rest of the logging docs no longer refer to the numeric levels.
AFAICS, there are no numbers in the logging docs anymore.
Should there be another issue opened to do something about the extra logging
IMO they shouldn't have been added in the first place, but I'm not sure if they're part of the public API and hence subject to backward-compatibility constraints. It would be nice to hear a justification for them from Jesse (or someone else). Of course levels are a bit subjective and logging supports user-defined levels for special cases, but using multiple libs with different added levels would be a headache. I think at least the stdlib should stick to the standard levels.
Camilla Montonen added the comment:
This issue raises the fact that the 2.X documentation
lists two logging levels (SUBDEBUG and SUBWARNING)
without explaining how these two fit into the logging
hierarchy of the logging levels provided by the standard library logging module
(ie, is SUBDEBUG between INFO and DEBUG).
The patch (provided by JJeffries and modified by Petri Lehtinen)
adds an explanatory note stating the hierarchy as follows
These are :const:`SUBWARNING`,
+which fits between :const:`INFO` and :const:`WARNING` in the normal logging
+hierarchy, and :const:`SUBDEBUG`, which fits below :const:`DEBUG`
Review (this applies to the 2.X version of the documentation)
1. It would be nice to clarify that SUBDEBUG is between DEBUG and NOTSET
instead of saying that it is 'below' as this maybe misunderstood (at least it's not very clear to me).
2. Slightly unrelated to the main issue of this patch
2a) "In addition to having these two logging functions, the multiprocessing also"
"In addition to having these two logging functions, the multiprocessing module also"
3. The documentation for the multiprocessing module in Python 3.X has removed any mention
of SUBWARNING and SUBDEBUG, so I'm not sure if this patch is even relevant anymore?
4. Also, slightly tangent to this patch, but might be nice to pick up is the fact that
documentation for the 2.X version mentions that the logging level table can be viewed in
the logging module documentation
"For a full table of logging levels, see the logging module."
which is not the case anymore. As Vinay Sajip mentions, in 2.X the logging level table
has moved to the how-to https://docs.python.org/2/howto/logging.html#logging-levels
and so this link should be updated as well
1. Check if SUBWARNING and SUBDEBUG are still part of the public API in 3.X and then
suggest alterations to documentation based on that.