logging.Logger.disabled is not documented

[mariocj89]

BPO	37104
Nosy	@vsajip, @mariocj89
PRs	bpo-37104: docs: Add docs about the Logger.disabled attribute #13687

^{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 2019-05-31.09:12:33.701>
created_at = <Date 2019-05-30.22:03:29.127>
labels = ['invalid', 'type-feature', '3.8', 'docs']
title = 'logging.Logger.disabled is not documented'
updated_at = <Date 2019-05-31.10:26:25.928>
user = 'https://github.com/mariocj89'

bugs.python.org fields:

activity = <Date 2019-05-31.10:26:25.928>
actor = 'mariocj89'
assignee = 'docs@python'
closed = True
closed_date = <Date 2019-05-31.09:12:33.701>
closer = 'vinay.sajip'
components = ['Documentation']
creation = <Date 2019-05-30.22:03:29.127>
creator = 'mariocj89'
dependencies = []
files = []
hgrepos = []
issue_num = 37104
keywords = ['patch']
message_count = 5.0
messages = ['344007', '344044', '344054', '344056', '344058']
nosy_count = 3.0
nosy_names = ['vinay.sajip', 'docs@python', 'mariocj89']
pr_nums = ['13687']
priority = 'low'
resolution = 'not a bug'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue37104'
versions = ['Python 3.8']

[mariocj89]

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

[vsajip]

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

[mariocj89]

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?

[vsajip]

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.

[mariocj89]

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.