classification
Title: Multiprocessing logging levels unclear
Type: Stage: patch review
Components: Documentation Versions: Python 3.2, Python 3.3
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: JJeffries, Winterflower, davin, docs@python, jnoller, ncoghlan, petri.lehtinen, r.david.murray, vinay.sajip
Priority: normal Keywords: needs review, patch

Created on 2011-05-25 11:54 by JJeffries, last changed 2015-12-27 16:49 by davin.

Files
File name Uploaded Description Edit
multiprocessing_logging.patch JJeffries, 2011-05-25 12:32 Patch removing table and adding description instead.
multiprocessing_logging_2.patch petri.lehtinen, 2011-05-25 15:04 review
Messages (10)
msg136839 - (view) Author: JJeffries (JJeffries) Date: 2011-05-25 11:54
It is unclear without reference to the logging module where the multiprocessing logging levels fit in the normal logging provided by the logging module, even though it says above the table

"The table below illustrates where theses fit in the
normal level hierarchy.

+----------------+----------------+
| Level          | Numeric value  |
+================+================+
| ``SUBWARNING`` | 25             |
+----------------+----------------+
| ``SUBDEBUG``   | 5              |
+----------------+----------------+"

I propose adding further values from the logging module for clarification.
msg136841 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2011-05-25 12:19
It seems that the documentation of logging no longer gives a table with numeric values for levels (I remember seeing it before). Maybe it would be most useful to remove the table from multiprocessing documentation and state it explicitly that "SUBDEBUG is lower than DEBUG and SUBWARNING is between INFO and WARNING".
msg136844 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2011-05-25 12:39
The patch is in an invalid format. See http://docs.python.org/devguide/patch.html for instructions on working with patches. If you cannot/won't use Mercurial, use two separate directories for original and modified cpython source tree, and invoke:

    diff -urN cpython-orig cpython-modified
msg136852 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2011-05-25 15:04
Converted the patch by JJeffries to a valid format.
msg138260 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-06-13 16:16
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.
msg138293 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2011-06-14 05:38
R. David Murray wrote:
> 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.
msg143068 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2011-08-27 14:27
Although the reference docs don't list the numeric values of logging levels, this happened during reorganising of the docs. The table has moved to the HOWTO:

http://docs.python.org/howto/logging.html#logging-levels

That said, I don't understand the need for special logging levels in the multiprocessing package. From the section following the one linked to above:

"Defining your own levels is possible, but should not be necessary, as the existing levels have been chosen on the basis of practical experience. However, if you are convinced that you need custom levels, great care should be exercised when doing this, and it is possibly *a very bad idea to define custom levels if you are developing a library*. That’s because if multiple library authors all define their own custom levels, there is a chance that the logging output from such multiple libraries used together will be difficult for the using developer to control and/or interpret, because a given numeric value might mean different things for different libraries."
msg145780 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2011-10-18 08:25
Should there be another issue opened to do something about the extra logging levels?
msg145867 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2011-10-18 20:05
> Should there be another issue opened to do something about the extra logging 

> levels?

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.
msg256407 - (view) Author: Camilla Montonen (Winterflower) Date: 2015-12-14 17:56
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"

Should be 

"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


TODO:
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.
History
Date User Action Args
2015-12-27 16:49:34davinsetnosy: + davin
2015-12-14 17:56:20Winterflowersetnosy: + Winterflower
messages: + msg256407
2011-10-18 20:05:22vinay.sajipsetmessages: + msg145867
2011-10-18 08:25:56petri.lehtinensetmessages: + msg145780
2011-08-27 14:27:34vinay.sajipsetnosy: + vinay.sajip
messages: + msg143068
2011-07-24 17:58:43petri.lehtinensetkeywords: + needs review
stage: patch review
versions: + Python 3.2
2011-06-14 05:38:16petri.lehtinensetmessages: + msg138293
2011-06-13 16:16:01r.david.murraysetnosy: + r.david.murray
messages: + msg138260
2011-05-26 06:29:34ncoghlansetnosy: + ncoghlan, jnoller
2011-05-25 15:04:38petri.lehtinensetfiles: + multiprocessing_logging_2.patch

messages: + msg136852
2011-05-25 12:39:37petri.lehtinensetmessages: + msg136844
2011-05-25 12:32:06JJeffriessetfiles: + multiprocessing_logging.patch
keywords: + patch
2011-05-25 12:19:23petri.lehtinensetnosy: + petri.lehtinen
messages: + msg136841
2011-05-25 11:54:07JJeffriescreate