Improve wording of how to "undo" a call to logging.disable(lvl)

[simonmweber]

BPO	19789
Nosy	@birkenfeld, @vsajip, @ezio-melotti, @merwok

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2013-11-30.22:46:42.249>
created_at = <Date 2013-11-26.05:14:20.345>
labels = ['type-feature', 'docs']
title = 'Improve wording of how to "undo" a call to logging.disable(lvl)'
updated_at = <Date 2013-11-30.22:46:42.247>
user = 'https://bugs.python.org/simonmweber'

bugs.python.org fields:

activity = <Date 2013-11-30.22:46:42.247>
actor = 'python-dev'
assignee = 'docs@python'
closed = True
closed_date = <Date 2013-11-30.22:46:42.249>
closer = 'python-dev'
components = ['Documentation']
creation = <Date 2013-11-26.05:14:20.345>
creator = 'simonmweber'
dependencies = []
files = []
hgrepos = []
issue_num = 19789
keywords = []
message_count = 4.0
messages = ['204451', '204803', '204845', '204854']
nosy_count = 7.0
nosy_names = ['georg.brandl', 'vinay.sajip', 'ezio.melotti', 'eric.araujo', 'docs@python', 'python-dev', 'simonmweber']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue19789'
versions = ['Python 2.7', 'Python 3.3', 'Python 3.4']

[simonmweber]

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

[vsajip]

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.

[simonmweber]

That sounds much clearer. Thanks!

[python-dev]

New changeset b6377ca8087a by Vinay Sajip in branch '2.7':
Issue bpo-19789: Clarified documentation for logging.disable.
http://hg.python.org/cpython/rev/b6377ca8087a

New changeset 5c8130b85c17 by Vinay Sajip in branch '3.3':
Issue bpo-19789: Clarified documentation for logging.disable.
http://hg.python.org/cpython/rev/5c8130b85c17

New changeset eae4b83108fb by Vinay Sajip in branch 'default':
Closes bpo-19789: Merged update from 3.3.
http://hg.python.org/cpython/rev/eae4b83108fb