Issue 21995: Explain some differences between IDLE and console Python.

Doc/library/idle.rst

@@ -16,7 +16,7 @@ IDLE has the following features:
 
 * coded in 100% pure Python, using the :mod:`tkinter` GUI toolkit
 
-* cross-platform: works on Windows, Unix, and Mac OS X
+* cross-platform: works mostly the same on Windows, Unix, and Mac OS X
 
 * Python shell window (interactive interpreter) with colorizing
   of code input, output, and error messages
@@ -492,8 +492,8 @@ Shell colors:
       black
 
 
-Startup
--------
+Startup and code execution
+--------------------------
 
 Upon startup with the ``-s`` option, IDLE will execute the file referenced by
 the environment variables :envvar:`IDLESTARTUP` or :envvar:`PYTHONSTARTUP`.
@@ -538,10 +538,27 @@ If there are arguments:
   ``sys.argv`` reflects the arguments passed to IDLE itself.
 
 
+IDLE-console differences
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+As much as possible, the result of executing Python code with IDLE is the
+same as executing the same code in a console window.  However, the different
+interface and operation occasionally affects results.
+
+For instance, IDLE normally executes user code in a separate process from
+the IDLE GUI itself.  The IDLE versions of sys.stdin, .stdout, and .stderr in the
+execution process get input from and send output to the GUI process,
+which keeps control of the keyboard and screen.  This is normally transparent,
+but code that access these object will see different attribute values.
+Also, functions that directly access the keyboard and screen will not work.
+
+With IDLE's Shell, one enters, edits, and recalls complete statements.
+Some consoles only work with a single physical line at a time.
+
 Running without a subprocess
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-By default, Idle executes user code in a separate subprocess via a socket,
+By default, IDLE executes user code in a separate subprocess via a socket,
 which uses the internal loopback interface.  This connection is not
 externally visible and no data is sent to or received from the Internet.
 If firewall software complains anyway, you can ignore it.

Lib/idlelib/help.html

@@ -79,7 +79,7 @@
 <p>IDLE has the following features:</p>
 <ul class="simple">
 <li>coded in 100% pure Python, using the <a class="reference internal" href="tkinter.html#module-tkinter" title="tkinter: Interface to Tcl/Tk for graphical user interfaces"><tt class="xref py py-mod docutils literal"><span class="pre">tkinter</span></tt></a> GUI toolkit</li>
-<li>cross-platform: works on Windows, Unix, and Mac OS X</li>
+<li>cross-platform: works mostly the same on Windows, Unix, and Mac OS X</li>
 <li>Python shell window (interactive interpreter) with colorizing
 of code input, output, and error messages</li>
 <li>multi-window text editor with multiple undo, Python colorizing,
@@ -223,7 +223,12 @@ there is a syntax error, the approximate location is indicated in the
 Editor window.</dd>
 <dt>Run Module</dt>
 <dd>Do Check Module (above).  If no error, restart the shell to clean the
-environment, then execute the module.</dd>
+environment, then execute the module.  Output is displayed in the Shell
+window.  Note that output requires use of <tt class="docutils literal"><span class="pre">print</span></tt> or <tt class="docutils literal"><span class="pre">write</span></tt>.
+When execution is complete, the Shell retains focus and displays a prompt.
+At this point, one may interactively explore the result of execution.
+This is similar to executing a file with <tt class="docutils literal"><span class="pre">python</span> <span class="pre">-i</span> <span class="pre">file</span></tt> at a command
+line.</dd>
 </dl>
 </div>
 <div class="section" id="shell-menu-shell-window-only">
@@ -467,8 +472,8 @@ uncolorized text.  To change the color scheme, edit the <tt class="docutils lite
 </dd>
 </dl>
 </div>
