Skip to content

bpo-37765: Add keywords to IDLE tab completions #15138

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
terryjreedy merged 12 commits into from
Jul 9, 2020
Merged

bpo-37765: Add keywords to IDLE tab completions #15138

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
15b9ba0
bpo-37765: Add keywords to IDLE's main completion list
terryjreedy Aug 5, 2019
e8e0dfa
Merge remote-tracking branch 'upstream/master' into c_keyword
terryjreedy Jul 7, 2020
76053bf
News item.
terryjreedy Jul 7, 2020
8d53070
Filter keywords by length and previous inclusion.
terryjreedy Jul 7, 2020
561a52a
Revise completions doc.
terryjreedy Jul 8, 2020
31b2fc3
that lists
terryjreedy Jul 8, 2020
f8a8cad
Add date directive.
terryjreedy Jul 9, 2020
b898ac0
Merge remote-tracking branch 'upstream/master' into c_keyword
terryjreedy Jul 9, 2020
ee2450b
Revise news item.
terryjreedy Jul 9, 2020
061d96b
Include all keywords.
terryjreedy Jul 9, 2020
f4fe920
Revise revised text.
terryjreedy Jul 9, 2020
526db49
Update idle.rst
terryjreedy Jul 9, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 37 additions & 42 deletions Doc/library/idle.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -469,52 +469,47 @@ 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.
When available, completions are supplied for filenames and for
attributes of modules, classes, and functions. This is usually done
Comment thread
terryjreedy marked this conversation as resolved.
Outdated
by displaying a completion box listing existing names. The name
Comment thread
terryjreedy marked this conversation as resolved.
Outdated
being completed and the item highlighted in the box can be changed by
adding and deleting characters, with Up, Down, Page Up, Page Down, Home
and End keys, and by a single click within the box. Keys <Escape>,
Copy link
Copy Markdown
Contributor

@csabella csabella Jul 8, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here you mention keys without enclosing them in brackets, but in the next line you enclose the keys in brackets. You also use the :kbd: directive below. Was there a reason for using different styles?

Copy link
Copy Markdown
Member Author

@terryjreedy terryjreedy Jul 9, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was consistent within sentences ;-). Habit and history. The directive translates to <kbd class="kbd docutils literal notranslate">Backspace</kbd>. In my Firefox, this displays a slightly bold sans serif. The contrast with normal text depends on whether normal text has serifs or not, and with styling turned on, it does not. In help.py, the kbd tag is not translated, so no contrast. We should revise that to 'em' (currently italics) or a new tk 'bd' tag.

<Enter>, and double <Tab> and clicks outside the box close the box.
Copy link
Copy Markdown
Contributor

@csabella csabella Jul 8, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think 'close the box' is the point of this sentence, but it gets lost. It might be clearer to start with that. Or, alternatively, to reformat this paragraph somehow as a navigation section with bullets or subsections. Something like

Open the completion list:
Get new completions:
Select a completion:
Close the box:

Copy link
Copy Markdown
Member Author

@terryjreedy terryjreedy Jul 9, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I revised to "Close the box with ...", parallel to previous sentence. As to structure, we have a 3 dimensions: Open method (wait, hot key, tab), namespace (main, attribute, files), and stage (open select, close), with some cells blank (wait never opens the main namespace) and some entries identical. The existing order made little sense to me. I started with select and close because these are common to all open methods and lists. I made this more explicit. I follow with the 3 invocation methods and module level completions.

In any case, there are more edits all through the doc and a will wait a day for more comments before merging.

A double click within the box selects and closes.

An attribute completion box will automatically open, if any completions
are available, if one types '.' and waits for a predefined
delay. The delay defaults to 2 seconds and can be set in the settings
dialog. If one types os.sep or os.altsep in a string and waits,
Comment thread
terryjreedy marked this conversation as resolved.
Outdated
a completion box opens with filenames in the current directory.
Typing a separator after a directory name changes the list to that
directory. To prevent auto popups, set the delay to a large number of
milliseconds, such as 100000000.

One can try to directly open a completion box 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 is displayed. This is the same as if one enters a prefix
after the box is displayed. The same is usually true if one hits
<Tab>. However, if there is only one match to an existing prefix,
it is immediately added to the editor text without opening a box.

