Issue #16893: include new files
diff --git a/Lib/idlelib/help.py b/Lib/idlelib/help.py
new file mode 100644
index 0000000..a895a9c
--- /dev/null
+++ b/Lib/idlelib/help.py
@@ -0,0 +1,236 @@
+"""
+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
+
+<to be moved here from aboutDialog.py>
+
+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 HTMLParser import HTMLParser
+from os.path import abspath, dirname, isdir, isfile, join
+from Tkinter import Tk, Toplevel, Frame, Text, Scrollbar, Menu, Menubutton
+import tkFont 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)
+ 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 <dl>
+ 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)
+
+ def handle_charref(self, name):
+ self.text.insert('end', unichr(int(name)))
+
+
+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) as f:
+ contents = f.read().decode(encoding='utf-8')
+ 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)