bpo-35099: Improve the doc about IDLE running user code. (GH-10350)
The section is renamed from "IDLE -- console differences". It mostly
covers the implications of using custom sys.stdxxx objects.
(cherry picked from commit 5e7909032491cef17754a3208872655fe350e9be)
Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>
diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst
index 645bd61..c5015bf 100644
--- a/Doc/library/idle.rst
+++ b/Doc/library/idle.rst
@@ -563,7 +563,6 @@
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 @@
* Otherwise, arguments are files opened for editing and
``sys.argv`` reflects the arguments passed to IDLE itself.
-
Startup failure
^^^^^^^^^^^^^^^
@@ -635,27 +633,38 @@
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.
-IDLE also replaces ``sys.stdin``, ``sys.stdout``, and ``sys.stderr`` with
-objects that get input from and send output to the Shell window.
+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``.
+
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.
+and screen will not work. These include system-specific functions that
+determine whether a key has been pressed and if so, which.
-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.
+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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Misc/NEWS.d/next/IDLE/2018-11-05-20-43-08.bpo-35099.SVOZXC.rst b/Misc/NEWS.d/next/IDLE/2018-11-05-20-43-08.bpo-35099.SVOZXC.rst
new file mode 100644
index 0000000..1459f20
--- /dev/null
+++ b/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.