classification
Title: logging.Logger.disabled is not documented
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, mariocj89, vinay.sajip
Priority: low Keywords: patch

Created on 2019-05-30 22:03 by mariocj89, last changed 2019-05-31 10:26 by mariocj89. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 13687 closed mariocj89, 2019-05-30 22:03
Messages (5)
msg344007 - (view) Author: Mario Corchero (mariocj89) * (Python triager) Date: 2019-05-30 22:03
Just realised the "disabled" attribute of the Logger class is not documented in https://docs.python.org/3/library/logging.html#logging.Logger.

Any reason to not have it documented? I'll send a PR otherwise.

This comes as I was trying to point to the docs of the attribute in https://bugs.python.org/issue29143
msg344044 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2019-05-31 09:12
Thanks for looking at this, Mario, but I'd rather not document this attribute, for the reason stated on the PR when I closed it:

"I'd like to avoid documenting this attribute, as it's really meant for internal use by the configuration machinery. I realise that it's named disabled rather than _disabled, which might indicate that it's public, but it isn't meant to be, and the name can't be changed now for compatibility reasons, in case some code somewhere is relying on it! I don't want someone to ask for "disabled" to be explicitly supported in configurations, for instance - I can currently argue that it's not meant to be public, as it isn't documented."
msg344054 - (view) Author: Mario Corchero (mariocj89) * (Python triager) Date: 2019-05-31 10:00
Thanks! I was wondering about it but saw no comment about it, issue or anything in the history. At least we have now this issue :).

Would you like that I move this to `_disabled` and have a setter for `disabled` that emits a deprecation warning so we can remove this someday or at least make it more explicit that it should not be used?
msg344056 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2019-05-31 10:13
As it's not documented, people would come across it by browsing the source. I'd just mention in the source (Logger constructor) that it's for internal use, and leave it at that.
msg344058 - (view) Author: Mario Corchero (mariocj89) * (Python triager) Date: 2019-05-31 10:26
Note that even if not in the standard library I've seen this attributed used and documented quite often.

Example: https://docs.python-guide.org/writing/logging/#or-print

I would really suggest making it private as mentioned before to make sure this does not happen, but if you still prefer just a comment (as in source comment, not even documentation) I'll go with that.
History
Date User Action Args
2019-05-31 10:26:25mariocj89setmessages: + msg344058
2019-05-31 10:13:28vinay.sajipsetmessages: + msg344056
2019-05-31 10:00:35mariocj89setmessages: + msg344054
2019-05-31 09:12:33vinay.sajipsetstatus: open -> closed

nosy: + vinay.sajip
messages: + msg344044

resolution: not a bug
stage: patch review -> resolved
2019-05-30 22:03:46mariocj89setkeywords: + patch
stage: patch review
pull_requests: + pull_request13575
2019-05-30 22:03:29mariocj89create