Index: Misc/NEWS =================================================================== --- Misc/NEWS (revision 83093) +++ Misc/NEWS (working copy) @@ -1437,6 +1437,12 @@ - Issue #8235: _socket: Add the constant ``SO_SETFIB``. SO_SETFIB is a socket option available on FreeBSD 7.1 and newer. +- Issue #2001: Add a new page header to pydoc html pages (in gui mode) with + Python version, get, search, module index, topics, and keywords choices. + Add a new local_text_server module to the http package which serves + generated text/html pages. + Removed tkinter search panel and need for tk in pydoc. + Extension Modules ----------------- Index: Doc/library/pydoc.rst =================================================================== --- Doc/library/pydoc.rst (revision 83093) +++ Doc/library/pydoc.rst (working copy) @@ -53,9 +53,11 @@ that will serve documentation to visiting Web browsers. :program:`pydoc` :option:`-p 1234` will start a HTTP server on port 1234, allowing you to browse the documentation at ``http://localhost:1234/`` in your preferred Web browser. -:program:`pydoc` :option:`-g` will start the server and additionally bring up a -small :mod:`tkinter`\ -based graphical interface to help you search for -documentation pages. +:program:`pydoc` :option:`-g` will start the server and additionally open a web +browser to a module index page. Each served page has a navigation bar at the +top where you can 'get' help on a individual item, 'find' all modules with a +keyword in their synopsis line, and goto indexes for 'modules', 'topics' and +'keywords'. When :program:`pydoc` generates documentation, it uses the current environment and path to locate modules. Thus, invoking :program:`pydoc` :option:`spam` Index: Lib/http/local_text_server.py =================================================================== --- Lib/http/local_text_server.py (revision 0) +++ Lib/http/local_text_server.py (revision 0) @@ -0,0 +1,134 @@ +""" +A simple local HTML/text server + +Start an html server so html and text documents can be browsed +dynamically and interactively with a web browser. + +Note: This server was developed to use with pydoc. + Any changes made to this file should be tested with pydoc. + + +Example use from another module. + + import http.local_text_server + + # Page getter - get a page of text + def page_getter(url): + # + # use url to get or generate a page of text or html + # code to send back to the web browser. + # + text = 'the url sent was: %s' % url + return text + + # Define a url handler. + def my_url_handler(url): + return page_getter(url) + + # Start server thread on port 8080. + server.start(my_url_handler, 8080) + + # Open browser and get first page. + import webbrowser + webbrowser.open("http://localhost:%s/startpage.html" % port) + while server.serving: #serve until stopped. + time.sleep(1) + +To stop the server thread explicitly: + server.stop() + +""" +import sys +import http.server +import email.message +import select +import threading +import time + +class DocHandler(http.server.BaseHTTPRequestHandler): + """ Handle server requests from browser. + """ + def do_GET(self): + """ Process a request from a html browser. + The url received is in self.path. + Get an html page from self.urlhandler and send it. + """ + if self.path.endswith('.css'): + content_type = 'text/css' + else: + content_type = 'text/html' + self.send_response(200) + self.send_header('Content-Type', content_type) + self.end_headers() + self.wfile.write(bytes(self.urlhandler(self.path, content_type), + 'UTF-8')) + + def log_message(self, *args): + # Don't log messages. + pass + + +class DocServer(http.server.HTTPServer): + def __init__(self, port, callback): + host = (sys.platform == 'mac') and '127.0.0.1' or 'localhost' + self.address = ('', port) + self.url = 'http://%s:%d/' % (host, port) + self.callback = callback + self.base.__init__(self, self.address, self.handler) + self.quit = False + + def serve_until_quit(self): + while not self.quit: + rd, wr, ex = select.select([self.socket.fileno()], [], [], 1) + if rd: + self.handle_request() + + def server_activate(self): + self.base.server_activate(self) + if self.callback: + self.callback(self) + + +class ServerThread(threading.Thread): + """ Use to start the server as a thread in an application. + """ + def __init__(self, urlhandler, port): + self.urlhandler = urlhandler + self.port = int(port) + threading.Thread.__init__(self) + self.serving = False + + def run(self): + """ Start the server. + """ + DocServer.base = http.server.HTTPServer + DocServer.handler = DocHandler + DocHandler.MessageClass = email.message.Message + DocHandler.urlhandler = staticmethod(self.urlhandler) + dsvr = DocServer(self.port, self.ready) + self.docserver = dsvr + dsvr.serve_until_quit() + + def ready(self, server): + self.serving = True + self.url = server.url + + def stop(self): + """ Stop the server and this thread nicely + """ + self.docserver.quit = True + self.serving = False + self.url = None + + +def startserver(urlhandler, port): + """ Start a http server thread on a specific port. + Use address http://localhost:/ + """ + thread = ServerThread(urlhandler, port) + thread.start() + # make sure we are really up before returning. + while not thread.serving: + time.sleep(.01) + return thread + Index: Lib/pydoc.py =================================================================== --- Lib/pydoc.py (revision 83093) +++ Lib/pydoc.py (working copy) @@ -20,7 +20,7 @@ local machine to generate documentation web pages. For platforms without a command line, "pydoc -g" starts the HTTP server -and also pops up a little window for controlling it. +and opens the web browser to the index page. Run "pydoc -w " to write out the HTML documentation for a module to a file named ".html". @@ -593,7 +593,7 @@ if sys.platform == 'win32': import nturl2path url = nturl2path.pathname2url(path) - filelink = '%s' % (url, path) + filelink = '%s' % (url, path) except TypeError: filelink = '(built-in)' info = [] @@ -613,7 +613,7 @@ docloc = '' result = self.heading( head, '#ffffff', '#7799ee', - 'index
' + filelink + docloc) + filelink + docloc) modules = inspect.getmembers(object, inspect.ismodule) @@ -1842,6 +1842,36 @@ 'Related help topics: ' + ', '.join(xrefs.split()) + '\n') self.output.write('\n%s\n' % buffer.getvalue()) + def gettopic(self, topic, more_xrefs=''): + # + # Returns unbuffered tuple of (topic, xrefs). + # + # If an error acurrs, topic is the error message, and xrefs is ''. + # This function duplicates showtopic but returns it's result directly + # so it can be formatted for display in an html page. + # + try: + import pydoc_data.topics + except ImportError: + return(''' +Sorry, topic and keyword documentation is not available because the +module "pydoc_data.topics" could not be found. +''' , '') + return + target = self.topics.get(topic, self.keywords.get(topic)) + if not target: + return 'no documentation found for %s' % repr(topic), '' + if type(target) is type(''): + return self.gettopic(target, more_xrefs) + label, xrefs = target + try: + doc = pydoc_data.topics.topics[label] + except KeyError: + return 'no documentation found for %s' % repr(topic), '' + if more_xrefs: + xrefs = (xrefs or '') + ' ' + more_xrefs + return doc, xrefs + def showsymbol(self, symbol): target = self.symbols[symbol] topic, _, xrefs = target.partition(' ') @@ -1973,269 +2003,235 @@ else: warnings.filterwarnings('ignore') # ignore problems during import ModuleScanner().run(callback, key, onerror=onerror) + # --------------------------------------------------- web browser interface -def serve(port, callback=None, completer=None): - import http.server, email.message, select +def html_navbar(): return \ +""" + + + + + +
Python %s
+ + +
+ + +
+ Index of Modules + : Topics + : Keywords +
+""" % sys.version - class DocHandler(http.server.BaseHTTPRequestHandler): - def send_document(self, title, contents): - try: - self.send_response(200) - self.send_header('Content-Type', 'text/html; charset=UTF-8') - self.end_headers() - self.wfile.write(html.page(title, contents).encode('utf-8')) - except IOError: pass - def do_GET(self): - path = self.path - if path[-5:] == '.html': path = path[:-5] - if path[:1] == '/': path = path[1:] - if path and path != '.': - try: - obj = locate(path, forceload=1) - except ErrorDuringImport as value: - self.send_document(path, html.escape(str(value))) - return - if obj: - self.send_document(describe(obj), html.document(obj, path)) - else: - self.send_document(path, -'no Python documentation found for %s' % repr(path)) - else: - heading = html.heading( -'Python: Index of Modules', -'#ffffff', '#7799ee') - def bltinlink(name): - return '%s' % (name, name) - names = [x for x in sys.builtin_module_names if x != '__main__'] - contents = html.multicolumn(names, bltinlink) - indices = ['

' + html.bigsection( - 'Built-in Modules', '#ffffff', '#ee77aa', contents)] +def html_index(): + """ Index of modules web page. """ + def bltinlink(name): + return '%s' % (name, name) - seen = {} - for dir in sys.path: - indices.append(html.index(dir, seen)) - contents = heading + ' '.join(indices) + '''

- + heading = html.heading( + 'Index of Modules', + '#ffffff', '#7799ee') + names = list(filter(lambda x: x != '__main__', + sys.builtin_module_names)) + contents = html.multicolumn(names, bltinlink) + indices = ['

' + html.bigsection( + 'Built-in Modules', '#ffffff', '#ee77aa', contents)] + seen = {} + for dir in sys.path: + indices.append(html.index(dir, seen)) + contents = heading + ''.join(indices) + \ +'''

pydoc by Ka-Ping Yee <ping@lfw.org>''' - self.send_document('Index of Modules', contents) + return html.page('Index of Modules' ,contents) - def log_message(self, *args): pass - class DocServer(http.server.HTTPServer): - def __init__(self, port, callback): - host = 'localhost' - self.address = ('', port) - self.url = 'http://%s:%d/' % (host, port) - self.callback = callback - self.base.__init__(self, self.address, self.handler) +def html_search(key): + """ Search results page. """ + # scan for modules + search_result = [] + def callback(path, modname, desc): + if modname[-9:] == '.__init__': + modname = modname[:-9] + ' (package)' + search_result.append((modname, desc and '- ' + desc)) + try: import warnings + except ImportError: pass + else: warnings.filterwarnings('ignore') # ignore problems during import + ModuleScanner().run(callback, key) + # format page + def bltinlink(name): + return '%s' % (name, name) + results = [] + heading = html.heading( + 'Search Results', + '#ffffff', '#7799ee') + for name, desc in search_result: + results.append(bltinlink(name) + desc) + contents = heading + html.bigsection( + 'key = %s' % key, '#ffffff', '#ee77aa', '
'.join(results)) + return html.page('Search Results', contents) - def serve_until_quit(self): - import select - self.quit = False - while not self.quit: - rd, wr, ex = select.select([self.socket.fileno()], [], [], 1) - if rd: self.handle_request() - def server_activate(self): - self.base.server_activate(self) - if self.callback: self.callback(self) - - DocServer.base = http.server.HTTPServer - DocServer.handler = DocHandler - DocHandler.MessageClass = email.message.Message +def html_getfile(path): + """ Get and display a source file listing safely. + """ + path = os.sep + path.replace('%20', ' ') try: - try: - DocServer(port, callback).serve_until_quit() - except (KeyboardInterrupt, select.error): - pass + f = open(path, 'r') + lines = html.escape(f.read()) finally: - if completer: completer() + f.close() + body = '

%s
' % lines + heading = html.heading( + 'File Listing', + '#ffffff', '#7799ee') + contents = heading + html.bigsection( + 'File: %s' % path, '#ffffff', '#ee77aa', body) + return html.page('getfile: %s' % path, contents) -# ----------------------------------------------------- graphical interface -def gui(): - """Graphical interface (starts web server and pops up a control window).""" - class GUI: - def __init__(self, window, port=7464): - self.window = window - self.server = None - self.scanner = None +def html_topics(): + """ Index of topic texts available. + """ + def bltinlink(name): + return '%s' % (name, name) + heading = html.heading( + 'INDEX', + '#ffffff', '#7799ee') + names = sorted(Helper.topics.keys()) + def bltinlink(name): + return '%s' % (name, name) + contents = html.multicolumn(names, bltinlink) + contents = heading + html.bigsection( + 'Topics', '#ffffff', '#ee77aa', contents) + return html.page('Topics', contents) - import tkinter - self.server_frm = tkinter.Frame(window) - self.title_lbl = tkinter.Label(self.server_frm, - text='Starting server...\n ') - self.open_btn = tkinter.Button(self.server_frm, - text='open browser', command=self.open, state='disabled') - self.quit_btn = tkinter.Button(self.server_frm, - text='quit serving', command=self.quit, state='disabled') - self.search_frm = tkinter.Frame(window) - self.search_lbl = tkinter.Label(self.search_frm, text='Search for') - self.search_ent = tkinter.Entry(self.search_frm) - self.search_ent.bind('', self.search) - self.stop_btn = tkinter.Button(self.search_frm, - text='stop', pady=0, command=self.stop, state='disabled') - if sys.platform == 'win32': - # Trying to hide and show this button crashes under Windows. - self.stop_btn.pack(side='right') +def html_keywords(): + """ Index of keywords. + """ + heading = html.heading( + 'INDEX', + '#ffffff', '#7799ee') + names = sorted(Helper.keywords.keys()) + def bltinlink(name): + return '%s' % (name, name) + contents = html.multicolumn(names, bltinlink) + contents = heading + html.bigsection( + 'Keywords', '#ffffff', '#ee77aa', contents) + return html.page('Keywords', contents) - self.window.title('pydoc') - self.window.protocol('WM_DELETE_WINDOW', self.quit) - self.title_lbl.pack(side='top', fill='x') - self.open_btn.pack(side='left', fill='x', expand=1) - self.quit_btn.pack(side='right', fill='x', expand=1) - self.server_frm.pack(side='top', fill='x') - self.search_lbl.pack(side='left') - self.search_ent.pack(side='right', fill='x', expand=1) - self.search_frm.pack(side='top', fill='x') - self.search_ent.focus_set() +def html_topicpage(topic): + """ Topic or keyword help page. + """ + import io + buf = io.StringIO() + htmlhelp = Helper(buf, buf) + contents, xrefs = htmlhelp.gettopic(topic) + if topic in htmlhelp.keywords: + title = 'KEYWORD' + else: + title = 'TOPIC' + heading = html.heading( + '%s' % title, + '#ffffff', '#7799ee') + contents = '
%s
' % contents + contents = html.bigsection(topic , '#ffffff','#ee77aa', contents) + xrefs = sorted(xrefs.split()) + def bltinlink(name): + return '%s' % (name, name) + xrefs = html.multicolumn(xrefs, bltinlink) + xrefs = html.section('Related help topics: ', '#ffffff', '#ee77aa', xrefs) - font = ('helvetica', sys.platform == 'win32' and 8 or 10) - self.result_lst = tkinter.Listbox(window, font=font, height=6) - self.result_lst.bind('', self.select) - self.result_lst.bind('', self.goto) - self.result_scr = tkinter.Scrollbar(window, - orient='vertical', command=self.result_lst.yview) - self.result_lst.config(yscrollcommand=self.result_scr.set) + return html.page('%s: %s' % (title, topic), heading + contents + xrefs) + - self.result_frm = tkinter.Frame(window) - self.goto_btn = tkinter.Button(self.result_frm, - text='go to selected', command=self.goto) - self.hide_btn = tkinter.Button(self.result_frm, - text='hide results', command=self.hide) - self.goto_btn.pack(side='left', fill='x', expand=1) - self.hide_btn.pack(side='right', fill='x', expand=1) +def html_error(url): + heading = html.heading( + 'Error', + '#ffffff', '#ee0000') + return heading + url - self.window.update() - self.minwidth = self.window.winfo_width() - self.minheight = self.window.winfo_height() - self.bigminheight = (self.server_frm.winfo_reqheight() + - self.search_frm.winfo_reqheight() + - self.result_lst.winfo_reqheight() + - self.result_frm.winfo_reqheight()) - self.bigwidth, self.bigheight = self.minwidth, self.bigminheight - self.expanded = 0 - self.window.wm_geometry('%dx%d' % (self.minwidth, self.minheight)) - self.window.wm_minsize(self.minwidth, self.minheight) - self.window.tk.willdispatch() - import threading - threading.Thread( - target=serve, args=(port, self.ready, self.quit)).start() +def get_html_page(url): + """ Function url handler uses to get the html page to get + depending on the url. + """ + if url[-5:] == '.html': url = url[:-5] + if url[:1] == '/': url = url[1:] + if url.startswith("get?key="): + url = url[8:] + title = url + contents = '' + if url in ("", ".", "index"): + contents = html_index() + elif url == "topics": + contents = html_topics() + elif url == "keywords": + contents = html_keywords() + elif url.startswith("search?key="): + contents = html_search(url[11:]) + elif url.startswith("getfile?key="): + url = url[12:] + try: + contents = html_getfile(url) + except IOError as value: + contents = html_error('could read file %s' % repr(url)) + else: + obj = None + try: + obj = locate(url, forceload=1) + except ErrorDuringImport as value: + contents = html.escape(str(value)) + if obj: + title = describe(obj) + contents = html.document(obj, url) + elif url in Helper.keywords or url in Helper.topics: + contents = html_topicpage(url) + else: + contents = html_error('no Python documentation found for %s' + % repr(url)) + return html.page(title, html_navbar() + contents) + - def ready(self, server): - self.server = server - self.title_lbl.config( - text='Python documentation server at\n' + server.url) - self.open_btn.config(state='normal') - self.quit_btn.config(state='normal') +def gui(port=7464, browse=True): + """ Start pydoc server and web browser. + """ + import http.local_text_server + import webbrowser + import time - def open(self, event=None, url=None): - url = url or self.server.url - try: - import webbrowser - webbrowser.open(url) - except ImportError: # pre-webbrowser.py compatibility - if sys.platform == 'win32': - os.system('start "%s"' % url) - else: - rc = os.system('netscape -remote "openURL(%s)" &' % url) - if rc: os.system('netscape "%s" &' % url) + def url_handler(url, content_type): + """ html server html and style sheet requests. + """ + if url.startswith('/'): + url = url[1:] + if content_type == 'text/css': + fp = open(os.path.join(path_here, url)) + css = ''.join(fp.readlines()) + fp.close() + return css + elif content_type == 'text/html': + return get_html_page(url) + return 'Error: unknown content type ' + content_type - def quit(self, event=None): - if self.server: - self.server.quit = 1 - self.window.quit() - - def search(self, event=None): - key = self.search_ent.get() - self.stop_btn.pack(side='right') - self.stop_btn.config(state='normal') - self.search_lbl.config(text='Searching for "%s"...' % key) - self.search_ent.forget() - self.search_lbl.pack(side='left') - self.result_lst.delete(0, 'end') - self.goto_btn.config(state='disabled') - self.expand() - - import threading - if self.scanner: - self.scanner.quit = 1 - self.scanner = ModuleScanner() - threading.Thread(target=self.scanner.run, - args=(self.update, key, self.done)).start() - - def update(self, path, modname, desc): - if modname[-9:] == '.__init__': - modname = modname[:-9] + ' (package)' - self.result_lst.insert('end', - modname + ' - ' + (desc or '(no description)')) - - def stop(self, event=None): - if self.scanner: - self.scanner.quit = 1 - self.scanner = None - - def done(self): - self.scanner = None - self.search_lbl.config(text='Search for') - self.search_lbl.pack(side='left') - self.search_ent.pack(side='right', fill='x', expand=1) - if sys.platform != 'win32': self.stop_btn.forget() - self.stop_btn.config(state='disabled') - - def select(self, event=None): - self.goto_btn.config(state='normal') - - def goto(self, event=None): - selection = self.result_lst.curselection() - if selection: - modname = self.result_lst.get(selection[0]).split()[0] - self.open(url=self.server.url + modname + '.html') - - def collapse(self): - if not self.expanded: return - self.result_frm.forget() - self.result_scr.forget() - self.result_lst.forget() - self.bigwidth = self.window.winfo_width() - self.bigheight = self.window.winfo_height() - self.window.wm_geometry('%dx%d' % (self.minwidth, self.minheight)) - self.window.wm_minsize(self.minwidth, self.minheight) - self.expanded = 0 - - def expand(self): - if self.expanded: return - self.result_frm.pack(side='bottom', fill='x') - self.result_scr.pack(side='right', fill='y') - self.result_lst.pack(side='top', fill='both', expand=1) - self.window.wm_geometry('%dx%d' % (self.bigwidth, self.bigheight)) - self.window.wm_minsize(self.minwidth, self.bigminheight) - self.expanded = 1 - - def hide(self, event=None): - self.stop() - self.collapse() - - import tkinter + serverthread = http.local_text_server.startserver(url_handler, port) + print('Server ready at:', serverthread.url) + if browse: + webbrowser.open("http://localhost:%s" % port) try: - root = tkinter.Tk() - # Tk will crash if pythonw.exe has an XP .manifest - # file and the root has is not destroyed explicitly. - # If the problem is ever fixed in Tk, the explicit - # destroy can go. - try: - gui = GUI(root) - root.mainloop() - finally: - root.destroy() - except KeyboardInterrupt: - pass + while serverthread.serving: + time.sleep(.01) + finally: + if serverthread.serving: + serverthread.stop() + print('Server stopped') + # -------------------------------------------------- command-line interface def ispath(x): @@ -2266,15 +2262,7 @@ apropos(val) return if opt == '-p': - try: - port = int(val) - except ValueError: - raise BadUsage - def ready(server): - print('pydoc server ready at %s' % server.url) - def stopped(): - print('pydoc server stopped') - serve(port, ready, stopped) + gui(port=val, browse=False) return if opt == '-w': writing = 1 @@ -2316,7 +2304,7 @@ Start an HTTP server on the given port on the local machine. %s -g - Pop up a graphical interface for finding and serving documentation. + Use a web browser to interactively browse documentation. %s -w ... Write out the HTML documentation for a module to a file in the current Index: Lib/test/test_pydoc.py =================================================================== --- Lib/test/test_pydoc.py (revision 83093) +++ Lib/test/test_pydoc.py (working copy) @@ -92,7 +92,7 @@  
 
test.pydoc_mod (version 1.2.3.4)
index
%s%s
+>%s

This is a test module for test_pydoc

@@ -249,7 +249,7 @@ mod_url = nturl2path.pathname2url(mod_file) else: mod_url = mod_file - expected_html = expected_html_pattern % (mod_url, mod_file, doc_loc) + expected_html = expected_html_pattern % (mod_url, mod_file) if result != expected_html: print_diffs(expected_html, result) self.fail("outputs are not equal, see diff above")