Issue 37104: logging.Logger.disabled is not documented (original) (raw)

Issue37104

Created on 2019-05-30 22:03 by mariocj89, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Messages (5)
msg344007 - (view)	Author: Mario Corchero (mariocj89) *	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) *	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) *	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) *	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) *	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.