[issue37563] Documentation - default for StreamHandler
New submission from Jonathan <bugreports@lightpear.com>: https://docs.python.org/2/library/logging.handlers.html https://docs.python.org/3/library/logging.handlers.html Both say: """class logging.StreamHandler(stream=None) Returns a new instance of the StreamHandler class. If stream is specified, the instance will use it for logging output; otherwise, sys.stderr will be used.""" Surely that means from an user perspective that the default is actually `sys.stderr`, not `None`? ---------- assignee: docs@python components: Documentation messages: 347677 nosy: docs@python, jonathan-lp priority: normal severity: normal status: open title: Documentation - default for StreamHandler versions: Python 3.9 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37563> _______________________________________
Change by Karthikeyan Singaravelan <tir.karthi@gmail.com>: ---------- nosy: +vinay.sajip _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37563> _______________________________________
Vinay Sajip <vinay_sajip@yahoo.co.uk> added the comment: If None is passed, that is interpreted to mean whatever the implementation default is, and that is sys.stderr. For backwards compatibility, that won't change: and I don't see any need to update the documentation, as it makes it perfectly clear that sys.stderr will be used if None is specified. Nor do I see a need to change the default parameter value from its current value of None. ---------- resolution: -> not a bug stage: -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37563> _______________________________________
Change by Jonathan <bugreports@lightpear.com>: ---------- status: -> open _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37563> _______________________________________
Vinay Sajip <vinay_sajip@yahoo.co.uk> added the comment: The devil is in the detail. If stream=sys.stderr is specified, that takes effect at import time. If stream=None is specified and the implementation chooses to treat that as sys.stderr, that takes effect at the time of the call. The two are not equivalent. It was a conscious choice by me to implement it this way, and I believe it's clearly documented what happens, which should be sufficiently clear for users. Which part of "If stream is specified, the instance will use it for logging output; otherwise, sys.stderr will be used." is unclear? ---------- resolution: -> not a bug status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37563> _______________________________________
Jonathan <bugreports@lightpear.com> added the comment:
The devil is in the detail. If stream=sys.stderr is specified, that takes effect at import time. If stream=None is specified and the implementation chooses to treat that as sys.stderr, that takes effect at the time of the call. The two are not equivalent.
But this isn't what the prose says at all. You're right, the prose clearly say that the default is sys.stderr, however the code doesn't show that, and many people won't read the prose (I don't a lot of the time), they'll only look at the code snippet because that's all they think they need. The code-snippet claims that the default is None, which from a user perspective isn't true. Again I point out that the documentation is for users, not implementers. We users Do. Not. Care. about how wonderfully clever your implementation is, we care about how it actually works. Whatever Rube-Goldbergian implementation details there are behind the scenes are of no interest to us. Yet again: There's a standard for documenting defaults for keyword arguments, I would ask that it please be used consistently to help us users. Fine, lets try this another way - does anyone else have opinions on this? What's the convention for documentation defaults? ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37563> _______________________________________
Vinay Sajip <vinay_sajip@yahoo.co.uk> added the comment:
the prose clearly say that the default is sys.stderr, however the code doesn't show that
Which code are you looking at? Here is the entirety of StreamHandler.__init__: def __init__(self, stream=None): """ Initialize the handler. If stream is not specified, sys.stderr is used. """ Handler.__init__(self) if stream is None: stream = sys.stderr self.stream = stream
We users Do. Not. Care. about how wonderfully clever your implementation is, we care about how it actually works. Whatever Rube-Goldbergian implementation details there are behind the scenes are of no interest to us.
I'm not sure your tone is particularly constructive here. I don't regard the code you say you've read, reproduced above, is particularly Rube-Goldbergian, or even Heath-Robinsonish. And are you presuming to speak for all Python users here?
Fine, lets try this another way - does anyone else have opinions on this?
As far as I can remember, you're the first person to bring this up since logging was added to Python in 2003. In all that time, no-one appears to have been confused by that prose, which has been there since pretty much the beginning, though there was a spelling change and a logging documentation reorganisation around 9 years ago. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37563> _______________________________________
Jonathan <bugreports@lightpear.com> added the comment:
I'm not sure your tone is particularly constructive here. Apologies, my bad.
Which code are you looking at? The documentation code: `class logging.StreamHandler(stream=None)`. Sorry, I don't know what you'd call that. I'm not referring to the code proper.
As far as I can remember, you're the first person to bring this up since logging was added to Python in 2003. This is a fallacy. Just because no-one else has reported it doesn't mean it hasn't caused a problem. I mean, I'm sure there are plenty of spelling errors/typos in the docs that no-one has reported for years, it doesn't mean they shouldn't be fixed when raised. It's also assuming you have seen and remember every single bug report related to this from the past 16 years which, nothing personal, seems incredibly unlikely given how poor humans are at remembering things in the first place.
And are you presuming to speak for all Python users here? I'm presuming to speak for end-users yes, why not? I did ask for other input too you'll note. After a few decades of practice I'm fairly decent at getting into the headspace of users (of which I am one in this case), and I know it's something many developers don't really do well. A common mistake we developers make is to assume that everyone knows what we know and thinks like us.
---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37563> _______________________________________
Vinay Sajip <vinay_sajip@yahoo.co.uk> added the comment:
This is a fallacy.
What fallacy? I was responding to "does anyone else have opinions on this?" I can't read minds of people all over the world, so I have to go by my best guess, which is based on how many times this issue has been reported before - which I believe is zero.
It's also assuming you have seen and remember every single bug report related to this from the past 16 years which, nothing personal, seems incredibly unlikely given how poor humans are at remembering things in the first place.
Feel free to do a search on here to see if you can find an earlier issue about this.
I'm presuming to speak for end-users yes, why not?
Because they're a very diverse bunch who don't all speak with one voice. I, too, am a user (of other people's code) as much as a developer. I don't see things the same way as you do, here, and it's not because it's my code. I'd probably feel the same way if you'd pointed to some other instance of Python code which does the same kind of thing. There are numerous examples in the stdlib where None is passed in and some other value (e.g. 'utf-8' for an encoding) are used as a default, without that value appearing in any documented argument list. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37563> _______________________________________
Jonathan <bugreports@lightpear.com> added the comment:
What fallacy? You appeared to be saying (to paraphrase) "no-one else has ever reported this, so it's never been a problem". That's a fallacy.
I was responding to "does anyone else have opinions on this?" I was asking if anyone else wanted to chime in with an opinion.
There are numerous examples in the stdlib where None is passed in and some other value (e.g. 'utf-8' for an encoding) are used as a default Then for clarity's purpose I'd suggest those be changed too, but that's another ticket.
---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37563> _______________________________________
participants (3)
-
Jonathan -
Karthikeyan Singaravelan
-
Vinay Sajip