Issue 19789: Improve wording of how to "undo" a call to logging.disable(lvl) (original) (raw)
Created on 2013-11-26 05:14 by simonmweber, last changed 2022-04-11 14:57 by admin. This issue is now closed.
Messages (4)
Author: Simon Weber (simonmweber)
Date: 2013-11-26 05:14
In http://bugs.python.org/issue14864, this line was added to the logging.disable docstring:
To undo the effect of a call to logging.disable(lvl), call logging.disable(logging.NOTSET).
To prevent misunderstanding, I propose that this line be changed to:
Calling logging.disable(logging.NOTSET) will undo all previous calls to logging.disable(lvl).
While the original change was an improvement, it's misleading. "undoing the effect of a call" reads as "undoing the effect of the last call", which implies a stack -- think of text editor "undo" functionality. In other words, the current documentation implies behavior like a context manager:
import logging
start with all logging enabled
logging.disable(logging.CRITICAL)
all logging disabled
logging.disable(logging.WARNING)
only CRITICAL enabled
logging.disable(logging.NOTSET)
undo; all logging disabled
logging.disable(logging.NOTSET)
undo; all logging enabled
Since logging.disable is idempotent, we're not undoing a call, we're undoing all calls.
Author: Vinay Sajip (vinay.sajip) * 
Date: 2013-11-30 11:16
It's not the docstring in the code, it's the actual documentation. I propose to change it so that the documentation for disable will read:
Provides an overriding level lvl for all loggers which takes precedence over the logger's own level. When the need arises to temporarily throttle logging output down across the whole application, this function can be useful. Its effect is to disable all logging calls of severity lvl and below, so that if you call it with a value of INFO, then all INFO and DEBUG events would be discarded, whereas those of severity WARNING and above would be processed according to the logger's effective level. If logging.disable(logging.NOTSET) is called, it effectively removes this overriding level, so that logging output again depends on the effective levels of individual loggers.
Please confirm if this is still not clear enough, otherwise I will commit this in a day or two and close the issue.
Author: Simon Weber (simonmweber)
Date: 2013-11-30 21:04
That sounds much clearer. Thanks!
Author: Roundup Robot (python-dev) 
Date: 2013-11-30 22:46
New changeset b6377ca8087a by Vinay Sajip in branch '2.7': Issue #19789: Clarified documentation for logging.disable. http://hg.python.org/cpython/rev/b6377ca8087a
New changeset 5c8130b85c17 by Vinay Sajip in branch '3.3': Issue #19789: Clarified documentation for logging.disable. http://hg.python.org/cpython/rev/5c8130b85c17
New changeset eae4b83108fb by Vinay Sajip in branch 'default': Closes #19789: Merged update from 3.3. http://hg.python.org/cpython/rev/eae4b83108fb
History
Date
User
Action
Args
2022-04-11 14:57:54
admin
set
github: 63988
2013-11-30 22:46:42
python-dev
set
status: open -> closed
nosy: + python-dev
messages: +
resolution: fixed
stage: resolved
2013-11-30 21:04:11
simonmweber
set
messages: +
2013-11-30 11:16:54
vinay.sajip
set
messages: +
versions: + Python 2.7, Python 3.3, Python 3.4
2013-11-30 07:07:17
ezio.melotti
set
nosy: + vinay.sajip
2013-11-26 05:14:20
simonmweber
create