From a7cc43b9e8b55223ad6b711488fbe8c10df6b5c2 Mon Sep 17 00:00:00 2001
From: Barry Warsaw <barry@python.org>
Date: Mon, 22 Apr 2002 17:15:19 +0000
Subject: [PATCH] Skip Montanaro's contribution (slightly mod'd by Barry) to
 provide a "help-on-symbol-at-point" feature which uses pydoc to provide help
 on the symbol under point, if available.

Mods include some name changes, a port to Emacs, binding the command
to C-c C-h, and providing a more informative error message if the
symbol's help can't be found (through use of a nasty bare except).

Note also that py-describe-mode has been moved off of C-c C-h m; it's
now just available on C-c ?

Closes SF patch #545439.
---
 Misc/python-mode.el | 58 +++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 54 insertions(+), 4 deletions(-)

diff --git a/Misc/python-mode.el b/Misc/python-mode.el
index 5a9bff19bef..7ca3b9ba12a 100644
--- a/Misc/python-mode.el
+++ b/Misc/python-mode.el
@@ -498,7 +498,7 @@ Currently-active file is at the head of the list.")
   (define-key py-mode-map "\C-c\C-u"  'py-goto-block-up)
   (define-key py-mode-map "\C-c#"     'py-comment-region)
   (define-key py-mode-map "\C-c?"     'py-describe-mode)
-  (define-key py-mode-map "\C-c\C-hm" 'py-describe-mode)
+  (define-key py-mode-map "\C-c\C-h"  'py-help-at-point)
   (define-key py-mode-map "\e\C-a"    'py-beginning-of-def-or-class)
   (define-key py-mode-map "\e\C-e"    'py-end-of-def-or-class)
   (define-key py-mode-map "\C-c-"     'py-up-exception)
@@ -553,8 +553,7 @@ Currently-active file is at the head of the list.")
 
 (defvar py-mode-syntax-table nil
   "Syntax table used in `python-mode' buffers.")
-(if py-mode-syntax-table
-    nil
+(when (not py-mode-syntax-table)
   (setq py-mode-syntax-table (make-syntax-table))
   (modify-syntax-entry ?\( "()" py-mode-syntax-table)
   (modify-syntax-entry ?\) ")(" py-mode-syntax-table)
@@ -595,10 +594,19 @@ Currently-active file is at the head of the list.")
   (modify-syntax-entry ?\n ">"  py-mode-syntax-table)
   )
 
+;; An auxiliary syntax table which places underscore and dot in the
+;; symbol class for simplicity
+(defvar py-dotted-expression-syntax-table nil
+  "Syntax table used to identify Python dotted expressions.")
+(when (not py-dotted-expression-syntax-table)
+  (setq py-dotted-expression-syntax-table
+	(copy-syntax-table py-mode-syntax-table))
+  (modify-syntax-entry ?_ "_" py-dotted-expression-syntax-table)
+  (modify-syntax-entry ?. "_" py-dotted-expression-syntax-table))
+
 
 
 ;; Utilities
-
 (defmacro py-safe (&rest body)
   "Safely execute BODY, return nil if an error occurred."
   (` (condition-case nil
@@ -2600,6 +2608,48 @@ A `nomenclature' is a fancy way of saying AWordWithMixedCaseNotUnderscores."
   (py-pdbtrack-toggle-stack-tracking 0))
 
 
+
+;; Skip's python-help commands. The guts of this function is stolen
+;; from XEmacs's symbol-near-point, but without the useless
+;; regexp-quote call on the results, nor the interactive bit.  Also,
+;; we've added the temporary syntax table setting, which Skip
+;; originally had broken out into a separate function.  Note that
+;; Emacs doesn't have the original function.
+(defun py-symbol-near-point ()
+  "Return the first textual item to the nearest point."
+  ;; alg stolen from etag.el
+  (save-excursion
+    (with-syntax-table py-dotted-expression-syntax-table
+      (if (or (bobp) (not (memq (char-syntax (char-before)) '(?w ?_))))
+	  (while (not (looking-at "\\sw\\|\\s_\\|\\'"))
+	    (forward-char 1)))
+      (while (looking-at "\\sw\\|\\s_")
+	(forward-char 1))
+      (if (re-search-backward "\\sw\\|\\s_" nil t)
+	  (progn (forward-char 1)
+		 (buffer-substring (point)
+				   (progn (forward-sexp -1)
+					  (while (looking-at "\\s'")
+					    (forward-char 1))
+					  (point))))
+	nil))))
+
+(defun py-help-at-point ()
+  "Get help from Python based on the symbol nearest point."
+  (interactive)
+  (let* ((sym (py-symbol-near-point))
+	 (base (substring sym 0 (or (search "." sym :from-end t) 0)))
+	 cmd)
+    (if (not (equal base ""))
+        (setq cmd (concat "import " base "\n")))
+    (setq cmd (concat "import pydoc\n"
+                      cmd
+		      "try: pydoc.help(" sym ")\n"
+		      "except: print 'No help available on:', \"" sym "\""))
+    (message cmd)
+    (py-execute-string cmd)))
+
+
 
 ;; Documentation functions