From 5d46ab1274232d51060ba2e45e6c345ef4e5b970 Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Sun, 20 Sep 2015 19:57:13 -0400 Subject: [PATCH] Issue #16893: Replace help.txt with idle.html for Idle doc display. The new idlelib/idle.html is copied from Doc/build/html/idle.html. It looks better than help.txt and will better document Idle as released. The tkinter html viewer that works for this file was written by Rose Roseman. The new code is in idlelib/help.py, a new file for help menu classes. The now unused EditorWindow.HelpDialog class and helt.txt file are deprecated. --- Lib/idlelib/EditorWindow.py | 12 +- Lib/idlelib/help.py | 233 ++++++++++++ Lib/idlelib/help.txt | 4 + Lib/idlelib/idle.html | 671 +++++++++++++++++++++++++++++++++ Lib/idlelib/idle_test/htest.py | 14 +- Lib/idlelib/macosxSupport.py | 5 +- 6 files changed, 927 insertions(+), 12 deletions(-) create mode 100644 Lib/idlelib/help.py create mode 100644 Lib/idlelib/idle.html diff --git a/Lib/idlelib/EditorWindow.py b/Lib/idlelib/EditorWindow.py index 3ac68bbaf24..09f2b28657d 100644 --- a/Lib/idlelib/EditorWindow.py +++ b/Lib/idlelib/EditorWindow.py @@ -21,6 +21,7 @@ from idlelib import PyParse from idlelib.configHandler import idleConf from idlelib import aboutDialog, textView, configDialog from idlelib import macosxSupport +from idlelib import help # The default tab setting for a Text widget, in average-width characters. TK_TABWIDTH_DEFAULT = 8 @@ -42,6 +43,11 @@ def _sphinx_version(): class HelpDialog(object): def __init__(self): + import warnings as w + w.warn("EditorWindow.HelpDialog is no longer used by Idle.\n" + "It will be removed in 3.6 or later.\n" + "It has been replaced by private help.HelpWindow\n", + DeprecationWarning, stacklevel=2) self.parent = None # parent of help window self.dlg = None # the help window iteself @@ -539,11 +545,13 @@ class EditorWindow(object): configDialog.ConfigExtensionsDialog(self.top) def help_dialog(self, event=None): + "Handle help doc event." + # edit maxosxSupport.overrideRootMenu.help_dialog to match if self.root: parent = self.root else: parent = self.top - helpDialog.display(parent, near=self.top) + help.show_idlehelp(parent) def python_docs(self, event=None): if sys.platform[:3] == 'win': @@ -1716,4 +1724,4 @@ def _editor_window(parent): # htest # if __name__ == '__main__': from idlelib.idle_test.htest import run - run(_help_dialog, _editor_window) + run(_editor_window) diff --git a/Lib/idlelib/help.py b/Lib/idlelib/help.py new file mode 100644 index 00000000000..b1047c87564 --- /dev/null +++ b/Lib/idlelib/help.py @@ -0,0 +1,233 @@ +""" +help.py implements the Idle help menu and is subject to change. + +The contents are subject to revision at any time, without notice. + +Help => About IDLE: diplay About Idle dialog + + + +Help => IDLE Help: display idle.html with proper formatting + +HelpParser - Parses idle.html generated from idle.rst by Sphinx +and renders to tk Text. + +HelpText - Displays formatted idle.html. + +HelpFrame - Contains text, scrollbar, and table-of-contents. +(This will be needed for display in a future tabbed window.) + +HelpWindow - Display idleframe in a standalone window. + +show_idlehelp - Create HelpWindow. Called in EditorWindow.help_dialog. +""" +from html.parser import HTMLParser +from os.path import abspath, dirname, isdir, isfile, join +from tkinter import Tk, Toplevel, Frame, Text, Scrollbar, Menu, Menubutton +from tkinter import font as tkfont + +use_ttk = False # until available to import +if use_ttk: + from tkinter.ttk import Menubutton + +## About IDLE ## + + +## IDLE Help ## + +class HelpParser(HTMLParser): + """Render idle.html generated by Sphinx from idle.rst. + + The overridden handle_xyz methods handle a subset of html tags. + The supplied text should have the needed tag configurations. + The behavior for unsupported tags, such as table, is undefined. + """ + def __init__(self, text): + HTMLParser.__init__(self, convert_charrefs=True) + self.text = text # text widget we're rendering into + self.tags = '' # current text tags to apply + self.show = False # used so we exclude page navigation + self.hdrlink = False # used so we don't show header links + self.level = 0 # indentation level + self.pre = False # displaying preformatted text + self.hprefix = '' # strip e.g. '25.5' from headings + self.nested_dl = False # if we're in a nested
+ self.simplelist = False # simple list (no double spacing) + self.tocid = 1 # id for table of contents entries + self.contents = [] # map toc ids to section titles + self.data = '' # to record data within header tags for toc + + def indent(self, amt=1): + self.level += amt + self.tags = '' if self.level == 0 else 'l'+str(self.level) + + def handle_starttag(self, tag, attrs): + "Handle starttags in idle.html." + class_ = '' + for a, v in attrs: + if a == 'class': + class_ = v + s = '' + if tag == 'div' and class_ == 'section': + self.show = True # start of main content + elif tag == 'div' and class_ == 'sphinxsidebar': + self.show = False # end of main content + elif tag == 'p' and class_ != 'first': + s = '\n\n' + elif tag == 'span' and class_ == 'pre': + self.tags = 'pre' + elif tag == 'span' and class_ == 'versionmodified': + self.tags = 'em' + elif tag == 'em': + self.tags = 'em' + elif tag in ['ul', 'ol']: + if class_.find('simple') != -1: + s = '\n' + self.simplelist = True + else: + self.simplelist = False + self.indent() + elif tag == 'dl': + if self.level > 0: + self.nested_dl = True + elif tag == 'li': + s = '\n* ' if self.simplelist else '\n\n* ' + elif tag == 'dt': + s = '\n\n' if not self.nested_dl else '\n' # avoid extra line + self.nested_dl = False + elif tag == 'dd': + self.indent() + s = '\n' + elif tag == 'pre': + self.pre = True + if self.show: + self.text.insert('end', '\n\n') + self.tags = 'preblock' + elif tag == 'a' and class_ == 'headerlink': + self.hdrlink = True + elif tag == 'h1': + self.text.mark_set('toc'+str(self.tocid), + self.text.index('end-1line')) + self.tags = tag + elif tag in ['h2', 'h3']: + if self.show: + self.data = '' + self.text.mark_set('toc'+str(self.tocid), + self.text.index('end-1line')) + self.text.insert('end', '\n\n') + self.tags = tag + if self.show: + self.text.insert('end', s, self.tags) + + def handle_endtag(self, tag): + "Handle endtags in idle.html." + if tag in ['h1', 'h2', 'h3', 'span', 'em']: + self.indent(0) # clear tag, reset indent + if self.show and tag in ['h1', 'h2', 'h3']: + title = self.data + self.contents.append(('toc'+str(self.tocid), title)) + self.tocid += 1 + elif tag == 'a': + self.hdrlink = False + elif tag == 'pre': + self.pre = False + self.tags = '' + elif tag in ['ul', 'dd', 'ol']: + self.indent(amt=-1) + + def handle_data(self, data): + "Handle date segments in idle.html." + if self.show and not self.hdrlink: + d = data if self.pre else data.replace('\n', ' ') + if self.tags == 'h1': + self.hprefix = d[0:d.index(' ')] + if self.tags in ['h1', 'h2', 'h3'] and self.hprefix != '': + if d[0:len(self.hprefix)] == self.hprefix: + d = d[len(self.hprefix):].strip() + self.data += d + self.text.insert('end', d, self.tags) + + +class HelpText(Text): + "Display idle.html." + def __init__(self, parent, filename): + "Configure tags and feed file to parser." + Text.__init__(self, parent, wrap='word', highlightthickness=0, + padx=5, borderwidth=0) + + normalfont = self.findfont(['TkDefaultFont', 'arial', 'helvetica']) + fixedfont = self.findfont(['TkFixedFont', 'monaco', 'courier']) + self['font'] = (normalfont, 12) + self.tag_configure('em', font=(normalfont, 12, 'italic')) + self.tag_configure('h1', font=(normalfont, 20, 'bold')) + self.tag_configure('h2', font=(normalfont, 18, 'bold')) + self.tag_configure('h3', font=(normalfont, 15, 'bold')) + self.tag_configure('pre', font=(fixedfont, 12)) + self.tag_configure('preblock', font=(fixedfont, 10), lmargin1=25, + borderwidth=1, relief='solid', background='#eeffcc') + self.tag_configure('l1', lmargin1=25, lmargin2=25) + self.tag_configure('l2', lmargin1=50, lmargin2=50) + self.tag_configure('l3', lmargin1=75, lmargin2=75) + self.tag_configure('l4', lmargin1=100, lmargin2=100) + + self.parser = HelpParser(self) + with open(filename, encoding='utf-8') as f: + contents = f.read() + self.parser.feed(contents) + self['state'] = 'disabled' + + def findfont(self, names): + "Return name of first font family derived from names." + for name in names: + if name.lower() in (x.lower() for x in tkfont.names(root=self)): + font = tkfont.Font(name=name, exists=True, root=self) + return font.actual()['family'] + elif name.lower() in (x.lower() + for x in tkfont.families(root=self)): + return name + + +class HelpFrame(Frame): + def __init__(self, parent, filename): + Frame.__init__(self, parent) + text = HelpText(self, filename) + self['background'] = text['background'] + scroll = Scrollbar(self, command=text.yview) + text['yscrollcommand'] = scroll.set + text.grid(column=1, row=0, sticky='nsew') + scroll.grid(column=2, row=0, sticky='ns') + self.grid_columnconfigure(1, weight=1) + self.grid_rowconfigure(0, weight=1) + toc = self.contents_widget(text) + toc.grid(column=0, row=0, sticky='nw') + + def contents_widget(self, text): + toc = Menubutton(self, text='TOC') + drop = Menu(toc, tearoff=False) + for tag, lbl in text.parser.contents: + drop.add_command(label=lbl, command=lambda mark=tag:text.see(mark)) + toc['menu'] = drop + return toc + + +class HelpWindow(Toplevel): + + def __init__(self, parent, filename, title): + Toplevel.__init__(self, parent) + self.wm_title(title) + self.protocol("WM_DELETE_WINDOW", self.destroy) + HelpFrame(self, filename).grid(column=0, row=0, sticky='nsew') + self.grid_columnconfigure(0, weight=1) + self.grid_rowconfigure(0, weight=1) + + +def show_idlehelp(parent): + filename = join(abspath(dirname(__file__)), 'idle.html') + if not isfile(filename): + dirpath = join(abspath(dirname(dirname(dirname(__file__)))), + 'Doc', 'build', 'html', 'library') + HelpWindow(parent, filename, 'IDLE Help') + +if __name__ == '__main__': + from idlelib.idle_test.htest import run + run(show_idlehelp) diff --git a/Lib/idlelib/help.txt b/Lib/idlelib/help.txt index 3f7bb23b619..89fbe0b41ec 100644 --- a/Lib/idlelib/help.txt +++ b/Lib/idlelib/help.txt @@ -1,3 +1,7 @@ +This file, idlelib/help.txt is out-of-date and no longer used by Idle. +It is deprecated and will be removed in the future, possibly in 3.6 +---------------------------------------------------------------------- + [See the end of this file for ** TIPS ** on using IDLE !!] IDLE is the Python IDE built with the tkinter GUI toolkit. diff --git a/Lib/idlelib/idle.html b/Lib/idlelib/idle.html new file mode 100644 index 00000000000..6e8d89bda09 --- /dev/null +++ b/Lib/idlelib/idle.html @@ -0,0 +1,671 @@ + + + + + + + + 25.5. IDLE — Python 3.4.3 documentation + + + + + + + + + + + + + + + + + + + + + + + + +
+

