bpo-37765: Add keywords to IDLE tab completions (GH-15138)

Keywords are present in the main module tab completion lists generated by rlcompleter, which is used by REPLs on *nix. Add all keywords to IDLE's main module name list except those already added from builtins (True, False, and None) . This list may also be used by Show Completions on the Edit menu, and its hot key.

Rewrite Completions doc.

Co-authored-by: Cheryl Sabella <cheryl.sabella@gmail.com>

6 files changed, 110 insertions, 83 deletions

diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst
index b1192e7bb46..75b6fa3861b 100644
--- a/Doc/library/idle.rst
+++ b/Doc/library/idle.rst
@@ -147,7 +147,7 @@ Go to Line
    Clear any selection and update the line and column status.
 
 Show Completions
-   Open a scrollable list allowing selection of keywords and attributes. See
+   Open a scrollable list allowing selection of existing names. See
    :ref:`Completions <completions>` in the Editing and navigation section below.
 
 Expand Word
@@ -469,52 +469,58 @@ are restricted to four spaces due to Tcl/Tk limitations.
 See also the indent/dedent region commands on the
 :ref:`Format menu <format-menu>`.
 
-
 .. _completions:
 
 Completions
 ^^^^^^^^^^^
 
-Completions are supplied for functions, classes, and attributes of classes,
-both built-in and user-defined. Completions are also provided for
-filenames.
-
-The AutoCompleteWindow (ACW) will open after a predefined delay (default is
-two seconds) after a '.' or (in a string) an os.sep is typed. If after one
-of those characters (plus zero or more other characters) a tab is typed
-the ACW will open immediately if a possible continuation is found.
-
-If there is only one possible completion for the characters entered, a
-:kbd:`Tab` will supply that completion without opening the ACW.
-
-'Show Completions' will force open a completions window, by default the
-:kbd:`C-space` will open a completions window. In an empty
-string, this will contain the files in the current directory. On a
-blank line, it will contain the built-in and user-defined functions and
-classes in the current namespaces, plus any modules imported. If some
-characters have been entered, the ACW will attempt to be more specific.
-
-If a string of characters is typed, the ACW selection will jump to the
-entry most closely matching those characters.  Entering a :kbd:`tab` will
-cause the longest non-ambiguous match to be entered in the Editor window or
-Shell.  Two :kbd:`tab` in a row will supply the current ACW selection, as
-will return or a double click.  Cursor keys, Page Up/Down, mouse selection,
-and the scroll wheel all operate on the ACW.
-
-"Hidden" attributes can be accessed by typing the beginning of hidden
-name after a '.', e.g. '_'. This allows access to modules with
-``__all__`` set, or to class-private attributes.
-
-Completions and the 'Expand Word' facility can save a lot of typing!
-
-Completions are currently limited to those in the namespaces. Names in
-an Editor window which are not via ``__main__`` and :data:`sys.modules` will
-not be found.  Run the module once with your imports to correct this situation.
-Note that IDLE itself places quite a few modules in sys.modules, so
-much can be found by default, e.g. the re module.
-
-If you don't like the ACW popping up unbidden, simply make the delay
-longer or disable the extension.
+Completions are supplied, when requested and available, for module
+names, attributes of classes or functions, or filenames.  Each request
+method displays a completion box with existing names.  (See tab
+completions below for an exception.) For any box, change the name
+being completed and the item highlighted in the box by
+typing and deleting characters; by hitting :kbd:`Up`, :kbd:`Down`,
+:kbd:`PageUp`, :kbd:`PageDown`, :kbd:`Home`, and :kbd:`End` keys;
+and by a single click within the box.  Close the box with :kbd:`Escape`,
+:kbd:`Enter`, and double :kbd:`Tab` keys or clicks outside the box.
+A double click within the box selects and closes.
+
+One way to open a box is to type a key character and wait for a
+predefined interval.  This defaults to 2 seconds; customize it
+in the settings dialog.  (To prevent auto popups, set the delay to a
+large number of milliseconds, such as 100000000.) For imported module
+names or class or function attributes, type '.'.
+For filenames in the root directory, type :data:`os.sep` or
+data:`os.altsep` immediately after an opening quote.  (On Windows,
+one can specify a drive first.)  Move into subdirectories by typing a
+directory name and a separator.
+
+Instead of waiting, or after a box is closed, open a completion box
+immediately with Show Completions on the Edit menu.  The default hot
+key is :kbd:`C-space`.  If one types a prefix for the desired name
+before opening the box, the first match or near miss is made visible.
+The result is the same as if one enters a prefix
+after the box is displayed.  Show Completions after a quote completes
+filenames in the current directory instead of a root directory.
+
+Hitting :kbd:`Tab` after a prefix usually has the same effect as Show
+Completions.  (With no prefix, it indents.)  However, if there is only
+one match to the prefix, that match is immediately added to the editor
+text without opening a box.
+
+Invoking 'Show Completions', or hitting :kbd:`Tab` after a prefix,
+outside of a string and without a preceding '.' opens a box with
+keywords, builtin names, and available module-level names.
+
+When editing code in an editor (as oppose to Shell), increase the
+available module-level names by running your code
+and not restarting the Shell thereafter.  This is especially useful
+after adding imports at the top of a file.  This also increases
+possible attribute completions.
+
+Completion boxes intially exclude names beginning with '_' or, for
+modules, not included in '__all__'.  The hidden names can be accessed
+by typing '_' after '.', either before or after the box is opened.
 
 .. _calltips:
 
