From 01c48adb75a62f08e190831208c46bed148898e4 Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Mon, 5 Nov 2018 20:40:13 -0500 Subject: [PATCH 1/4] bpo-35099: Improve the doc about IDLE running user code. The section is renamed from "IDLE -- console differences". It mostly covers the implications of using custom sys.stdxxx objects. --- Doc/library/idle.rst | 35 +++++++++++++++++++++-------------- 1 file changed, 21 insertions(+), 14 deletions(-) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index 645bd612618bc7..b761b191fac14d 100644 --- a/Doc/library/idle.rst +++ b/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,36 @@ 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. 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 +By default, IDLE run user code is a separate OS process rather than the +same process as the user interface. It replaces ``sys.stdin``, ``sys.stdout``, +and ``sys.stderr`` in the execution process 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. + +IDLE's standard stream replacements are not inherited by subprocesses +created by user code or by modules, such as multiprocessing, that create +subprocesses. One should start IDLE in a system console if one creates +subprocesses that use ``input`` and ``print``. User subprocess will then +be attached to the console for input and output. -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. +If ``sys`` is reset with ``importlib.reload(sys)``, +IDLE's changes are lost and functions like ``input`` and +``print`` will not work correctly. Developing tkinter applications ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 23f392f18b6d59300c97bf0ad1b32e56ab00d6c7 Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Mon, 5 Nov 2018 20:43:26 -0500 Subject: [PATCH 2/4] blurb --- Misc/NEWS.d/next/IDLE/2018-11-05-20-43-08.bpo-35099.SVOZXC.rst | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 Misc/NEWS.d/next/IDLE/2018-11-05-20-43-08.bpo-35099.SVOZXC.rst 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 00000000000000..58f7c64a219210 --- /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". It mostly covers the implications of using +custom sys.stdxxx objects. From 54058514f65911d19946e8b1b5c5924e3b51defc Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Mon, 5 Nov 2018 21:17:39 -0500 Subject: [PATCH 3/4] Revise text and blurb. --- Doc/library/idle.rst | 28 ++++++++++--------- .../2018-11-05-20-43-08.bpo-35099.SVOZXC.rst | 4 +-- 2 files changed, 17 insertions(+), 15 deletions(-) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index b761b191fac14d..160f3a517c340f 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -637,15 +637,16 @@ 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, and ``threading.activeCount()`` returns 2 instead of 1. -By default, IDLE run user code is a separate OS process rather than the -same process as the user interface. It replaces ``sys.stdin``, ``sys.stdout``, -and ``sys.stderr`` in the execution process 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. @@ -655,14 +656,15 @@ 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 by user code or by modules, such as multiprocessing, that create -subprocesses. One should start IDLE in a system console if one creates -subprocesses that use ``input`` and ``print``. User subprocess will then -be attached to the console for input and output. - -If ``sys`` is reset with ``importlib.reload(sys)``, -IDLE's changes are lost and functions like ``input`` and -``print`` will not work correctly. +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 index 58f7c64a219210..1459f20cb78f62 100644 --- 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 @@ -1,3 +1,3 @@ Improve the doc about IDLE running user code. The section is renamed from -"IDLE -- console differences". It mostly covers the implications of using -custom sys.stdxxx objects. +"IDLE -- console differences" is renamed "Running user code". +It mostly covers the implications of using custom sys.stdxxx objects. From dee8a46d707e6426bbecf63aa077e544105f59bc Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Mon, 5 Nov 2018 21:21:44 -0500 Subject: [PATCH 4/4] Quote dunder words. --- Doc/library/idle.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index 160f3a517c340f..c5015bf30cfb78 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -647,8 +647,8 @@ 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. +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