bpo-35099: Improve the doc about IDLE running user code. (#10350)

The section is renamed from "IDLE -- console differences".  It mostly
covers the implications of using custom sys.stdxxx objects.

Doc/library/idle.rst

@@ -563,7 +563,6 @@ looked for in the user's home directory.  Statements in this file will be
 executed in the Tk namespace, so this file is not useful for importing
 functions to be used from IDLE's Python shell.
 
-
 Command line usage
 ^^^^^^^^^^^^^^^^^^
 
@@ -591,7 +590,6 @@ If there are arguments:
 * Otherwise, arguments are files opened for editing and
   ``sys.argv`` reflects the arguments passed to IDLE itself.
 
-
 Startup failure
 ^^^^^^^^^^^^^^^
 
@@ -635,27 +633,38 @@ be to delete one or more of the configuration files.
 If IDLE quits with no message, and it was not started from a console, try
 starting from a console (``python -m idlelib)`` and see if a message appears.
 
-
-IDLE-console differences
-^^^^^^^^^^^^^^^^^^^^^^^^
+Running user code
+^^^^^^^^^^^^^^^^^
 
 With rare exceptions, the result of executing Python code with IDLE is
-intended to be the same as executing the same code in a console window.
+intended to be the same as executing the same code by the default method,
+directly with Python in a text-mode system console or terminal window.
 However, the different interface and operation occasionally affect
-visible results.  For instance, ``sys.modules`` starts with more entries.
+visible results.  For instance, ``sys.modules`` starts with more entries,
+and ``threading.activeCount()`` returns 2 instead of 1.
+
+By default, IDLE runs user code in a separate OS process rather than in
+the user interface process that runs the shell and editor.  In the execution
+process, it replaces ``sys.stdin``, ``sys.stdout``, and ``sys.stderr``
+with objects that get input from and send output to the Shell window.
+The original values stored in ``sys.__stdin__``, ``sys.__stdout__``, and
+``sys.__stderr__`` are not touched, but may be ``None``.
 
-IDLE also replaces ``sys.stdin``, ``sys.stdout``, and ``sys.stderr`` with
-objects that get input from and send output to the Shell window.
 When Shell has the focus, it controls the keyboard and screen.  This is
 normally transparent, but functions that directly access the keyboard
-and screen will not work.  If ``sys`` is reset with ``importlib.reload(sys)``,
-IDLE's changes are lost and things like ``input``, ``raw_input``, and
-``print`` will not work correctly.
-
-With IDLE's Shell, one enters, edits, and recalls complete statements.
-Some consoles only work with a single physical line at a time.  IDLE uses
-``exec`` to run each statement.  As a result, ``'__builtins__'`` is always
-defined for each statement.
+and screen will not work.  These include system-specific functions that
+determine whether a key has been pressed and if so, which.
+
+IDLE's standard stream replacements are not inherited by subprocesses
+created in the execution process, whether directly by user code or by modules
+such as multiprocessing.  If such subprocess use ``input`` from sys.stdin
+or ``print`` or ``write`` to sys.stdout or sys.stderr,
+IDLE should be started in a command line window.  The secondary subprocess
+will then be attached to that window for input and output.
+
+If ``sys`` is reset by user code, such as with ``importlib.reload(sys)``,
+IDLE's changes are lost and input from the keyboard and output to the screen
+will not work correctly.
 
 Developing tkinter applications
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Misc/NEWS.d/next/IDLE/2018-11-05-20-43-08.bpo-35099.SVOZXC.rst

@@ -0,0 +1,3 @@
+Improve the doc about IDLE running user code.   The section is renamed from
+"IDLE -- console differences" is renamed "Running user code".
+It mostly covers the implications of using custom sys.stdxxx objects.