Navigation

+ +
+ +
+
+
+
+ +
+

25.5. IDLE

+

IDLE is the Python IDE built with the tkinter GUI toolkit.

+

IDLE has the following features:

+
    +
  • coded in 100% pure Python, using the tkinter GUI toolkit
    • +
  • cross-platform: works on Windows, Unix, and Mac OS X
    • +
  • multi-window text editor with multiple undo, Python colorizing, +smart indent, call tips, and many other features
    • +
  • Python shell window (a.k.a. interactive interpreter)
    • +
  • debugger (not complete, but you can set breakpoints, view and step)
    • +
+ +
+

25.5.2. Editing and navigation

+

In this section, ‘C’ refers to the Control key on Windows and Unix and +the Command key on Mac OSX.

+
    +

  • Backspace deletes to the left; Del deletes to the right

    +
    • +

  • C-Backspace delete word left; C-Del delete word to the right

    +
    • +

  • Arrow keys and Page Up/Page Down to move around

    +
    • +

  • C-LeftArrow and C-RightArrow moves by words

    +
    • +

  • Home/End go to begin/end of line

    +
    • +

  • C-Home/C-End go to begin/end of file

    +
    • +

  • Some useful Emacs bindings are inherited from Tcl/Tk:

    +
    +
      +
    • C-a beginning of line
      • +
    • C-e end of line
      • +
    • C-k kill line (but doesn’t put it in clipboard)
      • +
    • C-l center window around the insertion point
      • +
    • C-b go backwards one character without deleting (usually you can +also use the cursor key for this)
      • +
    • C-f go forward one character without deleting (usually you can +also use the cursor key for this)
      • +
    • C-p go up one line (usually you can also use the cursor key for +this)
      • +
    • C-d delete next character
      • +
    +
    +
    • +
