[issue17232] Improve -O docs

[Terry J. Reedy]

Change by Terry J. Reedy :


--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[miss-islington]

miss-islington  added the comment:


New changeset fc9471a888f373aedff3c118ae9a6cbf2037bd7c by Miss Islington (bot) 
in branch '3.6':
bpo-17232: Clarify docs for -O and -OO command line options (GH-5839)
https://github.com/python/cpython/commit/fc9471a888f373aedff3c118ae9a6cbf2037bd7c


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[miss-islington]

miss-islington  added the comment:


New changeset b5655f3d187084579ff389dbd8734742a8b66cbc by Miss Islington (bot) 
in branch '3.7':
bpo-17232: Clarify docs for -O and -OO command line options (GH-5839)
https://github.com/python/cpython/commit/b5655f3d187084579ff389dbd8734742a8b66cbc


--
nosy: +miss-islington

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[miss-islington]

Change by miss-islington :


--
pull_requests: +5642

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[miss-islington]

Change by miss-islington :


--
pull_requests: +5641

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Terry J. Reedy]

Terry J. Reedy  added the comment:


New changeset 186b606d8a2ea4fd51b7286813302c8e8c7006cc by Terry Jan Reedy 
(Cheryl Sabella) in branch 'master':
bpo-17232: Clarify docs for -O and -OO command line options (#5839)
https://github.com/python/cpython/commit/186b606d8a2ea4fd51b7286813302c8e8c7006cc


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Cheryl Sabella]

Cheryl Sabella  added the comment:

I've made a PR and tried to integrate the changes from PEP 488.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Cheryl Sabella]

Change by Cheryl Sabella :


--
pull_requests: +5616
stage: needs patch -> patch review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Nick Coghlan]

Nick Coghlan  added the comment:

We don't change the extension on optimised pyc files any more, we add an 
optimisation marker to the name without changing the file extension: 
https://www.python.org/dev/peps/pep-0488/

(This means `-O` and `-OO` don't tread on each other any more)

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Terry J. Reedy]

Terry J. Reedy  added the comment:

Cheryl: yes, with changes in responses to Ezio's review.

Nick or Antoine: has there been any change to meaning of -O or -OO that I am 
not remembering?

--
versions: +Python 3.6, Python 3.7, Python 3.8 -Python 3.4, Python 3.5

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Cheryl Sabella]

Cheryl Sabella  added the comment:

Should I make a pull request for Terry's last patch?

--
nosy: +csabella

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[STINNER Victor]

Changes by STINNER Victor :


--
nosy: +haypo

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Berker Peksag]

Changes by Berker Peksag :


--
nosy: +berker.peksag

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Serhiy Storchaka]

Changes by Serhiy Storchaka storch...@gmail.com:


--
stage: patch review - needs patch
versions: +Python 3.5 -Python 3.3

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Arfrever Frehtes Taifersar Arahesis]

Changes by Arfrever Frehtes Taifersar Arahesis arfrever@gmail.com:


--
nosy: +Arfrever

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Martin Panter]

Changes by Martin Panter vadmium...@gmail.com:


--
nosy: +vadmium

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Ezio Melotti]

Ezio Melotti added the comment:

Terry, do you want to update your patch?

--
versions:  -Python 3.2

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Ezio Melotti]

Ezio Melotti added the comment:

I left a review on rietveld.

--
nosy: +ezio.melotti
stage:  - patch review

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Nick Coghlan]

Nick Coghlan added the comment:

On Tue, Mar 12, 2013 at 1:18 PM, Antoine Pitrou rep...@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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Terry J. Reedy]

Terry J. Reedy added the comment:

I added :const: and tweaked -OO entry and -h startup display.
Tested new html and python_d -h. Any other comments before I apply?

--
assignee: docs@python - terry.reedy
Added file: http://bugs.python.org/file29392/17232-O.diff

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Antoine Pitrou]

Antoine Pitrou added the comment:

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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Antoine Pitrou]

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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Terry J. Reedy]

Terry J. Reedy added the comment:

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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Nick Coghlan]

Nick Coghlan added the comment:

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

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Eli Bendersky]

Eli Bendersky added the comment:

+1, I've been bothered by this description of optimization for a long time. 

Terry's patch LGTM

--
nosy: +eli.bendersky

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Maciej Fijalkowski]

Maciej Fijalkowski added the comment:

Also IMO -OO should stop talking about optimizations. Maybe Do what -O does 
and discard docstrings?

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Terry J. Reedy]

Terry J. Reedy added the comment:

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.

--
keywords: +patch
nosy: +terry.reedy
versions: +Python 2.7, Python 3.2, Python 3.3, Python 3.4
Added file: http://bugs.python.org/file29165/issue17232.diff

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Antoine Pitrou]

Antoine Pitrou added the comment:

Should probably be Remove, not Removes (we use infinitives to describe the 
actions undertaken by a command / option / method ...).

--
nosy: +pitrou

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Terry J. Reedy]

Terry J. Reedy added the comment:

Perhaps '__debug__' need markup, but if so, I don't know how.
And I agree with Antoine.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Ramchandra Apte]

Ramchandra Apte added the comment:

It should also add that in the future, more optimizations may be added i.e. a 
peephole optimizer, etc.

--
nosy: +Ramchandra Apte

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Maciej Fijalkowski]

Maciej Fijalkowski added the comment:

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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Nick Coghlan]

Nick Coghlan added the comment:

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.

--
nosy: +ncoghlan

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Brett Cannon]

Changes by Brett Cannon br...@python.org:


--
nosy: +brett.cannon

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17232] Improve -O docs

[Maciej Fijalkowski]

New submission from Maciej Fijalkowski:

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.

--
assignee: docs@python
components: Documentation
messages: 182365
nosy: docs@python, fijall
priority: normal
severity: normal
status: open
title: Improve -O docs
type: behavior

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue17232
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com