Jan-Philip Gehrcke added the comment:
Thanks for your feedback Antoine.
> I'm not sure what the doc patch achieves.
Let me try to bring things in order. It should achieve two things:
1. Properly describe the stderr-writing behavior of sys.exit().
===============================================================
Current 2.7 docs:
"..., and any other object is printed to stderr".
This is wrong in its generality and requires clarification. Agreed? How would
you improve the docs in this regard? This is the reasoning I had in mind:
We could change the original sentence, but IMO it then contains too many pieces
of important information and becomes difficult to digest, e.g.: "If another
type of object is passed, None is equivalent to passing zero, and any other
object is printed to stderr (only when called in the main thread) and results
in an exit code of 1.". Difficult, right?
I thought about removing the stderr part from this sentence and discussing this
topic separately, in simpler sentences. But: I think the stderr part needs to
stay in the original sentence, because it clarifies how different argument
types are dealt with.
Then I took another point of view: we have acknowledged that the behavior is
problematic, we just cannot change it anymore for 2.7. The direct consequence
from this point of view is to warn about current behavior. 6 years ago, I took
the docs literally and relied on getting proper error messages printed to
stderr. And I didn't get those. I would have appreciated a warning, I guess.
With this being said, I'd love to look at an alternative proposal of how we
could change the docs in this regard.
2. Clarify that when called from a thread, the thread exits silently
====================================================================
Current 2.7 docs:
"Since exit ultimately "only" raises an exception,
it will only exit the process when called from the main thread."
This sentence is problematic. It relates a cause to an effect, and this
relation is wrong or at least incomplete. The only valuable information left in
the sentence is the *effect*, without providing an explanation. I would rather
want to take the inverse approach, and explain the *cause* as correct as
possible. In other words: the above sentence misses to explain what actually
happens when sys.exit() is called in a non-primary thread.
The actual behavior and cause for mentioned effect is, as far as I am aware:
If raised in a non-primary thread, SystemExit is caught automatically and
causes the calling thread to exit silently.
This is what I added as a note.
And I think that we agree that this cause may have many effects, whereas only
one of them is that sys.exit() called from a non-primary thread can not
terminate the process.
> It only states more verbosely what is already
> said in the current version.
I hope to have convinced you that this is not true.
> Also, warnings are really for important issues
> (such as security issues); using them too liberally
> is a disservice to the reader.
I agree. I really think that both points need to be addressed in the docs, and
I have now clarified my reasoning, but am very open to further suggestions. And
I really do not want to make a strong point about whether things should end up
in red or blue boxes :-).
----------
_______________________________________
Python tracker <rep...@bugs.python.org>
<http://bugs.python.org/issue6634>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
