classification
Title: Improve -O docs
Type: behavior Stage: patch review
Components: Documentation Versions: Python 3.4, Python 3.3, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: terry.reedy Nosy List: Arfrever, Ramchandra Apte, brett.cannon, docs@python, eli.bendersky, ezio.melotti, fijall, ncoghlan, pitrou, terry.reedy, vadmium
Priority: normal Keywords: patch

Created on 2013-02-19 06:25 by fijall, last changed 2013-11-29 21:50 by Arfrever.

Files
File name Uploaded Description Edit
issue17232.diff terry.reedy, 2013-02-22 18:43 review
17232-O.diff terry.reedy, 2013-03-12 20:10 Add :const:, tweek -OO review
Messages (17)
msg182365 - (view) Author: Maciej Fijalkowski (fijall) * (Python committer) Date: 2013-02-19 06:25
This is what the current documentation says:

-O
Turn on basic optimizations. This changes the filename extension for compiled (bytecode) files from .pyc to .pyo. See also PYTHONOPTIMIZE.

-OO
Discard docstrings in addition to the -O optimizations.

As far as I know, the only "optimization" that's done is removal of __debug__ sections and assert statements and has been like this for years. Maybe it should say so "-O does not do any optimizations, only removes assert statement" or so.
msg182373 - (view) Author: Ramchandra Apte (Ramchandra Apte) * Date: 2013-02-19 12:34
It should also add that in the future, more optimizations may be added i.e. a peephole optimizer, etc.
msg182377 - (view) Author: Maciej Fijalkowski (fijall) * (Python committer) Date: 2013-02-19 12:40
There were not for at least 10 years. I would also be the first one to strongly object adding optimizations only under -O, because that already changes semantics.
msg182380 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-02-19 14:12
Ramchandra, as it turns out, if we deem an optimization semantically safe, we do it without -O, it we deem it unsafe, we don't do it at all.

Thus, the real effect is to remove assert statements and optimise code as if "__debug__" was replaced by a literal zero (effectively).

So a more meaningful description would be:

-O
Removes assert statements and any code conditional on the value of __debug__. This changes the filename extension for compiled (bytecode) files from .pyc to .pyo. See also PYTHONOPTIMIZE.
msg182680 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-02-22 18:43
I agree that we should document exactly what is now. Patch replaces first sentence with Nick's. It is against 3.4, but should be identical for all versions. Maciej, thanks for reminding us to finally fix this.
msg182681 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-02-22 18:45
Should probably be "Remove", not "Removes" (we use infinitives to describe the actions undertaken by a command / option / method ...).
msg182682 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-02-22 18:46
Perhaps '__debug__' need markup, but if so, I don't know how.
And I agree with Antoine.
msg182729 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-02-23 10:11
+1 for Remove instead of Removes

For the online docs, :const:`__debug__` should work (resolving to http://docs.python.org/3/library/constants.html#__debug__, which is currently described using some slightly brain-bending phrasing)

We should also tweak the output of "python -h" (the help string is in ./Modules/main.c)
msg182738 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2013-02-23 13:20
+1, I've been bothered by this description of "optimization" for a long time. 

Terry's patch LGTM
msg182742 - (view) Author: Maciej Fijalkowski (fijall) * (Python committer) Date: 2013-02-23 13:34
Also IMO -OO should stop talking about optimizations. Maybe "Do what -O does and discard docstrings"?
msg184047 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-03-12 20:10
I added :const: and tweaked -OO entry and -h startup display.
Tested new html and python_d -h. Any other comments before I apply?
msg184048 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-03-12 20:17
There's a typo in your patch:

+-O     : remove assert and __debug__-dependent statements; change .py\n\
+         to .pyo; also PYTHONOPTIMIZE=x\n\

should say ".pyc", not ".py".
msg184049 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-03-12 20:18
Also, in 3.2 and higher I'm not sure there's a point in mentioning pyc/pyo files; they're all shelved in __pycache__ now.
msg184051 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-03-12 21:28
I corrected my copy of the .diff.

Since this issue is so far focused on removing the false optimize claim, hiding .pyx info is a new sub-issue. I will follow whatever the consensus is, but since this is a cpython-specific doc and help, I would prefer to give complete info. In fact, I would like to add 'stored in __pycache__' or even 'hidden away in  __pycache__', the latter to suggest that most people should generally forget about them. On Windows, _xxx files like __pycache__ appear in both Command Prompt dir and Explorer file listings, so beginners need to known that __cache__ is both normal and ignorable.
msg184070 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-03-13 06:56
On Tue, Mar 12, 2013 at 1:18 PM, Antoine Pitrou <report@bugs.python.org> wrote:
>
> Antoine Pitrou added the comment:
>
> Also, in 3.2 and higher I'm not sure there's a point in mentioning pyc/pyo files; they're all shelved in __pycache__ now.

It still makes a difference for bytecode-only files, which aren't in __pycache__

Cheers,
Nick.
msg184141 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-03-14 07:47
I left a review on rietveld.
msg195475 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-08-17 14:30
Terry, do you want to update your patch?
History
Date User Action Args
2013-11-29 21:50:01Arfreversetnosy: + Arfrever
2013-11-28 01:08:46vadmiumsetnosy: + vadmium
2013-08-17 14:30:38ezio.melottisetmessages: + msg195475
versions: - Python 3.2
2013-03-14 07:47:41ezio.melottisetnosy: + ezio.melotti

messages: + msg184141
stage: patch review
2013-03-13 06:56:01ncoghlansetmessages: + msg184070
2013-03-12 21:28:04terry.reedysetmessages: + msg184051
2013-03-12 20:18:28pitrousetmessages: + msg184049
2013-03-12 20:17:37pitrousetmessages: + msg184048
2013-03-12 20:10:06terry.reedysetfiles: + 17232-O.diff
assignee: docs@python -> terry.reedy
messages: + msg184047
2013-02-23 13:34:48fijallsetmessages: + msg182742
2013-02-23 13:20:00eli.benderskysetnosy: + eli.bendersky
messages: + msg182738
2013-02-23 10:11:47ncoghlansetmessages: + msg182729
2013-02-22 18:46:12terry.reedysetmessages: + msg182682
2013-02-22 18:45:11pitrousetnosy: + pitrou
messages: + msg182681
2013-02-22 18:43:37terry.reedysetfiles: + issue17232.diff
versions: + Python 2.7, Python 3.2, Python 3.3, Python 3.4
nosy: + terry.reedy

messages: + msg182680

keywords: + patch
2013-02-19 14:54:54brett.cannonsetnosy: + brett.cannon
2013-02-19 14:12:03ncoghlansetnosy: + ncoghlan
messages: + msg182380
2013-02-19 12:40:48fijallsetmessages: + msg182377
2013-02-19 12:34:30Ramchandra Aptesetnosy: + Ramchandra Apte
messages: + msg182373
2013-02-19 06:25:01fijallcreate