Title: More details about `-O` flag
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5
Status: closed Resolution: duplicate
Dependencies: Superseder: Improve -O docs
View: 17232
Assigned To: docs@python Nosy List: berker.peksag, cool-RR, docs@python, r.david.murray, terry.reedy
Priority: normal Keywords: patch

Created on 2016-07-24 09:46 by cool-RR, last changed 2016-09-12 10:31 by berker.peksag. This issue is now closed.

File name Uploaded Description Edit
1.patch cool-RR, 2016-07-26 05:44
2.patch cool-RR, 2016-07-29 15:24
3.patch cool-RR, 2016-07-29 19:58
Messages (24)
msg271142 - (view) Author: Ram Rachum (cool-RR) * Date: 2016-07-24 09:46
I wanted to ensure that the `-O` flag doesn't really do anything more than remove assert statement and make `__debug__` equal `False`. But the documentation for `-O` doesn't cover it:

It just says "basic optimizations". Are there any other optimizations except the two I mentioned?
msg271168 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2016-07-24 16:27
No, there are only the two optimizations, but I think historically the vagueness has been on purpose to allow us to add appropriate optimizations without breaking backwards-compatibility with what is documented.
msg271180 - (view) Author: Ram Rachum (cool-RR) * Date: 2016-07-24 19:13
So... The reasoning is that if someone adds optimizations to Python's `-O` mode (Something that hasn't happened in the last decade or two, right?) we want to save them from going to the trouble of writing two or three sentences in the docs describing the optimizations? Isn't it standard practice to require people who contribute code to Python to add documentation for their changes?

Anyway, I think that it'll be a good idea to add two or three sentences that document it. Would you like a patch? If so against which version?
msg271181 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2016-07-24 20:31
Two things. One, I don't know if you meant for your comment to come off as antagonistic, but it did.

Two, a patch is fine as long as it makes it clear that what optimizations are activated by the flag could change with no backwards-compatibility guarantees.
msg271240 - (view) Author: Ram Rachum (cool-RR) * Date: 2016-07-25 07:29
Yes, my comment was antagonistic. I'm baffled that the first response to someone who wants to contribute to Python is an esoteric argument against the contribution. I understand that sometimes not all contributions can be accepted because they break existing assumptions, but since that's not the case here, I think that this kind of responses just put people off contributing.

How about "Great idea, lots of people have been asking about Python's optimization mode on Stack Overflow and it'll be much nicer if they could see this information officially in the docs where they have more confidence that this information is correct. Except one thing, could you please mention that this behavior could change in future versions? This is important."

Anyway, I'll send a patch later.
msg271268 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-07-25 13:33
Ram: Brett gave you the benefit of the doubt on whether or not your comment was *intended* to be antagonistic.  Brett's comment was giving you the historical context for why it isn't documented, but said nothing about what we might do now.  In fact, his use of the term "historically" implies that we could re-evaluate things now if we wish to, whether or not he meant that.  You could have given him the benefit of the doubt.  I know that is often hard, though.  I've reacted negatively to a comment often enough myself that these days I try very hard to think two or three times about what the most charitable interpretation could be, and what the best way would be for moving the conversation forward in my response even if the other party really is being antagonistic.  I've found that this works well more often than not.

