From 75d9d59ab3a372d3d78e6a1f5e9f256e29d0a9a6 Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Tue, 6 Nov 2018 12:37:36 -0500 Subject: bpo-23220: Explain how IDLE's Shell displays output (GH-10356) Add a new subsection to the doc. --- Doc/library/idle.rst | 60 +++++++++++++++++----- Lib/idlelib/help.html | 53 +++++++++++++++---- .../IDLE/2018-11-05-23-23-00.bpo-23220.H3SAWE.rst | 1 + 3 files changed, 91 insertions(+), 23 deletions(-) create mode 100644 Misc/NEWS.d/next/IDLE/2018-11-05-23-23-00.bpo-23220.H3SAWE.rst diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index c5015bf..fa58e2d 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -502,8 +502,16 @@ or immediately run an existing file before editing. Python Shell window ^^^^^^^^^^^^^^^^^^^ -The editing features described above work when entering code interactively. -IDLE's Shell window also responds to the following keys. +With IDLE's Shell, one enters, edits, and recalls complete statements. +Most consoles and terminals only work with a single physical line at a time. + +When one pastes code into Shell, it is not compiled and possibly executed +until one hits :kbd:`Return`. One may edit pasted code first. +If one pastes more that one statement into Shell, the result will be a +:exc:`SyntaxError` when multiple statements are compiled as if they were one. + +The editing features described in previous subsections work when entering +code interactively. IDLE's Shell window also responds to the following keys. * :kbd:`C-c` interrupts executing command @@ -520,16 +528,6 @@ IDLE's Shell window also responds to the following keys. * :kbd:`Return` while on any previous command retrieves that command -Shell has a special facility for squeezing output lines down to a -'Squeezed text' label. This is done automatically for output over N lines -(N = 50 by default). N can be changed in the PyShell section of the General -page of the Settings dialog. Output with fewer lines can be squeezed by -right clicking on the output. This can be useful for extra long lines. - -Squeezed output is expanded in place by double-clicking the label. -It can also be sent to the clipboard or a separate view window by -right-clicking the label. - Text colors ^^^^^^^^^^^ @@ -666,6 +664,44 @@ 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. +User output in Shell +^^^^^^^^^^^^^^^^^^^^ + +When a program outputs text, the result is determined by the +corresponding output device. When IDLE executes user code, ``sys.stdout`` +and ``sys.stderr`` are connected to the display area of IDLE's Shell. Some of +its features are inherited from the underlying Tk Text widget. Others +are programmed additions. + +Text widgets display a subset of Unicode, the Basic Multilingual Plane (BMP). +Which characters get a proper glyph instead of a replacement box depends on +the operating system and installed fonts. Newline characters cause following +text to appear on a new line, but other control characters are replaced +with a box. But note that the ``repr()`` function, which is used for +interactive echo of expression values, replaces control characters +with escape codes before they are output. + +Normal and error output are generally kept separate (on separate lines) +from code input and each other. They each get different highlight colors. + +For SyntaxError tracebacks, the normal '^' marking where the error was +detected is replaced by coloring the text with an error highlight. +When code run from a file causes other exceptions, one may right click +on a traceback line to jump to the corresponding line in an IDLE editor. +The file will be opened if necessary. + +Shell has a special facility for squeezing output lines down to a +'Squeezed text' label. This is done automatically +for output over N lines (N = 50 by default). +N can be changed in the PyShell section of the General +page of the Settings dialog. Output with fewer lines can be squeezed by +right clicking on the output. This can be useful lines long enough to slow +down scrolling. + +Squeezed output is expanded in place by double-clicking the label. +It can also be sent to the clipboard or a separate view window by +right-clicking the label. + Developing tkinter applications ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Lib/idlelib/help.html b/Lib/idlelib/help.html index 1cd9b69..83bd4a1 100644 --- a/Lib/idlelib/help.html +++ b/Lib/idlelib/help.html @@ -501,8 +501,14 @@ or immediately run an existing file before editing.

Python Shell window

-

The editing features described above work when entering code interactively. -IDLE’s Shell window also responds to the following keys.

+

With IDLE’s Shell, one enters, edits, and recalls complete statements. +Most consoles and terminals only work with a single physical line at a time.

+

When one pastes code into Shell, it is not compiled and possibly executed +until one hits Return. One may edit pasted code first. +If one pastes more that one statement into Shell, the result will be a +SyntaxError when multiple statements are compiled as if they were one.

+

The editing features described in previous subsections work when entering +code interactively. IDLE’s Shell window also responds to the following keys.

-

Shell has a special facility for squeezing output lines down to a -‘Squeezed text’ label. This is done automatically for output over N lines -(N = 50 by default). N can be changed in the PyShell section of the General -page of the Settings dialog. Output with fewer lines can be squeezed by -right clicking on the output. This can be useful for extra long lines.

-

Squeezed output is expanded in place by double-clicking the label. -It can also be sent to the clipboard or a separate view window by -right-clicking the label.

Text colors

@@ -644,6 +642,38 @@ will then be attached to that window for input and output.

IDLE’s changes are lost and input from the keyboard and output to the screen will not work correctly.

+
+

User output in Shell

+

When a program outputs text, the result is determined by the +corresponding output device. When IDLE executes user code, sys.stdout +and sys.stderr are connected to the display area of IDLE’s Shell. Some of +its features are inherited from the underlying Tk Text widget. Others +are programmed additions.

+

Text widgets display a subset of Unicode, the Basic Multilingual Plane (BMP). +Which characters get a proper glyph instead of a replacement box depends on +the operating system and installed fonts. Newline characters cause following +text to appear on a new line, but other control characters are replaced +with a box. But note that the repr() function, which is used for +interactive echo of expression values, replaces control characters +with escape codes before they are output.

+

Normal and error output are generally kept separate (on separate lines) +from code input and each other. They each get different highlight colors.

+

For SyntaxError tracebacks, the normal ‘^’ marking where the error was +detected is replaced by coloring the text with an error highlight. +When code run from a file causes other exceptions, one may right click +on a traceback line to jump to the corresponding line in an IDLE editor. +The file will be opened if necessary.

+

Shell has a special facility for squeezing output lines down to a +‘Squeezed text’ label. This is done automatically +for output over N lines (N = 50 by default). +N can be changed in the PyShell section of the General +page of the Settings dialog. Output with fewer lines can be squeezed by +right clicking on the output. This can be useful lines long enough to slow +down scrolling.

+

Squeezed output is expanded in place by double-clicking the label. +It can also be sent to the clipboard or a separate view window by +right-clicking the label.

+

Developing tkinter applications

IDLE is intentionally different from standard Python in order to @@ -763,6 +793,7 @@ also used for testing.

  • Command line usage
  • Startup failure
  • Running user code
    • +
  • User output in Shell
  • Developing tkinter applications
  • Running without a subprocess
    • @@ -851,7 +882,7 @@ also used for testing.



    - Last updated on Nov 05, 2018. + Last updated on Nov 06, 2018. Found a bug?
    diff --git a/Misc/NEWS.d/next/IDLE/2018-11-05-23-23-00.bpo-23220.H3SAWE.rst b/Misc/NEWS.d/next/IDLE/2018-11-05-23-23-00.bpo-23220.H3SAWE.rst new file mode 100644 index 0000000..77c7126 --- /dev/null +++ b/Misc/NEWS.d/next/IDLE/2018-11-05-23-23-00.bpo-23220.H3SAWE.rst @@ -0,0 +1 @@ +Explain how IDLE's Shell displays output. -- cgit v0.12