diff --git a/Lib/idlelib/NEWS.txt b/Lib/idlelib/NEWS.txt
index 7ae29af0b30..1c5c03da86e 100644
--- a/Lib/idlelib/NEWS.txt
+++ b/Lib/idlelib/NEWS.txt
@@ -3,6 +3,9 @@ Released on 2020-10-05?
 ======================================
 
 
+bpo-37765: Add keywords to module name completion list.  Rewrite
+Completions section of IDLE doc.
+
 bpo-41152: The encoding of ``stdin``, ``stdout`` and ``stderr`` in IDLE
 is now always UTF-8.
 
diff --git a/Lib/idlelib/autocomplete.py b/Lib/idlelib/autocomplete.py
index c623d45a153..e1e9e17311e 100644
--- a/Lib/idlelib/autocomplete.py
+++ b/Lib/idlelib/autocomplete.py
@@ -4,6 +4,7 @@ Either on demand or after a user-selected delay after a key character,
 pop up a list of candidates.
 """
 import __main__
+import keyword
 import os
 import string
 import sys
@@ -171,10 +172,13 @@ class AutoComplete:
                                      (what, mode), {})
         else:
             if mode == ATTRS:
-                if what == "":
+                if what == "":  # Main module names.
                     namespace = {**__main__.__builtins__.__dict__,
                                  **__main__.__dict__}
                     bigl = eval("dir()", namespace)
+                    kwds = (s for s in keyword.kwlist
+                            if s not in {'True', 'False', 'None'})
+                    bigl.extend(kwds)
                     bigl.sort()
                     if "__all__" in bigl:
                         smalll = sorted(eval("__all__", namespace))
diff --git a/Lib/idlelib/help.html b/Lib/idlelib/help.html
index 424c6b50f33..81ce5100bb8 100644
--- a/Lib/idlelib/help.html
+++ b/Lib/idlelib/help.html
@@ -4,7 +4,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml">
   <head>
     <meta charset="utf-8" />
-    <title>IDLE &#8212; Python 3.9.0a4 documentation</title>
+    <title>IDLE &#8212; Python 3.10.0a0 documentation</title>
     <link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
     <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
 
@@ -17,7 +17,7 @@
     <script type="text/javascript" src="../_static/sidebar.js"></script>
 
     <link rel="search" type="application/opensearchdescription+xml"
-          title="Search within Python 3.9.0a4 documentation"
+          title="Search within Python 3.10.0a0 documentation"
           href="../_static/opensearch.xml"/>
     <link rel="author" title="About these documents" href="../about.html" />
     <link rel="index" title="Index" href="../genindex.html" />
@@ -71,7 +71,7 @@
 
 
     <li>
-      <a href="../index.html">3.9.0a4 Documentation</a> &#187;
+      <a href="../index.html">3.10.0a0 Documentation</a> &#187;
     </li>
 
           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>
@@ -201,7 +201,7 @@ be undone.</p>
 line visible.  A request past the end of the file goes to the end.
 Clear any selection and update the line and column status.</p>
 </dd>
-<dt>Show Completions</dt><dd><p>Open a scrollable list allowing selection of keywords and attributes. See
+<dt>Show Completions</dt><dd><p>Open a scrollable list allowing selection of existing names. See
 <a class="reference internal" href="#completions"><span class="std std-ref">Completions</span></a> in the Editing and navigation section below.</p>
 </dd>
 <dt>Expand Word</dt><dd><p>Expand a prefix you have typed to match a full word in the same window;
@@ -465,38 +465,47 @@ are restricted to four spaces due to Tcl/Tk limitations.</p>
 </div>
 <div class="section" id="completions">
 <span id="id3"></span><h3>Completions<a class="headerlink" href="#completions" title="Permalink to this headline">¶</a></h3>
-<p>Completions are supplied for functions, classes, and attributes of classes,
-both built-in and user-defined. Completions are also provided for
-filenames.</p>
-<p>The AutoCompleteWindow (ACW) will open after a predefined delay (default is
-two seconds) after a ‘.’ or (in a string) an os.sep is typed. If after one
-of those characters (plus zero or more other characters) a tab is typed
-the ACW will open immediately if a possible continuation is found.</p>
-<p>If there is only one possible completion for the characters entered, a
-<kbd class="kbd docutils literal notranslate">Tab</kbd> will supply that completion without opening the ACW.</p>
-<p>‘Show Completions’ will force open a completions window, by default the
-<kbd class="kbd docutils literal notranslate">C-space</kbd> will open a completions window. In an empty
-string, this will contain the files in the current directory. On a
-blank line, it will contain the built-in and user-defined functions and
-classes in the current namespaces, plus any modules imported. If some
-characters have been entered, the ACW will attempt to be more specific.</p>
-<p>If a string of characters is typed, the ACW selection will jump to the
-entry most closely matching those characters.  Entering a <kbd class="kbd docutils literal notranslate">tab</kbd> will
-cause the longest non-ambiguous match to be entered in the Editor window or
-Shell.  Two <kbd class="kbd docutils literal notranslate">tab</kbd> in a row will supply the current ACW selection, as
-will return or a double click.  Cursor keys, Page Up/Down, mouse selection,
-and the scroll wheel all operate on the ACW.</p>
-<p>“Hidden” attributes can be accessed by typing the beginning of hidden
-name after a ‘.’, e.g. ‘_’. This allows access to modules with
-<code class="docutils literal notranslate"><span class="pre">__all__</span></code> set, or to class-private attributes.</p>
-<p>Completions and the ‘Expand Word’ facility can save a lot of typing!</p>
-<p>Completions are currently limited to those in the namespaces. Names in
-an Editor window which are not via <code class="docutils literal notranslate"><span class="pre">__main__</span></code> and <a class="reference internal" href="sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a> will
-not be found.  Run the module once with your imports to correct this situation.
-Note that IDLE itself places quite a few modules in sys.modules, so
-much can be found by default, e.g. the re module.</p>
-<p>If you don’t like the ACW popping up unbidden, simply make the delay
-longer or disable the extension.</p>
+<p>Completions are supplied, when requested and available, for module
+names, attributes of classes or functions, or filenames.  Each request
+method displays a completion box with existing names.  (See tab
+completions below for an exception.) For any box, change the name
+being completed and the item highlighted in the box by
+typing and deleting characters; by hitting <kbd class="kbd docutils literal notranslate">Up</kbd>, <kbd class="kbd docutils literal notranslate">Down</kbd>,
+<kbd class="kbd docutils literal notranslate">PageUp</kbd>, <kbd class="kbd docutils literal notranslate">PageDown</kbd>, <kbd class="kbd docutils literal notranslate">Home</kbd>, and <kbd class="kbd docutils literal notranslate">End</kbd> keys;
+and by a single click within the box.  Close the box with <kbd class="kbd docutils literal notranslate">Escape</kbd>,
+<kbd class="kbd docutils literal notranslate">Enter</kbd>, and double <kbd class="kbd docutils literal notranslate">Tab</kbd> keys or clicks outside the box.
+A double click within the box selects and closes.</p>
+<p>One way to open a box is to type a key character and wait for a
+predefined interval.  This defaults to 2 seconds; customize it
+in the settings dialog.  (To prevent auto popups, set the delay to a
+large number of milliseconds, such as 100000000.) For imported module
+names or class or function attributes, type ‘.’.
+For filenames in the root directory, type <a class="reference internal" href="os.html#os.sep" title="os.sep"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.sep</span></code></a> or
+data:<cite>os.altsep</cite> immediately after an opening quote.  (On Windows,
+one can specify a drive first.)  Move into subdirectories by typing a
+directory name and a separator.</p>
+<p>Instead of waiting, or after a box is closed. open a completion box
+immediately with Show Completions on the Edit menu.  The default hot
+key is <kbd class="kbd docutils literal notranslate">C-space</kbd>.  If one types a prefix for the desired name
+before opening the box, the first match is displayed.
+The result is the same as if one enters a prefix
+after the box is displayed.  Show Completions after a quote completes
+filenames in the current directory instead of a root directory.</p>
+<p>Hitting <kbd class="kbd docutils literal notranslate">Tab</kbd> after a prefix usually has the same effect as Show
+Completions.  (With no prefix, it indents.)  However, if there is only
+one match to the prefix, that match is immediately added to the editor
+text without opening a box.</p>
+<p>Invoking ‘Show Completions’, or hitting <kbd class="kbd docutils literal notranslate">Tab</kbd> after a prefix,
+outside of a string and without a preceding ‘.’ opens a box with
+keywords, builtin names, and available module-level names.</p>
+<p>When editing code in an editor (as oppose to Shell), increase the
+available module-level names by running your code
+and not restarting the Shell thereafter.  This is especially useful
+after adding imports at the top of a file.  This also increases
+possible attribute completions.</p>
+<p>Completion boxes intially exclude names beginning with ‘_’ or, for
+modules, not included in ‘__all__’.  The hidden names can be accessed
+by typing ‘_’ after ‘.’, either before or after the box is opened.</p>
 </div>
 <div class="section" id="calltips">
 <span id="id4"></span><h3>Calltips<a class="headerlink" href="#calltips" title="Permalink to this headline">¶</a></h3>
@@ -935,7 +944,7 @@ also used for testing.</p>
 
 
     <li>
-      <a href="../index.html">3.9.0a4 Documentation</a> &#187;
+      <a href="../index.html">3.10.0a0 Documentation</a> &#187;
     </li>
 
           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>
@@ -966,7 +975,7 @@ also used for testing.</p>
 <br />
     <br />
 
-    Last updated on Mar 07, 2020.
+    Last updated on Jul 08, 2020.
     <a href="https://docs.python.org/3/bugs.html">Found a bug</a>?
     <br />
 
diff --git a/Lib/idlelib/idle_test/test_autocomplete.py b/Lib/idlelib/idle_test/test_autocomplete.py
index 1841495fcf1..9c113bd893f 100644
--- a/Lib/idlelib/idle_test/test_autocomplete.py
+++ b/Lib/idlelib/idle_test/test_autocomplete.py
@@ -240,8 +240,11 @@ class AutoCompleteTest(unittest.TestCase):
         with patch.dict('__main__.__dict__', {'__all__': ['a', 'b']}):
             s, b = acp.fetch_completions('', ac.ATTRS)
             self.assertEqual(s, ['a', 'b'])
-            self.assertIn('__name__', b)    # From __main__.__dict__
-            self.assertIn('sum', b)         # From __main__.__builtins__.__dict__
+            self.assertIn('__name__', b)  # From __main__.__dict__.
+            self.assertIn('sum', b)       # From __main__.__builtins__.__dict__.
+            self.assertIn('nonlocal', b)  # From keyword.kwlist.
+            pos = b.index('False')        # Test False not included twice.
+            self.assertNotEqual(b[pos+1], 'False')
 
         # Test attributes with name entity.
         mock = Mock()
diff --git a/Misc/NEWS.d/next/IDLE/2020-07-07-18-44-30.bpo-37765.umc1o8.rst b/Misc/NEWS.d/next/IDLE/2020-07-07-18-44-30.bpo-37765.umc1o8.rst
new file mode 100644
index 00000000000..f8b53ca482a
--- /dev/null
+++ b/Misc/NEWS.d/next/IDLE/2020-07-07-18-44-30.bpo-37765.umc1o8.rst
@@ -0,0 +1,2 @@
+Add keywords to module name completion list.  Rewrite Completions
+section of IDLE doc.