Author jgehrcke
Recipients Arfrever, David.Manowitz, docs@python, ggenellina, jgehrcke, martin.panter, pitrou, stutzbach, terry.reedy
Date 2015-02-03.14:00:57
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1422972058.57.0.803527365609.issue6634@psf.upfronthosting.co.za>
In-reply-to
Content
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 :-).
History
Date User Action Args
2015-02-03 14:00:58jgehrckesetrecipients: + jgehrcke, terry.reedy, ggenellina, pitrou, stutzbach, Arfrever, docs@python, martin.panter, David.Manowitz
2015-02-03 14:00:58jgehrckesetmessageid: <1422972058.57.0.803527365609.issue6634@psf.upfronthosting.co.za>
2015-02-03 14:00:58jgehrckelinkissue6634 messages
2015-02-03 14:00:57jgehrckecreate