'Show Completions' outside of a string and without a preceding '.'
opens a box with keywords at least 5 letters long, all builtin names,
and available module-level names. When editing code in an editor
(as oppose to Shell), the latter can be updated by running your code
and not restarting the Shell thereafter. This is especially useful
after adding imports at the top of a file.

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:

Expand Down
2 changes: 2 additions & 0 deletions Lib/idlelib/NEWS.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ Released on 2020-10-05?
======================================


bpo-37765: Add longer keywords (len >= 5) to tab completion list.

bpo-41152: The encoding of ``stdin``, ``stdout`` and ``stderr`` in IDLE
is now always UTF-8.

Expand Down
6 changes: 5 additions & 1 deletion Lib/idlelib/autocomplete.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
pop up a list of candidates.
"""
import __main__
import keyword
import os
import string
import sys
Expand Down Expand Up @@ -171,10 +172,13 @@ def fetch_completions(self, what, mode):
(what, mode), {})
else:
if mode == ATTRS:
if what == "":
if what == "": # Main module names.
namespace = {**__main__.__builtins__.__dict__,
**__main__.__dict__}
bigl = eval("dir()", namespace)
key5 = (s for s in keyword.kwlist
if len(s) >= 5 and s != 'False')
bigl.extend(key5)
bigl.sort()
if "__all__" in bigl:
smalll = sorted(eval("__all__", namespace))
Expand Down
76 changes: 38 additions & 38 deletions Lib/idlelib/help.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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" />

Expand All @@ -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" />
Expand Down Expand Up @@ -71,7 +71,7 @@ <h3>Navigation</h3>


<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>
Expand Down Expand Up @@ -201,7 +201,7 @@ <h3>Edit menu (Shell and Editor)<a class="headerlink" href="#edit-menu-shell-and
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;
Expand Down Expand Up @@ -465,38 +465,38 @@ <h3>Automatic indentation<a class="headerlink" href="#automatic-indentation" tit
</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>When available, completions are supplied for filenames and for
attributes of modules, classes, and functions. This is usually done
by displaying a completion box listing existing names. The name
being completed and the item highlighted in the box can be changed by
adding and deleting characters, with Up, Down, Page Up, Page Down, Home
and End keys, and by a single click within the box. Keys &lt;Escape&gt;,
&lt;Enter&gt;, and double &lt;Tab&gt; and clicks outside the box close the box.
A double click within the box selects and closes.</p>
<p>An attribute completion box will automatically open, if any completions
are available, if one types ‘.’ and waits for a predefined
delay. The delay defaults to 2 seconds and can be set in the settings
dialog. If one types os.sep or os.altsep in a string and waits,
a completion box opens with filenames in the current directory.
Typing a separator after a directory name changes the list to that
directory. To prevent auto popups, set the delay to a large number of
milliseconds, such as 100000000.</p>
<p>One can try to directly open a completion box 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. This is the same as if one enters a prefix
after the box is displayed. The same is usually true if one hits
&lt;Tab&gt;. However, if there is only one match to an existing prefix,
it is immediately added to the editor text without opening a box.</p>
<p>‘Show Completions’ outside of a string and without a preceding ‘.’
opens a box with keywords at least 5 letters long, all builtin names,
and available module-level names. When editing code in an editor
(as oppose to Shell), the latter can be updated by running your code
and not restarting the Shell thereafter. This is especially useful
after adding imports at the top of a file.</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>
Expand Down Expand Up @@ -935,7 +935,7 @@ <h3>Navigation</h3>


<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>
Expand Down Expand Up @@ -966,7 +966,7 @@ <h3>Navigation</h3>
<br />
<br />

Last updated on Mar 07, 2020.
Last updated on Jul 07, 2020.
<a href="https://docs.python.org/3/bugs.html">Found a bug</a>?
<br />

Expand Down
8 changes: 6 additions & 2 deletions Lib/idlelib/idle_test/test_autocomplete.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -240,8 +240,12 @@ def test_fetch_completions(self):
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.assertNotIn('pass', b) # Exclude keywords <= 4.
self.assertIn('async', b) # Include keywords >= 5.
pos = b.index('False') # Test False not included twice.
self.assertNotEqual(b[pos+1], 'False')

# Test attributes with name entity.
mock = Mock()
Expand Down
1 change: 1 addition & 0 deletions Misc/NEWS.d/next/IDLE/2020-07-07-18-44-30.bpo-37765.umc1o8.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Add longer keywords (len >= 5) to tab completion list.