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: 

https://docs.python.org/3/using/cmdline.html#cmdoption-O

https://docs.python.org/3/using/cmdline.html#envvar-PYTHONOPTIMIZE

It just says "basic optimizations". Are there any other optimizations except the two I mentioned?

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.

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?

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.

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.

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 :)

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.

Thanks for your understanding David.

I'll submit a patch for this issue soon.

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.

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 bugs.python.org. 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.

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?

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.

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.

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.

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.

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.

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.

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.

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

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 :)

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 ;)

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.

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.

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.