But yes, it is good for us to be reminded periodically that we should think about being welcoming any time we respond to a contribution.  (On the other hand, you aren't exactly a new contributor, so Brett may have assumed he could take some shortcuts in speaking to you.)

Also, you will find in *every* community that there is a tendency to "defend the status quo" (and we're explicit about this), so sometimes you do have to mount an argument for changing it.  That's just human nature, but is also something I've been trying to train myself to be aware of (I'm still working on getting better at both of these :)
msg271269 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-07-25 13:36
Heh, clarification on "we're explicit about this".  I was referring to Nick's aphorism, "The status quo wins a tie", which means that there has to be a *postive* reason to change the status quo.  That's what we're explicit about.
msg271270 - (view) Author: Ram Rachum (cool-RR) * Date: 2016-07-25 13:44
Thanks for your understanding David.

I'll submit a patch for this issue soon.
msg271274 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2016-07-25 14:03
I can see nothing wrong with msg271168. It's polite, informative, not apodictic and does not rule out the possibility of accepting a patch.

Also, it answers a direct question from msg271142.
msg271298 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2016-07-25 17:47
If you had viewed the comment as esoteric, Ram, then you could have politely asked for a more in-depth explanation. To me the explanation seemed clear: the optimizations had not been documented so we could feel free in changing what -O meant without breaking any assumptions people had made. I didn't think about suggesting a doc patch saying as such while still documenting what it currently does until after I explained why the documentation is the way it is.

As for discouraging contributions, please stop and think about how your messages read to newcomers to If I had never contributed and stumbled upon this issue thinking it was an easy one to help with and I saw an openly antagonistic message, I would think twice about participating if that was the kind of attitude I might be confronted with.

And then think about how this discourages me from contributing. I took personal time out of my weekend to give you a prompt reply to your issue instead of making you wait until Monday or until someone else happened to reply so you knew the issue was noticed and you didn't start working on a patch that may not get accepted. And in response to me taking the time to respond to your message I get an antagonistic response. How does that in any way inspire me to want to help you out with this issue? And I certainly don't need this documentation change as I know what -O and -OO do, so if my time to try and help someone with an issue I don't directly benefit from leads to me getting grief for my efforts then why should I bother helping anyone unless it also helps me? It's this sort of tone in communication that is unnecessarily hostile towards project maintainers that leads to burnout and long-term contributors such as myself walking away from a project (and I'm not stating this lightly; this is just one instance in a string of incidents like this where I have been treated poorly that has convinced me to take some time off from helping others in my spare time after Python 3.6b1 is released to prevent me from quitting the Python project entirely).

I'm going to remove myself from the nosy list so that I recuse myself from this issue so that my feelings about this whole situation doesn't influence any potential patch review.
msg271325 - (view) Author: Ram Rachum (cool-RR) * Date: 2016-07-26 05:44
I'm sorry everyone, for being unpleasant on this thread. Rereading the thread from the beginning, I think I misunderstood Brett's message and immediately saw it as someone trying to block my efforts rather than just answering the question I asked.

Anyway, I attached my patch. A couple of questions:

1. As you can see in the patch, I also found a spot in `Doc/c-api/veryhigh.rst` where optimization mode was mentioned, so I figured let's add the "this may change in the future" comment there. But I don't know that area of the docs at all, so let me know if that makes sense there.

2. I believe these are the docs for Python 3.4, right? Can this change be merged into the documentation for all versions of Python?
msg271379 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-07-26 15:34
It might be better to reduce redundancy (ie: minimize the places that would need changing) by creating a cross link from the option description to the technical details in veryhigh.rst.  You could make the existing words 'basic optimizations' the link text.

Doc changes will be made to 3.5 and 3.6.  I've adjusted the versions accordingly.  A single patch against 3.5 will be merged into 3.6 by the committer.
msg271633 - (view) Author: Ram Rachum (cool-RR) * Date: 2016-07-29 15:24
I uploaded a new patch.

I added another thing: Mentioning explicitly that no other optimizations are currently being made. I think this is important because it's often the question that the user is asking themselves. (At least my boss and team members have asked that, and people on Stack Overflow.)

I disagree with your suggestion to limit the change only to veryhigh.rst and link to there from cmdline.rst. I think this is an important piece of information so it should be available in cmdline.rst which is more visible than the technical veryhigh.rst. If you feel strongly about this issue let me know and I'll do it your way.
msg271638 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2016-07-29 17:21
Ram > (At least my boss and team members have asked that, and people on Stack Overflow.)

Ram, to me it would have been helpful if you had said this initially.  It gives a doc change request a bit more force.
msg271639 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-07-29 17:47
I think the cmdline ref telling you that optimizations are enabled or disabled is enough.  If someone wants technical information they can click on the link.  For comparison, the gcc man page lists what optimizations the -O levels enable, but does not explain them.  To understand what it does you must follow the "links" to the referenced optimization options.  If python had separate options for the individual optimizations we could do likewise, but we don't, so linking to the technical explanation seems like the logical thing to do instead.

Perhaps we can get the opinion of some other devs.
msg271643 - (view) Author: Ram Rachum (cool-RR) * Date: 2016-07-29 19:58
Hi David,

I attached a patch that follows your instructions, but to be honest, if I wasn't the person writing this patch and I wanted to find the information "Does Python do any optimization besides dumping asserts when I do -O?" I'm not sure I'd be able to understand the information from the docs with 3.patch applied. The documentation doesn't clearly state that `-O` causes an `optimize` value of 1. If it did it'll be a bit easier to understand. Still too difficult in my opinion (which is why I would personally put this information directly in cmdline.rst) but maybe a bit easier.
msg271644 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2016-07-29 19:59
The -O entry is unchanged from when the Using doc was added in 2007.  I believe there has been discussion about being more specific and that Guido said something, but that is the most I will say.
msg271704 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-07-30 21:19
You know, it's actually more complicated than this now.  We recently changed the way optimization levels are handled in pyc files in such a way that it is possible for other optimization 'levels" to be added by third parties.  So the reference information is no longer complete.  We may need to revise that section further.  And yes, there needs to be a mapping from O values to the optimization levels discussed in the reference, in one location or the other.
msg271705 - (view) Author: Ram Rachum (cool-RR) * Date: 2016-07-30 21:27
Hmm. What do you think about merging 3.patch now, and then possibly adding more information later? (Or asking the people who are designing the complex behvior you describe to write those docs.)
msg271706 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-07-30 21:35
I wouldn't object, but if I started to do it I'd wind up doing the research to "do it right" instead, so it would have to be someone else doing the intermediate commit :)
msg271707 - (view) Author: Ram Rachum (cool-RR) * Date: 2016-07-30 21:47
Well, I guess we had a fun week exchanging a couple thousand words about a two-line change to the docs that's now never going to happen ;)
msg271708 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-07-30 21:49
Oh, don't say never.  Berker seems to like these kind of small commits, and it won't get lost.  Who knows, I may even decide to tackle it.  Or someone else will decide to do the research and update your patch.
msg271709 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-07-30 21:51
Heh, that comment about Berker came out wrong.  I meant, he seems willing to do, and make time for, the small doc commits that some of the rest of us don't seem to get around to, which is great.
msg276017 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-09-12 10:31
This is a duplicate of issue 17232. Note that "This changes the filename extension for compiled files from ``.pyc`` to ``.pyo``." part is no longer true. See PEP 488 for details.
Date User Action Args
2016-09-12 10:31:50berker.peksagsetstatus: open -> closed

superseder: Improve -O docs

nosy: + berker.peksag
messages: + msg276017
resolution: duplicate
stage: resolved
2016-07-30 21:51:47r.david.murraysetmessages: + msg271709
2016-07-30 21:49:26r.david.murraysetmessages: + msg271708
2016-07-30 21:47:04cool-RRsetmessages: + msg271707
2016-07-30 21:35:01r.david.murraysetmessages: + msg271706
2016-07-30 21:27:36cool-RRsetmessages: + msg271705
2016-07-30 21:19:42r.david.murraysetmessages: + msg271704
2016-07-29 19:59:52terry.reedysetmessages: + msg271644
2016-07-29 19:58:17cool-RRsetfiles: + 3.patch

messages: + msg271643
2016-07-29 17:47:03r.david.murraysetmessages: + msg271639
2016-07-29 17:21:40terry.reedysetnosy: + terry.reedy
messages: + msg271638
2016-07-29 15:24:01cool-RRsetfiles: + 2.patch

messages: + msg271633
2016-07-26 15:34:43r.david.murraysetmessages: + msg271379
versions: - Python 3.3, Python 3.4
2016-07-26 05:44:12cool-RRsetfiles: + 1.patch
keywords: + patch
messages: + msg271325
2016-07-25 19:30:00skrahsetnosy: - skrah
2016-07-25 17:47:50brett.cannonsetnosy: - brett.cannon
2016-07-25 17:47:42brett.cannonsetmessages: + msg271298
2016-07-25 14:03:09skrahsetnosy: + skrah
messages: + msg271274
2016-07-25 13:44:27cool-RRsetmessages: + msg271270
2016-07-25 13:36:30r.david.murraysetmessages: + msg271269
2016-07-25 13:33:44r.david.murraysetnosy: + r.david.murray
messages: + msg271268
2016-07-25 07:29:08cool-RRsetmessages: + msg271240
2016-07-24 20:31:55brett.cannonsetmessages: + msg271181
2016-07-24 19:13:20cool-RRsetmessages: + msg271180
2016-07-24 16:27:40brett.cannonsetnosy: + brett.cannon
messages: + msg271168
2016-07-24 09:46:21cool-RRcreate