+

Standard keybindings (like C-c to copy and C-v to paste) +may work. Keybindings are selected in the Configure IDLE dialog.

+
+

25.5.2.1. Automatic indentation

+

After a block-opening statement, the next line is indented by 4 spaces (in the +Python Shell window by one tab). After certain keywords (break, return etc.) +the next line is dedented. In leading indentation, Backspace deletes up +to 4 spaces if they are there. Tab inserts spaces (in the Python +Shell window one tab), number depends on Indent width. Currently tabs +are restricted to four spaces due to Tcl/Tk limitations.

+

See also the indent/dedent region commands in the edit menu.

+
+
+

25.5.2.2. 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 +Tab will supply that completion without opening the ACW.

+

‘Show Completions’ will force open a completions window, by default the +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 name spaces, 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 tab will +cause the longest non-ambiguous match to be entered in the Editor window or +Shell. Two 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 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. Or another option is the delay could +be set to zero. Another alternative to preventing ACW popups is to +disable the call tips extension.

+
+
+

25.5.2.3. Python Shell window

+
    +

  • C-c interrupts executing command

    +
    • +

  • C-d sends end-of-file; closes window if typed at a >>> prompt

    +
    • +

  • Alt-/ (Expand word) is also useful to reduce typing

    +

    Command history

    +
      +
    • Alt-p retrieves previous command matching what you have typed. On +OS X use C-p.
      • +
    • Alt-n retrieves next. On OS X use C-n.
      • +
    • Return while on any previous command retrieves that command
      • +
    +
    • +
