1 ;; LCD-ENTRY: pydoc.el|Bob Weiner|bob@deepware.com|Interface to pydoc Python documentation viewer|Date|04/23/2001|01.02|www.deepware.com/pub/python
4 ;; SUMMARY: Interface to pydoc Python documentation viewer
5 ;; USAGE: Autoloaded XEmacs Lisp Library, use {C-c M-h} to invoke
6 ;; KEYWORDS: help, languages, oop, tools
10 ;; E-MAIL: bob@deepware.com
12 ;; ORIG-DATE: 18-Apr-01 at 19:11:27
13 ;; LAST-MOD: 23-Apr-01 at 23:59:46 by Bob Weiner
15 ;; Copyright (C) 2001 Bob Weiner
16 ;; Licensed under the Python license version 2.0 or higher.
18 ;; This file is part of InfoDock, available from:
19 ;; www.sourceforge.net/projects/infodock
23 ;; Globally adds key binding {C-c M-h} (pydoc-commands) which
24 ;; displays a menu of commands for interacting with the pydoc Python
25 ;; documentation viewer library. See the documentation of
26 ;; `pydoc-menu-help' for details on each available command.
28 ;; NOTE: You *must* install the following for pydoc.el to work:
30 ;; python-mode.el 4.1.1 or higher as your Python editing mode (included
31 ;; in the pydoc.el distribution)
33 ;; pydoc_lisp.py in your Python site-packages directory (unless
34 ;; these functions are already integrated into pydoc.py)
36 ;; set the environment variable PYTHONDOCS to the root directory
37 ;; of your Python html documentation tree, for example:
38 ;; export PYTHONDOCS=$HOME/Python-2.1/Doc/html/
39 ;; and then startup your editor (otherwise, the environment variable
40 ;; setting won't be inherited by the editor and some commands will not
43 ;; Install and byte-compile pydoc.el in one of your load-path directories
44 ;; and then either set it to autoload or do a (require 'pydoc) in your
45 ;; editor initialization file. Then invoke it via the menu key binding.
49 ;;; ************************************************************************
50 ;;; Other required Elisp libraries
51 ;;; ************************************************************************
53 (require 'python-mode)
55 ;; Ensure that the user has a python-mode version which supports pydoc.el.
56 (if (string-lessp py-version "$Revision: 1.1 $")
57 (error "(pydoc): you must upgrade from python-mode.el %s to 4.1.1 (or higher)"
58 (if (string-match "[0-9.]+" py-version)
59 (match-string 0 py-version) py-version)))
63 ;;; ************************************************************************
65 ;;; ************************************************************************
67 (defvar pydoc-version "01.01"
68 "Release version of the Emacs Lisp interface to pydoc.")
70 ;; Provide easy access to (pydoc-commands) everywhere since the user may want
71 ;; to reference Python doc when in a Python help buffer, a documentation file,
72 ;; etc. Use {C-c M-h} instead of {C-c C-h} for this next binding since
73 ;; {C-c C-h} is an important key in InfoDock's outline-minor-mode which is
74 ;; often used under python-mode, so this avoids conflicts.
77 (global-set-key "\C-c\M-h" 'pydoc-commands)
79 (defvar pydoc-buffer-prefix "Py: "
80 "Prefix string attached to all pydoc display buffers.")
82 (defvar pydoc-xrefs-prefix "^Related help topics:"
83 "Prefix regexp output before comma separated pydoc help section names.")
85 ;;; ************************************************************************
87 ;;; ************************************************************************
89 (defvar pydoc-cmd-alist
90 '(("A)propos" . pydoc-apropos)
91 ("H)elp" . pydoc-help)
92 ("K)eyword" . pydoc-keywords)
93 ("M)odule" . pydoc-modules)
94 ("P)ackage" . pydoc-packages)
95 ("T)opic" . pydoc-topics)
96 ("X)ref" . pydoc-xrefs))
97 "Association list of (HELP-CMD-PROMPT . CMD) elements for pydoc commands.")
99 (defvar pydoc-alist nil
100 "Association list of (list-name . alist) elements used to build prompt completion tables.")
102 (defvar pydoc-menu-mode-map nil
103 "Keymap containing pydoc-menu commands.")
105 (defvar pydoc-menu-special-keys '(?\C-g ?? ?\C-i ?\C-j ?\C-m ?\ ))
107 (if pydoc-menu-mode-map
109 (setq pydoc-menu-mode-map (make-keymap))
110 (suppress-keymap pydoc-menu-mode-map)
111 (define-key pydoc-menu-mode-map
112 (car (where-is-internal 'keyboard-quit)) 'pydoc-menu-enter)
113 (mapcar #'(lambda (key)
114 (define-key pydoc-menu-mode-map (char-to-string key) 'pydoc-menu-enter))
115 pydoc-menu-special-keys)
118 (define-key pydoc-menu-mode-map (char-to-string i) 'pydoc-menu-enter)
121 ;;; ************************************************************************
123 ;;; ************************************************************************
126 (defun pydoc-commands (&optional init-flag)
127 "Display a menu of commands for interacting with the pydoc Python documentation viewer library.
128 With optional prefix arg INIT-FLAG, reinitializes the pydoc completion
129 tables which includes the list of available Python modules.
130 See the documentation for `pydoc-menu-help' for a description of the
133 (if (or init-flag (null pydoc-alist))
135 (call-interactively (pydoc-select-command)))
138 (defun pydoc-apropos (&optional argument)
139 "Call the Python module apropos function with optional ARGUMENT and display the output.
140 ARGUMENT defaults to an identifier near point.
141 The apropos function finds matches for ARGUMENT within the first line of
142 module or package doc strings."
145 (setq argument (pydoc-read-argument "Python module/package apropos: ")))
146 (pydoc-call "apropos" (format "'%s'" argument) (concat "apropos " argument)))
149 (defun pydoc-help (&optional argument)
150 "Call the Python help function with optional ARGUMENT and display the output.
151 ARGUMENT defaults to an identifier near point.
152 ARGUMENT is resolved as a name in any present Python namespace; use
153 single 'quotes' to send ARGUMENT as a Python literal string."
156 (setq argument (pydoc-read-argument "Python help (name or 'string'): ")))
157 (pydoc-call "help" argument argument))
160 (defun pydoc-keywords (argument)
161 "Prompt with completion for a Python keyword ARGUMENT and display its documentation."
164 (let ((completion-ignore-case t))
165 (completing-read "Python keyword help (RET for all): "
166 (cdr (assoc "keywords" pydoc-alist))
168 (if (member argument '(nil ""))
169 (setq argument "keywords"))
170 (pydoc-call "help" (format "'%s'" argument) argument))
173 (defun pydoc-modules (argument)
174 "Prompt with completion for a Python module/package ARGUMENT and display its documentation."
177 (let ((completion-ignore-case t))
178 (completing-read "Python module/package help (RET for all): "
179 (cdr (assoc "modules" pydoc-alist))
181 (if (member argument '(nil ""))
182 (setq argument "modules"))
183 (if (string-match "\\`Pkg-" argument)
184 (setq argument (substring argument (match-end 0))))
185 (pydoc-call "help" (format "'%s'" argument) argument))
188 (defun pydoc-packages (argument)
189 "Prompt with completion for a Python package ARGUMENT and display its documentation."
192 (let ((completion-ignore-case t))
193 (completing-read "Python package help (RET for all): "
197 (if (string-match "\\`Pkg-" entry)
198 (list (substring entry (match-end 0)))))
199 (mapcar 'car (cdr (assoc "modules" pydoc-alist)))))
201 (if (member argument '(nil ""))
202 (setq argument "modules"))
203 (if (string-match "\\`Pkg-" argument)
204 (setq argument (substring argument (match-end 0))))
205 (pydoc-call "help" (format "'%s'" argument) argument))
208 (defun pydoc-topics (argument)
209 "Prompt with completion for a Python topic ARGUMENT and display its documentation."
212 (let ((completion-ignore-case t))
213 (completing-read "Python topic help (RET for all): "
214 (cdr (assoc "topics" pydoc-alist))
216 (if (member argument '(nil ""))
217 (setq argument "topics")
218 (setq argument (upcase argument)))
219 (pydoc-call "help" (format "'%s'" argument) argument))
222 (defun pydoc-xrefs ()
223 "Display xref at point or prompt user with completion and display chosen xref.
224 Xrefs are terms which follow the `pydoc-xrefs-prefix' regular expression."
226 (cond ((save-excursion
228 (looking-at pydoc-xrefs-prefix))
230 (if (>= (point) (match-end 0))
231 ;; After prefix, within an xref
233 ;; Prompt for with completion and display xref
236 (goto-char (match-end 0))
237 (pydoc-choose-xref "Display xref: ")))))
239 ;; Move to last xref line if any in buffer
241 ;; Prompt for with completion and display xref
244 (goto-char (match-end 0))
245 (pydoc-choose-xref "Display xref: "))))
247 (t (error "(pydoc): No cross-references in this buffer"))))
249 ;;; ************************************************************************
251 ;;; ************************************************************************
253 (defun pydoc-call (func-name argument buf-name-suffix)
254 "Call the pydoc function FUNC-NAME with ARGUMENT (a string) and display in Py: BUF-NAME-SUFFIX."
255 (let ((wind-config (current-window-configuration))
259 "if not vars().has_key('%s'):\n from pydoc import %s\n\n%s(%s)\n"
260 func-name func-name func-name argument)))
261 (async-process (pydoc-async-output-p))
263 (setq input-buf-name (if async-process
264 (buffer-name (process-buffer async-process))
265 " *Python Command*"))
266 (if (buffer-live-p (get-buffer input-buf-name))
267 (bury-buffer input-buf-name))
269 ;; current vintages of python-mode.el (4.6 at least)
270 ;; no longer return a buffer [name]. We get t from the
271 ;; final kill-buffer instead. If we see t we use try to
272 ;; guess a good buffer name.
273 (if (eq output-buf-name t)
274 (setq output-buf-name (if async-process
275 (buffer-name (process-buffer async-process))
278 (if (or (null output-buf-name)
279 ;; In earlier versions of python-mode.el, py-execute-string does
280 ;; not return a buffer name.
281 (not (stringp output-buf-name))
282 (not (buffer-live-p (get-buffer output-buf-name)))
283 (and async-process (not (pydoc-wait-for-output input-buf-name 10.0))))
284 (message "(\"%s(%s)\" finished with no output)" func-name argument)
285 (set-window-configuration wind-config)
286 (bury-buffer output-buf-name)
287 (set-buffer output-buf-name)
288 (goto-char (point-max)) ;; User may have moved point elsewhere.
290 ;; Skip any trailing Python prompt
291 (save-excursion (beginning-of-line) (point)))
292 (output-start (pydoc-output-start))
295 (goto-char (point-max))
297 (looking-at "^NameError:"))
298 (progn (switch-to-buffer (car (buffer-list)))
299 (error "(pydoc): %s(%s) failed to find any matching term"
301 (setq display-buf (get-buffer-create
302 (concat pydoc-buffer-prefix buf-name-suffix)))
303 (set-buffer display-buf)
306 (insert-buffer-substring output-buf-name output-start output-end)
307 (goto-char (point-min))
308 (set-buffer-modified-p nil)
311 (pydoc-kill-async-output output-buf-name async-process)
312 (pop-to-buffer display-buf))))))
314 (defun pydoc-display-apropos-entry ()
315 "Detect module/package names in pydoc apropos buffer entries and display their code.
316 Each module/package name must be at the beginning of the line
317 and must be followed by a space, dash and then another space."
319 (if (string-match (concat "\\`" (regexp-quote pydoc-buffer-prefix)
324 (if (looking-at "\\([^][-(){}<>'`\"/*+&^%$#@!=|?,~ \t\n\r]+\\) - ")
325 (let* ((entry (buffer-substring
326 (match-beginning 1) (match-end 1)))
327 (path (pydoc-pathname entry)))
328 (if (and path (file-exists-p path))
329 (find-file-other-window path)))))))
331 (defun pydoc-pathname (module-identifier)
332 "Return the filename or package directory where MODULE-IDENTIFIER is defined, else nil."
333 (setq module-identifier
334 (replace-in-string module-identifier "\\."
335 (char-to-string directory-sep-char) t))
336 (or (locate-file module-identifier (pydoc-paths-list) ".py:.pyc:.pyo:.pyd")
337 ;; May be a package directory
338 (locate-data-directory module-identifier (pydoc-paths-list))))
340 ;;; ************************************************************************
341 ;;; Private functions
342 ;;; ************************************************************************
344 (defun pydoc-commands-dialog-box (dialog-box)
345 "Prompt user with DIALOG-BOX and return selected value.
346 Assumes caller has checked that `dialog-box' function exists."
347 (let ((echo-keystrokes 0)
350 ;; Add cmd-help and cancel buttons to dialog box.
351 (setq dialog-box (append dialog-box
352 (list nil '["Cmd-Help" (pydoc-menu-help) t]
353 '["Cancel" 'keyboard-quit t])))
354 (popup-dialog-box dialog-box)
357 (setq event (next-command-event event)
358 event-obj (event-object event))
359 (cond ((and (menu-event-p event)
360 (memq event-obj '(abort menu-no-selection-hook)))
362 ((button-release-event-p event) ;; don't beep twice
364 ((menu-event-p event)
365 (throw 'pydoc-done (eval event-obj)))
368 (message "Please answer the dialog box.")))))))
370 (defun pydoc-default-argument ()
371 "Return a default identifier argument near point."
373 ;; Include periods as symbol constituents but remove any trailing period.
374 (let* ((period-syntax (char-to-string (char-syntax ?\.)))
375 (default (unwind-protect
377 (modify-syntax-entry ?\. "_")
379 (modify-syntax-entry ?\. period-syntax))))
380 (if (and (stringp default) (string-match "\\.+\\'" default))
381 (setq default (substring default 0 (match-beginning 0))))
384 (defun pydoc-initialize()
385 (message "Please wait a moment while the Python help system is initialized...")
386 ;; XEmacs change: help python find pydoc_lisp.py OOTB.
388 (pydir (locate-data-directory "python-modes")))
389 (save-window-excursion
390 ;; Start a Python interpreter if not already running.
392 (pydoc-wait-for-output (current-buffer) 3.0)
396 "if not vars().has_key('pydoc_lisp'):
398 if not '%s' in sys.path:
399 sys.path.append('%s')
402 pydoc_lisp.pydoc_output_lisp()
404 ;; current vintages of python-mode.el (4.6 at least)
405 ;; no longer return a buffer [name]. We get t from the
406 ;; final kill-buffer instead. If we see t we use the
407 ;; python shell's buffer.
408 (if (eq output-buf t)
410 (buffer-name (process-buffer (pydoc-async-output-p)))))
412 (setq pydoc-alist (pydoc-lisp-read-result output-buf)))
413 (if (member pydoc-alist '(nil None Traceback))
415 (setq pydoc-alist nil)
416 (pop-to-buffer output-buf)
417 (error "(pydoc): Initialization failed, Python did not output Lisp lists"))
418 (pydoc-kill-async-output output-buf (pydoc-async-output-p))
419 ;; Normalize Python search paths and make a regular list, not an alist
420 (let ((paths (assoc "paths" pydoc-alist)))
421 (setcdr paths (mapcar 'file-name-as-directory
422 (mapcar 'car (cdr paths)))))
425 (defun pydoc-lisp-read-result (result-buf)
426 "Read and return the most recent python output in RESULT-BUF as a Lisp expression.
427 If a timeout occurs before the expression is read, then return nil."
429 (if (pydoc-wait-for-output result-buf 5.0)
430 (progn (goto-char (pydoc-output-start))
431 (read (current-buffer)))
434 (defun pydoc-output-start ()
435 "Return the character position start of the most recent Python output."
437 ;; Skip any trailing Python prompt
438 (forward-line 0) ;; to bol
439 (if (re-search-backward "^>>> " nil t)
440 (if (not (zerop (forward-line 1)))
441 (goto-char (point-max)))
442 (goto-char (point-min)))
445 (defun pydoc-read-argument (prompt)
446 "Read and return a string argument using PROMPT."
447 (let* ((default (pydoc-default-argument))
451 (format "%s(default %s) " prompt default)
453 (if (member argument '(nil ""))
457 (defun pydoc-select-command ()
458 "Interactively select and return a pydoc command to run."
461 ;; Use dialog box if last user event involved the mouse.
462 (use-dialog-box (and (fboundp 'popup-dialog-box)
463 (fboundp 'button-press-event-p)
464 (or (button-press-event-p last-command-event)
465 (button-release-event-p last-command-event)
466 (menu-event-p last-command-event)))))
467 ;; Create a prompt numbering each command available.
471 #'(lambda (name-and-cmd)
472 (vector (car name-and-cmd)
473 (list 'quote (cdr name-and-cmd))
478 (mapconcat 'identity (mapcar 'car pydoc-cmd-alist) " ")
482 (setq cmd (pydoc-commands-dialog-box
483 (cons "Choose pydoc command (or choose Cmd-Help for help on commands): " cmd-prompt)))
484 ;; Otherwise, prompt in the minibuffer.
485 (let ((item-keys (mapcar #'(lambda (item) (aref item 0))
486 (mapcar 'car pydoc-cmd-alist)))
488 (while (and (not (memq (setq key (upcase
490 (read-from-minibuffer
491 "" cmd-prompt pydoc-menu-mode-map))))
493 (not (memq key pydoc-menu-special-keys)))
499 (if (memq key pydoc-menu-special-keys)
500 (setq cmd (pydoc-menu-help))
501 (setq cmd (cdr (nth (- (length pydoc-cmd-alist)
502 (length (memq key item-keys)))
503 pydoc-cmd-alist))))))
506 ;;; Asynchronous handling
507 (defun pydoc-async-output-p ()
508 "Return the running asynchronous process for Python code evaluation or nil if none."
509 (let ((proc (and (stringp py-which-bufname)
510 (get-process py-which-bufname))))
511 (and proc (eq (process-status proc) 'run) proc)))
513 (defun pydoc-kill-async-output (output-buf async-process)
516 (set-buffer output-buf)
517 ;; Remove output so it doesn't clog up the interpreter buffer.
518 (comint-kill-output))))
520 (defun pydoc-wait-for-output (buffer timeout)
521 "Move to BUFFER and wait a maximum of TIMEOUT seconds or until Python command execution ends.
522 Python command execution ends when Python returns a top-level prompt.
523 Return t if waited less than TIMEOUT time (and thus received full output)."
525 (goto-char (point-max)) ;; User may have moved point elsewhere.
526 (let ((time-waited 0.0)
528 (while (and (< time-waited timeout)
530 (forward-line 0) ;; to bol
531 (looking-at ">>> \\'"))))
532 (sleep-for wait-time)
533 (setq time-waited (+ time-waited wait-time)))
534 (< time-waited timeout)))
537 ;;; Cmd menu handling
538 (defun pydoc-menu-enter (&optional char-str)
539 "Uses CHAR-STR or last input character as minibuffer argument."
541 (let ((input (or char-str (aref (recent-keys) (1- (length (recent-keys))))))
542 (case-fold-search t))
544 ;; GNU Emacs 19 or above
545 ((and (not (string-match "XEmacs" emacs-version))
546 ;; Version 19 and above.
547 (string-lessp "19" emacs-version))
548 (and (not (integerp input))
550 (setq input (event-basic-type input))))
551 ((string-match "XEmacs" emacs-version)
553 (setq input (event-to-character input)))))
558 (defun pydoc-menu-help ()
559 "Type one of the following characters:
561 a - A)propos <term> - list modules/packages with <term> in their first line doc strings
562 h - H)elp <term> - display doc for name <term> or string literal '<term>'
563 k - K)eyword <keyword> - with completion, display doc for a Python <keyword>
564 m - M)odule <name> - with completion, display doc for a Python module <name>
565 p - P)ackage <name> - with completion, display doc for a Python package <name>
566 t - T)opic <topic> - with completion, display Python reference doc for <topic>
567 x - X)ref <term> - with completion, display doc for a pydoc cross-reference
570 C-g - abort from menu"
572 (save-window-excursion
573 (switch-to-buffer "*Help*")
574 (setq buffer-read-only nil)
576 (insert (documentation 'pydoc-menu-help))
577 (goto-char (point-min))
578 (pydoc-select-command)))
580 ;;; Pathname handling
581 (defun pydoc-paths-list ()
582 (cdr (assoc "paths" pydoc-alist)))
586 (defun pydoc-choose-xref (prompt &optional xrefs-alist)
587 (or xrefs-alist (setq xrefs-alist (pydoc-xrefs-alist)))
588 (if (null xrefs-alist)
589 (error "(pydoc): No cross-references in this buffer")
590 (let ((completion-ignore-case t)
591 (default (pydoc-default-argument))
593 (if (not (assoc default xrefs-alist))
596 (setq result (completing-read
598 (format "%s(default %s) " prompt default)
601 (if (string-equal result "")
603 (setq result default)
608 (defun pydoc-delete-space (string)
609 "Delete any leading and trailing space from STRING and return the STRING."
610 (if (string-match "\\`[ \t\n\r\f]+" string)
611 (setq string (substring string (match-end 0))))
612 (if (string-match "[ \t\n\r\f]+\\'" string)
613 (setq string (substring string 0 (match-beginning 0))))
616 (defun pydoc-display-xref (&optional xref)
617 "Displays optional XREF (or prompts for and then displays it).
618 Signals an error when there are no xrefs within the current buffer."
620 (if (member xref '(nil ""))
621 ;; Triggers an error if there are no xrefs.
622 (setq xref (pydoc-choose-xref "Display xref: ")))
623 (let ((case-fold-search nil))
624 (if (string-match "\\`[0-9A-Z_]+\\'" xref)
625 ;; all uppercase, so is a topic
627 ;; assume is a module
628 (pydoc-modules xref))))
630 (defun pydoc-xrefs-alist ()
631 ;; Assumes all xrefs are on a single line following point.
632 (mapcar #'(lambda (str) (list (pydoc-delete-space str)))
633 (split-string (buffer-substring
634 (point) (save-excursion (end-of-line) (point)))
637 (defun pydoc-xrefs-p ()
638 "Return t if current buffer contains xrefs or nil otherwise.
639 A call to \(match-end 0) returns the end of the xrefs-prefix."
641 (goto-char (point-max))
642 (re-search-backward pydoc-xrefs-prefix nil t)))