[docs] [issue19789] Improve wording of how to "undo" a call to logging.disable(lvl)

[Simon Weber]

New submission from Simon Weber:

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*.

----------
assignee: docs at python
components: Documentation
messages: 204451
nosy: docs at python, eric.araujo, ezio.melotti, georg.brandl, simonmweber
priority: normal
severity: normal
status: open
title: Improve wording of how to "undo" a call to logging.disable(lvl)
type: enhancement

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue19789>
_______________________________________