+
+
+
+

25.5.3. Syntax colors

+

The coloring is applied in a background “thread,” so you may occasionally see +uncolorized text. To change the color scheme, edit the [Colors] section in +config.txt.

+
+
Python syntax colors:
+
+
Keywords
+
orange
+
Strings
+
green
+
Comments
+
red
+
Definitions
+
blue
+
+
+
Shell colors:
+
+
Console output
+
brown
+
stdout
+
blue
+
stderr
+
dark green
+
stdin
+
black
+
+
+
+
+
+

25.5.4. Startup

+

Upon startup with the -s option, IDLE will execute the file referenced by +the environment variables IDLESTARTUP or PYTHONSTARTUP. +IDLE first checks for IDLESTARTUP; if IDLESTARTUP is present the file +referenced is run. If IDLESTARTUP is not present, IDLE checks for +PYTHONSTARTUP. Files referenced by these environment variables are +convenient places to store functions that are used frequently from the IDLE +shell, or for executing import statements to import common modules.

+

In addition, Tk also loads a startup file if it is present. Note that the +Tk file is loaded unconditionally. This additional file is .Idle.py and is +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.

+
+

25.5.4.1. Command line usage

+
idle.py [-c command] [-d] [-e] [-s] [-t title] [arg] ...
+
+-c command  run this command
+-d          enable debugger
+-e          edit mode; arguments are files to be edited
+-s          run $IDLESTARTUP or $PYTHONSTARTUP first
+-t title    set title of shell window
+
+
+

If there are arguments:

+
    +
  1. If -e is used, arguments are files opened for editing and +sys.argv reflects the arguments passed to IDLE itself.
    2. +
  2. Otherwise, if -c is used, all arguments are placed in +sys.argv[1:...], with sys.argv[0] set to '-c'.
    3. +
  3. Otherwise, if neither -e nor -c is used, the first +argument is a script which is executed with the remaining arguments in +sys.argv[1:...] and sys.argv[0] set to the script name. If the +script name is ‘-‘, no script is executed but an interactive Python session +is started; the arguments are still available in sys.argv.
    4. +
