This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Improve wording of how to "undo" a call to logging.disable(lvl)
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eric.araujo, ezio.melotti, georg.brandl, python-dev, simonmweber, vinay.sajip
Priority: normal Keywords:

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)
msg204451 - (view) 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*.
msg204803 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) 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.
msg204845 - (view) Author: Simon Weber (simonmweber) Date: 2013-11-30 21:04
That sounds much clearer. Thanks!
msg204854 - (view) Author: Roundup Robot (python-dev) (Python triager) 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:54adminsetgithub: 63988
2013-11-30 22:46:42python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg204854

resolution: fixed
stage: resolved
2013-11-30 21:04:11simonmwebersetmessages: + msg204845
2013-11-30 11:16:54vinay.sajipsetmessages: + msg204803
versions: + Python 2.7, Python 3.3, Python 3.4
2013-11-30 07:07:17ezio.melottisetnosy: + vinay.sajip
2013-11-26 05:14:20simonmwebercreate