bpo-31421: Document how IDLE runs tkinter programs. (#3513)

IDLE calls tcl/tk update in the background in order to make live
interaction and experimentatin with tkinter applications much easier.

1 files changed, 29 insertions, 6 deletions

diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst
index 38ab4f1..0faeb6d 100644
--- a/Doc/library/idle.rst
+++ b/Doc/library/idle.rst
@@ -599,15 +599,15 @@ starting from a console (``python -m idlelib)`` and see if a message appears.
 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 affect visible results.  For instance,
-``sys.modules`` starts with more entries.
+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.
+However, the different interface and operation occasionally affect
+visible results.  For instance, ``sys.modules`` starts with more entries.
 
 IDLE also replaces ``sys.stdin``, ``sys.stdout``, and ``sys.stderr`` with
 objects that get input from and send output to the Shell window.
-When this window has the focus, it controls the keyboard and screen.
-This is normally transparent, but functions that directly access the keyboard
+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.
@@ -617,6 +617,29 @@ 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.
 
+Developing tkinter applications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+IDLE is intentionally different from standard Python in order to
+facilitate development of tkinter programs.  Enter ``import tkinter as tk;
+root = tk.Tk()`` in standard Python and nothing appears.  Enter the same
+in IDLE and a tk window appears.  In standard Python, one must also enter
+``root.update()`` to see the window.  IDLE does the equivalent in the
+background, about 20 times a second, which is about every 50 milleseconds.
+Next enter ``b = tk.Button(root, text='button'); b.pack()``.  Again,
+nothing visibly changes in standard Python until one enters ``root.update()``.
+
+Most tkinter programs run ``root.mainloop()``, which usually does not
+return until the tk app is destroyed.  If the program is run with
+``python -i`` or from an IDLE editor, a ``>>>`` shell prompt does not
+appear until ``mainloop()`` returns, at which time there is nothing left
+to interact with.
+
+When running a tkinter program from an IDLE editor, one can comment out
+the mainloop call.  One then gets a shell prompt immediately and can
+interact with the live application.  One just has to remember to
+re-enable the mainloop call when running in standard Python.
+
 Running without a subprocess
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^