+
+
+

25.5.4.2. Running without a subprocess

+

If IDLE is started with the -n command line switch it will run in a +single process and will not create the subprocess which runs the RPC +Python execution server. This can be useful if Python cannot create +the subprocess or the RPC socket interface on your platform. However, +in this mode user code is not isolated from IDLE itself. Also, the +environment is not restarted when Run/Run Module (F5) is selected. If +your code has been modified, you must reload() the affected modules and +re-import any specific items (e.g. from foo import baz) if the changes +are to take effect. For these reasons, it is preferable to run IDLE +with the default subprocess if at all possible.

+
+

Deprecated since version 3.4.

+
+
+
+
+

25.5.5. Help and preferences

+
+

25.5.5.1. Additional help sources

+

IDLE includes a help menu entry called “Python Docs” that will open the +extensive sources of help, including tutorials, available at docs.python.org. +Selected URLs can be added or removed from the help menu at any time using the +Configure IDLE dialog. See the IDLE help option in the help menu of IDLE for +more information.

+
+
+

25.5.5.2. Setting preferences

+

The font preferences, highlighting, keys, and general preferences can be +changed via Configure IDLE on the Option menu. Keys can be user defined; +IDLE ships with four built in key sets. In addition a user can create a +custom key set in the Configure IDLE dialog under the keys tab.

+
+
+

25.5.5.3. Extensions

+

IDLE contains an extension facility. Peferences for extensions can be +changed with Configure Extensions. See the beginning of config-extensions.def +in the idlelib directory for further information. The default extensions +are currently:

+
    +
  • FormatParagraph
    • +
  • AutoExpand
    • +
  • ZoomHeight
    • +
  • ScriptBinding
    • +
  • CallTips
    • +
  • ParenMatch
    • +
  • AutoComplete
    • +
  • CodeContext
    • +
  • RstripExtension
    • +
+
+
+
+ + +
+
+
+
+
+

Table Of Contents

+ + +

Previous topic

+

25.4. tkinter.scrolledtext — Scrolled Text Widget

+

Next topic

+

25.6. Other Graphical User Interface Packages

+

This Page

+ + + + +
+
+
+
+
+

Navigation

+ +
+
+ © Copyright 1990-2015, Python Software Foundation. +
+ The Python Software Foundation is a non-profit corporation. + Please donate. +
+ Last updated on Sep 12, 2015. + Found a bug? +
+ Created using Sphinx 1.2.3. +
+ + + \ No newline at end of file diff --git a/Lib/idlelib/idle_test/htest.py b/Lib/idlelib/idle_test/htest.py index aa7f2e8f088..3a9885c7732 100644 --- a/Lib/idlelib/idle_test/htest.py +++ b/Lib/idlelib/idle_test/htest.py @@ -194,13 +194,6 @@ _grep_dialog_spec = { "should open that file \nin a new EditorWindow." } -_help_dialog_spec = { - 'file': 'EditorWindow', - 'kwds': {}, - 'msg': "If the help text displays, this works.\n" - "Text is selectable. Window is scrollable." - } - _io_binding_spec = { 'file': 'IOBinding', 'kwds': {}, @@ -279,6 +272,13 @@ _scrolled_list_spec = { "Right clicking an item will display a popup." } +show_idlehelp_spec = { + 'file': 'help', + 'kwds': {}, + 'msg': "If the help text displays, this works.\n" + "Text is selectable. Window is scrollable." + } + _stack_viewer_spec = { 'file': 'StackViewer', 'kwds': {}, diff --git a/Lib/idlelib/macosxSupport.py b/Lib/idlelib/macosxSupport.py index 77330cf91a7..1030afea5f3 100644 --- a/Lib/idlelib/macosxSupport.py +++ b/Lib/idlelib/macosxSupport.py @@ -174,9 +174,8 @@ def overrideRootMenu(root, flist): configDialog.ConfigDialog(root, 'Settings') def help_dialog(event=None): - from idlelib import textView - fn = path.join(path.abspath(path.dirname(__file__)), 'help.txt') - textView.view_file(root, 'Help', fn) + from idlelib import help + help.show_idlehelp(root) root.bind('<>', about_dialog) root.bind('<>', config_dialog)