-<div class="section" id="startup">
-<h2>25.5.4. Startup<a class="headerlink" href="#startup" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="startup-and-code-execution">
+<h2>25.5.4. Startup and code execution<a class="headerlink" href="#startup-and-code-execution" title="Permalink to this headline">¶</a></h2>
 <p>Upon startup with the <tt class="docutils literal"><span class="pre">-s</span></tt> option, IDLE will execute the file referenced by
 the environment variables <span class="target" id="index-5"></span><tt class="xref std std-envvar docutils literal"><span class="pre">IDLESTARTUP</span></tt> or <span class="target" id="index-6"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONSTARTUP"><tt class="xref std std-envvar docutils literal"><span class="pre">PYTHONSTARTUP</span></tt></a>.
 IDLE first checks for <tt class="docutils literal"><span class="pre">IDLESTARTUP</span></tt>; if <tt class="docutils literal"><span class="pre">IDLESTARTUP</span></tt> is present the file
@@ -506,9 +511,23 @@ set in the Options dialog.</li>
 <tt class="docutils literal"><span class="pre">sys.argv</span></tt> reflects the arguments passed to IDLE itself.</li>
 </ul>
 </div>
+<div class="section" id="idle-console-differences">
+<h3>25.5.4.2. IDLE-console differences<a class="headerlink" href="#idle-console-differences" title="Permalink to this headline">¶</a></h3>
+<p>As much as possible, the result of executing Python code with IDLE is the
+same as executing the same code in a console window.  However, the different
+interface and operation occasionally affects results.</p>
+<p>For instance, IDLE normally executes user code in a separate process from
+the IDLE GUI itself.  The IDLE versions of sys.stdin, .stdout, and .stderr in the
+execution process get input from and send output to the GUI process,
+which keeps control of the keyboard and screen.  This is normally transparent,
+but code that access these object will see different attribute values.
+Also, functions that directly access the keyboard and screen will not work.</p>
+<p>With IDLE&#8217;s Shell, one enters, edits, and recalls complete statements.
+Some consoles only work with a single physical line at a time.</p>
+</div>
 <div class="section" id="running-without-a-subprocess">
-<h3>25.5.4.2. Running without a subprocess<a class="headerlink" href="#running-without-a-subprocess" title="Permalink to this headline">¶</a></h3>
-<p>By default, Idle executes user code in a separate subprocess via a socket,
+<h3>25.5.4.3. Running without a subprocess<a class="headerlink" href="#running-without-a-subprocess" title="Permalink to this headline">¶</a></h3>
+<p>By default, IDLE executes user code in a separate subprocess via a socket,
 which uses the internal loopback interface.  This connection is not
 externally visible and no data is sent to or received from the Internet.
 If firewall software complains anyway, you can ignore it.</p>
@@ -599,9 +618,10 @@ are currently:</p>
 </ul>
 </li>
 <li><a class="reference internal" href="#syntax-colors">25.5.3. Syntax colors</a></li>
-<li><a class="reference internal" href="#startup">25.5.4. Startup</a><ul>
+<li><a class="reference internal" href="#startup-and-code-execution">25.5.4. Startup and code execution</a><ul>
 <li><a class="reference internal" href="#command-line-usage">25.5.4.1. Command line usage</a></li>
-<li><a class="reference internal" href="#running-without-a-subprocess">25.5.4.2. Running without a subprocess</a></li>
+<li><a class="reference internal" href="#idle-console-differences">25.5.4.2. IDLE-console differences</a></li>
+<li><a class="reference internal" href="#running-without-a-subprocess">25.5.4.3. Running without a subprocess</a></li>
 </ul>
 </li>
 <li><a class="reference internal" href="#help-and-preferences">25.5.5. Help and preferences</a><ul>
@@ -676,7 +696,7 @@ are currently:</p>
     The Python Software Foundation is a non-profit corporation.
     <a href="https://www.python.org/psf/donations/">Please donate.</a>
     <br />
-    Last updated on Sep 23, 2015.
+    Last updated on Sep 24, 2015.
     <a href="../bugs.html">Found a bug</a>?
     <br />
     Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2.3.