bpo-17232: Clarify docs for -O and -OO command line options (GH-5839)

The 'optimization' is for space in the executable file, not for run time.
(cherry picked from commit 186b606d8a2ea4fd51b7286813302c8e8c7006cc)

Co-authored-by: Cheryl Sabella <cheryl.sabella@gmail.com>

diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 9ffb714963169a6414d2765636de5cf3ffbb3f17..8463ad9f2fe77560817940eb6ebbc4adf0ceccb5 100644 (file)
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -246,12 +246,23 @@ Miscellaneous options
 
 .. cmdoption:: -O
 
-   Turn on basic optimizations.  See also :envvar:`PYTHONOPTIMIZE`.
+   Remove assert statements and any code conditional on the value of
+   :const:`__debug__`.  Augment the filename for compiled
+   (:term:`bytecode`) files by adding ``.opt-1`` before the ``.pyc``
+   extension (see :pep:`488`).  See also :envvar:`PYTHONOPTIMIZE`.
+
+   .. versionchanged:: 3.5
+      Modify ``.pyc`` filenames according to :pep:`488`.
 
 
 .. cmdoption:: -OO
 
-   Discard docstrings in addition to the :option:`-O` optimizations.
+   Do :option:`-O` and also discard docstrings.  Augment the filename
+   for compiled (:term:`bytecode`) files by adding ``.opt-2`` before the
+   ``.pyc`` extension (see :pep:`488`).
+
+   .. versionchanged:: 3.5
+      Modify ``.pyc`` filenames according to :pep:`488`.
 
 
 .. cmdoption:: -q

diff --git a/Misc/NEWS.d/next/Documentation/2018-02-23-12-48-03.bpo-17232.tmuTKL.rst b/Misc/NEWS.d/next/Documentation/2018-02-23-12-48-03.bpo-17232.tmuTKL.rst
new file mode 100644 (file)
index 0000000..5c14e91
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2018-02-23-12-48-03.bpo-17232.tmuTKL.rst
@@ -0,0 +1 @@
+Clarify docs for -O and -OO.  Patch by Terry Reedy.

diff --git a/Misc/python.man b/Misc/python.man
index 075b974e90495558f9a1763038755661feb343bc..ad3ea6a431f5561f4d05430eeb15225f53294342 100644 (file)
--- a/Misc/python.man
+++ b/Misc/python.man
@@ -156,10 +156,13 @@ for the named module and runs the corresponding
 file as a script.
 .TP
 .B \-O
-Turn on basic optimizations.  Given twice, causes docstrings to be discarded.
+Remove assert statements and any code conditional on the value of
+__debug__; augment the filename for compiled (bytecode) files by
+adding .opt-1 before the .pyc extension.
 .TP
 .B \-OO
-Discard docstrings in addition to the \fB-O\fP optimizations.
+Do \fB-O\fP and also discard docstrings; change the filename for
+compiled (bytecode) files by adding .opt-2 before the .pyc extension.
 .TP
 .B \-q
 Do not print the version and copyright messages. These messages are

diff --git a/Modules/main.c b/Modules/main.c
index 3ac405c0bd91d92097fc54cbf2616ea1135de737..585d6965dd361682be4b5da8b22ba26aea01ec69 100644 (file)
--- a/Modules/main.c
+++ b/Modules/main.c
@@ -64,8 +64,10 @@ static const char usage_2[] = "\
          if stdin does not appear to be a terminal; also PYTHONINSPECT=x\n\
 -I     : isolate Python from the user's environment (implies -E and -s)\n\
 -m mod : run library module as a script (terminates option list)\n\
--O     : optimize generated bytecode slightly; also PYTHONOPTIMIZE=x\n\
--OO    : remove doc-strings in addition to the -O optimizations\n\
+-O     : remove assert and __debug__-dependent statements; add .opt-1 before\n\
+         .pyc extension; also PYTHONOPTIMIZE=x\n\
+-OO    : do -O changes and also discard docstrings; add .opt-2 before\n\
+         .pyc extension\n\
 -q     : don't print version and copyright messages on interactive startup\n\
 -s     : don't add user site directory to sys.path; also PYTHONNOUSERSITE\n\
 -S     : don't imply 'import site' on initialization\n\