lisp/*: Fix typos in docstrings and messages.
[emacs.git] / lisp / progmodes / python.el
blob104ea26689f6f494454923ad3758ac56afe5abfc
1 ;;; python.el --- silly walks for Python -*- coding: iso-8859-1 -*-
3 ;; Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009
4 ;; Free Software Foundation, Inc.
6 ;; Author: Dave Love <fx@gnu.org>
7 ;; Maintainer: FSF
8 ;; Created: Nov 2003
9 ;; Keywords: languages
11 ;; This file is part of GNU Emacs.
13 ;; GNU Emacs is free software: you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published by
15 ;; the Free Software Foundation, either version 3 of the License, or
16 ;; (at your option) any later version.
18 ;; GNU Emacs is distributed in the hope that it will be useful,
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 ;; GNU General Public License for more details.
23 ;; You should have received a copy of the GNU General Public License
24 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
26 ;;; Commentary:
28 ;; Major mode for editing Python, with support for inferior processes.
30 ;; There is another Python mode, python-mode.el:
31 ;; http://launchpad.net/python-mode
32 ;; used by XEmacs, and originally maintained with Python.
33 ;; That isn't covered by an FSF copyright assignment (?), unlike this
34 ;; code, and seems not to be well-maintained for Emacs (though I've
35 ;; submitted fixes). This mode is rather simpler and is better in
36 ;; other ways. In particular, using the syntax functions with text
37 ;; properties maintained by font-lock makes it more correct with
38 ;; arbitrary string and comment contents.
40 ;; This doesn't implement all the facilities of python-mode.el. Some
41 ;; just need doing, e.g. catching exceptions in the inferior Python
42 ;; buffer (but see M-x pdb for debugging). [Actually, the use of
43 ;; `compilation-shell-minor-mode' now is probably enough for that.]
44 ;; Others don't seem appropriate. For instance,
45 ;; `forward-into-nomenclature' should be done separately, since it's
46 ;; not specific to Python, and I've installed a minor mode to do the
47 ;; job properly in Emacs 23. [CC mode 5.31 contains an incompatible
48 ;; feature, `c-subword-mode' which is intended to have a similar
49 ;; effect, but actually only affects word-oriented keybindings.]
51 ;; Other things seem more natural or canonical here, e.g. the
52 ;; {beginning,end}-of-defun implementation dealing with nested
53 ;; definitions, and the inferior mode following `cmuscheme'. (The
54 ;; inferior mode can find the source of errors from
55 ;; `python-send-region' & al via `compilation-shell-minor-mode'.)
56 ;; There is (limited) symbol completion using lookup in Python and
57 ;; Eldoc support also using the inferior process. Successive TABs
58 ;; cycle between possible indentations for the line.
60 ;; Even where it has similar facilities, this mode is incompatible
61 ;; with python-mode.el in some respects. For instance, various key
62 ;; bindings are changed to obey Emacs conventions.
64 ;; TODO: See various Fixmes below.
66 ;; Fixme: This doesn't support (the nascent) Python 3 .
68 ;;; Code:
70 (require 'comint)
72 (eval-when-compile
73 (require 'compile)
74 (require 'hippie-exp))
76 (autoload 'comint-mode "comint")
78 (defgroup python nil
79 "Silly walks in the Python language."
80 :group 'languages
81 :version "22.1"
82 :link '(emacs-commentary-link "python"))
84 ;;;###autoload
85 (add-to-list 'interpreter-mode-alist (cons (purecopy "jython") 'jython-mode))
86 ;;;###autoload
87 (add-to-list 'interpreter-mode-alist (cons (purecopy "python") 'python-mode))
88 ;;;###autoload
89 (add-to-list 'auto-mode-alist (cons (purecopy "\\.py\\'") 'python-mode))
90 (add-to-list 'same-window-buffer-names (purecopy "*Python*"))
92 ;;;; Font lock
94 (defvar python-font-lock-keywords
95 `(,(rx symbol-start
96 ;; From v 2.5 reference, § keywords.
97 ;; def and class dealt with separately below
98 (or "and" "as" "assert" "break" "continue" "del" "elif" "else"
99 "except" "exec" "finally" "for" "from" "global" "if"
100 "import" "in" "is" "lambda" "not" "or" "pass" "print"
101 "raise" "return" "try" "while" "with" "yield"
102 ;; Not real keywords, but close enough to be fontified as such
103 "self" "True" "False")
104 symbol-end)
105 (,(rx symbol-start "None" symbol-end) ; see § Keywords in 2.5 manual
106 . font-lock-constant-face)
107 ;; Definitions
108 (,(rx symbol-start (group "class") (1+ space) (group (1+ (or word ?_))))
109 (1 font-lock-keyword-face) (2 font-lock-type-face))
110 (,(rx symbol-start (group "def") (1+ space) (group (1+ (or word ?_))))
111 (1 font-lock-keyword-face) (2 font-lock-function-name-face))
112 ;; Top-level assignments are worth highlighting.
113 (,(rx line-start (group (1+ (or word ?_))) (0+ space) "=")
114 (1 font-lock-variable-name-face))
115 (,(rx line-start (* (any " \t")) (group "@" (1+ (or word ?_)))) ; decorators
116 (1 font-lock-type-face))
117 ;; Built-ins. (The next three blocks are from
118 ;; `__builtin__.__dict__.keys()' in Python 2.5.1.) These patterns
119 ;; are debateable, but they at least help to spot possible
120 ;; shadowing of builtins.
121 (,(rx symbol-start (or
122 ;; exceptions
123 "ArithmeticError" "AssertionError" "AttributeError"
124 "BaseException" "DeprecationWarning" "EOFError"
125 "EnvironmentError" "Exception" "FloatingPointError"
126 "FutureWarning" "GeneratorExit" "IOError" "ImportError"
127 "ImportWarning" "IndentationError" "IndexError" "KeyError"
128 "KeyboardInterrupt" "LookupError" "MemoryError" "NameError"
129 "NotImplemented" "NotImplementedError" "OSError"
130 "OverflowError" "PendingDeprecationWarning" "ReferenceError"
131 "RuntimeError" "RuntimeWarning" "StandardError"
132 "StopIteration" "SyntaxError" "SyntaxWarning" "SystemError"
133 "SystemExit" "TabError" "TypeError" "UnboundLocalError"
134 "UnicodeDecodeError" "UnicodeEncodeError" "UnicodeError"
135 "UnicodeTranslateError" "UnicodeWarning" "UserWarning"
136 "ValueError" "Warning" "ZeroDivisionError") symbol-end)
137 . font-lock-type-face)
138 (,(rx (or line-start (not (any ". \t"))) (* (any " \t")) symbol-start
139 (group (or
140 ;; callable built-ins, fontified when not appearing as
141 ;; object attributes
142 "abs" "all" "any" "apply" "basestring" "bool" "buffer" "callable"
143 "chr" "classmethod" "cmp" "coerce" "compile" "complex"
144 "copyright" "credits" "delattr" "dict" "dir" "divmod"
145 "enumerate" "eval" "execfile" "exit" "file" "filter" "float"
146 "frozenset" "getattr" "globals" "hasattr" "hash" "help"
147 "hex" "id" "input" "int" "intern" "isinstance" "issubclass"
148 "iter" "len" "license" "list" "locals" "long" "map" "max"
149 "min" "object" "oct" "open" "ord" "pow" "property" "quit"
150 "range" "raw_input" "reduce" "reload" "repr" "reversed"
151 "round" "set" "setattr" "slice" "sorted" "staticmethod"
152 "str" "sum" "super" "tuple" "type" "unichr" "unicode" "vars"
153 "xrange" "zip")) symbol-end)
154 (1 font-lock-builtin-face))
155 (,(rx symbol-start (or
156 ;; other built-ins
157 "True" "False" "None" "Ellipsis"
158 "_" "__debug__" "__doc__" "__import__" "__name__") symbol-end)
159 . font-lock-builtin-face)))
161 (defconst python-font-lock-syntactic-keywords
162 ;; Make outer chars of matching triple-quote sequences into generic
163 ;; string delimiters. Fixme: Is there a better way?
164 ;; First avoid a sequence preceded by an odd number of backslashes.
165 `((,(rx (not (any ?\\))
166 ?\\ (* (and ?\\ ?\\))
167 (group (syntax string-quote))
168 (backref 1)
169 (group (backref 1)))
170 (2 ,(string-to-syntax "\""))) ; dummy
171 (,(rx (group (optional (any "uUrR"))) ; prefix gets syntax property
172 (optional (any "rR")) ; possible second prefix
173 (group (syntax string-quote)) ; maybe gets property
174 (backref 2) ; per first quote
175 (group (backref 2))) ; maybe gets property
176 (1 (python-quote-syntax 1))
177 (2 (python-quote-syntax 2))
178 (3 (python-quote-syntax 3)))
179 ;; This doesn't really help.
180 ;;; (,(rx (and ?\\ (group ?\n))) (1 " "))
183 (defun python-quote-syntax (n)
184 "Put `syntax-table' property correctly on triple quote.
185 Used for syntactic keywords. N is the match number (1, 2 or 3)."
186 ;; Given a triple quote, we have to check the context to know
187 ;; whether this is an opening or closing triple or whether it's
188 ;; quoted anyhow, and should be ignored. (For that we need to do
189 ;; the same job as `syntax-ppss' to be correct and it seems to be OK
190 ;; to use it here despite initial worries.) We also have to sort
191 ;; out a possible prefix -- well, we don't _have_ to, but I think it
192 ;; should be treated as part of the string.
194 ;; Test cases:
195 ;; ur"""ar""" x='"' # """
196 ;; x = ''' """ ' a
197 ;; '''
198 ;; x '"""' x """ \"""" x
199 (save-excursion
200 (goto-char (match-beginning 0))
201 (cond
202 ;; Consider property for the last char if in a fenced string.
203 ((= n 3)
204 (let* ((font-lock-syntactic-keywords nil)
205 (syntax (syntax-ppss)))
206 (when (eq t (nth 3 syntax)) ; after unclosed fence
207 (goto-char (nth 8 syntax)) ; fence position
208 (skip-chars-forward "uUrR") ; skip any prefix
209 ;; Is it a matching sequence?
210 (if (eq (char-after) (char-after (match-beginning 2)))
211 (eval-when-compile (string-to-syntax "|"))))))
212 ;; Consider property for initial char, accounting for prefixes.
213 ((or (and (= n 2) ; leading quote (not prefix)
214 (= (match-beginning 1) (match-end 1))) ; prefix is null
215 (and (= n 1) ; prefix
216 (/= (match-beginning 1) (match-end 1)))) ; non-empty
217 (let ((font-lock-syntactic-keywords nil))
218 (unless (eq 'string (syntax-ppss-context (syntax-ppss)))
219 (eval-when-compile (string-to-syntax "|")))))
220 ;; Otherwise (we're in a non-matching string) the property is
221 ;; nil, which is OK.
224 ;; This isn't currently in `font-lock-defaults' as probably not worth
225 ;; it -- we basically only mess with a few normally-symbol characters.
227 ;; (defun python-font-lock-syntactic-face-function (state)
228 ;; "`font-lock-syntactic-face-function' for Python mode.
229 ;; Returns the string or comment face as usual, with side effect of putting
230 ;; a `syntax-table' property on the inside of the string or comment which is
231 ;; the standard syntax table."
232 ;; (if (nth 3 state)
233 ;; (save-excursion
234 ;; (goto-char (nth 8 state))
235 ;; (condition-case nil
236 ;; (forward-sexp)
237 ;; (error nil))
238 ;; (put-text-property (1+ (nth 8 state)) (1- (point))
239 ;; 'syntax-table (standard-syntax-table))
240 ;; 'font-lock-string-face)
241 ;; (put-text-property (1+ (nth 8 state)) (line-end-position)
242 ;; 'syntax-table (standard-syntax-table))
243 ;; 'font-lock-comment-face))
245 ;;;; Keymap and syntax
247 (defvar python-mode-map
248 (let ((map (make-sparse-keymap)))
249 ;; Mostly taken from python-mode.el.
250 (define-key map ":" 'python-electric-colon)
251 (define-key map "\177" 'python-backspace)
252 (define-key map "\C-c<" 'python-shift-left)
253 (define-key map "\C-c>" 'python-shift-right)
254 (define-key map "\C-c\C-k" 'python-mark-block)
255 (define-key map "\C-c\C-d" 'python-pdbtrack-toggle-stack-tracking)
256 (define-key map "\C-c\C-n" 'python-next-statement)
257 (define-key map "\C-c\C-p" 'python-previous-statement)
258 (define-key map "\C-c\C-u" 'python-beginning-of-block)
259 (define-key map "\C-c\C-f" 'python-describe-symbol)
260 (define-key map "\C-c\C-w" 'python-check)
261 (define-key map "\C-c\C-v" 'python-check) ; a la sgml-mode
262 (define-key map "\C-c\C-s" 'python-send-string)
263 (define-key map [?\C-\M-x] 'python-send-defun)
264 (define-key map "\C-c\C-r" 'python-send-region)
265 (define-key map "\C-c\M-r" 'python-send-region-and-go)
266 (define-key map "\C-c\C-c" 'python-send-buffer)
267 (define-key map "\C-c\C-z" 'python-switch-to-python)
268 (define-key map "\C-c\C-m" 'python-load-file)
269 (define-key map "\C-c\C-l" 'python-load-file) ; a la cmuscheme
270 (substitute-key-definition 'complete-symbol 'completion-at-point
271 map global-map)
272 (define-key map "\C-c\C-i" 'python-find-imports)
273 (define-key map "\C-c\C-t" 'python-expand-template)
274 (easy-menu-define python-menu map "Python Mode menu"
275 `("Python"
276 :help "Python-specific Features"
277 ["Shift region left" python-shift-left :active mark-active
278 :help "Shift by a single indentation step"]
279 ["Shift region right" python-shift-right :active mark-active
280 :help "Shift by a single indentation step"]
282 ["Mark block" python-mark-block
283 :help "Mark innermost block around point"]
284 ["Mark def/class" mark-defun
285 :help "Mark innermost definition around point"]
287 ["Start of block" python-beginning-of-block
288 :help "Go to start of innermost definition around point"]
289 ["End of block" python-end-of-block
290 :help "Go to end of innermost definition around point"]
291 ["Start of def/class" beginning-of-defun
292 :help "Go to start of innermost definition around point"]
293 ["End of def/class" end-of-defun
294 :help "Go to end of innermost definition around point"]
296 ("Templates..."
297 :help "Expand templates for compound statements"
298 :filter (lambda (&rest junk)
299 (abbrev-table-menu python-mode-abbrev-table)))
301 ["Start interpreter" python-shell
302 :help "Run `inferior' Python in separate buffer"]
303 ["Import/reload file" python-load-file
304 :help "Load into inferior Python session"]
305 ["Eval buffer" python-send-buffer
306 :help "Evaluate buffer en bloc in inferior Python session"]
307 ["Eval region" python-send-region :active mark-active
308 :help "Evaluate region en bloc in inferior Python session"]
309 ["Eval def/class" python-send-defun
310 :help "Evaluate current definition in inferior Python session"]
311 ["Switch to interpreter" python-switch-to-python
312 :help "Switch to inferior Python buffer"]
313 ["Set default process" python-set-proc
314 :help "Make buffer's inferior process the default"
315 :active (buffer-live-p python-buffer)]
316 ["Check file" python-check :help "Run pychecker"]
317 ["Debugger" pdb :help "Run pdb under GUD"]
319 ["Help on symbol" python-describe-symbol
320 :help "Use pydoc on symbol at point"]
321 ["Complete symbol" completion-at-point
322 :help "Complete (qualified) symbol before point"]
323 ["Find function" python-find-function
324 :help "Try to find source definition of function at point"]
325 ["Update imports" python-find-imports
326 :help "Update list of top-level imports for completion"]))
327 map))
328 ;; Fixme: add toolbar stuff for useful things like symbol help, send
329 ;; region, at least. (Shouldn't be specific to Python, obviously.)
330 ;; eric has items including: (un)indent, (un)comment, restart script,
331 ;; run script, debug script; also things for profiling, unit testing.
333 (defvar python-shell-map
334 (let ((map (copy-keymap comint-mode-map)))
335 (define-key map [tab] 'tab-to-tab-stop)
336 (define-key map "\C-c-" 'py-up-exception)
337 (define-key map "\C-c=" 'py-down-exception)
338 map)
339 "Keymap used in *Python* shell buffers.")
341 (defvar python-mode-syntax-table
342 (let ((table (make-syntax-table)))
343 ;; Give punctuation syntax to ASCII that normally has symbol
344 ;; syntax or has word syntax and isn't a letter.
345 (let ((symbol (string-to-syntax "_"))
346 (sst (standard-syntax-table)))
347 (dotimes (i 128)
348 (unless (= i ?_)
349 (if (equal symbol (aref sst i))
350 (modify-syntax-entry i "." table)))))
351 (modify-syntax-entry ?$ "." table)
352 (modify-syntax-entry ?% "." table)
353 ;; exceptions
354 (modify-syntax-entry ?# "<" table)
355 (modify-syntax-entry ?\n ">" table)
356 (modify-syntax-entry ?' "\"" table)
357 (modify-syntax-entry ?` "$" table)
358 table))
360 ;;;; Utility stuff
362 (defsubst python-in-string/comment ()
363 "Return non-nil if point is in a Python literal (a comment or string)."
364 ;; We don't need to save the match data.
365 (nth 8 (syntax-ppss)))
367 (defconst python-space-backslash-table
368 (let ((table (copy-syntax-table python-mode-syntax-table)))
369 (modify-syntax-entry ?\\ " " table)
370 table)
371 "`python-mode-syntax-table' with backslash given whitespace syntax.")
373 (defun python-skip-comments/blanks (&optional backward)
374 "Skip comments and blank lines.
375 BACKWARD non-nil means go backwards, otherwise go forwards.
376 Backslash is treated as whitespace so that continued blank lines
377 are skipped. Doesn't move out of comments -- should be outside
378 or at end of line."
379 (let ((arg (if backward
380 ;; If we're in a comment (including on the trailing
381 ;; newline), forward-comment doesn't move backwards out
382 ;; of it. Don't set the syntax table round this bit!
383 (let ((syntax (syntax-ppss)))
384 (if (nth 4 syntax)
385 (goto-char (nth 8 syntax)))
386 (- (point-max)))
387 (point-max))))
388 (with-syntax-table python-space-backslash-table
389 (forward-comment arg))))
391 (defun python-backslash-continuation-line-p ()
392 "Non-nil if preceding line ends with backslash that is not in a comment."
393 (and (eq ?\\ (char-before (line-end-position 0)))
394 (not (syntax-ppss-context (syntax-ppss)))))
396 (defun python-continuation-line-p ()
397 "Return non-nil if current line continues a previous one.
398 The criteria are that the previous line ends in a backslash outside
399 comments and strings, or that point is within brackets/parens."
400 (or (python-backslash-continuation-line-p)
401 (let ((depth (syntax-ppss-depth
402 (save-excursion ; syntax-ppss with arg changes point
403 (syntax-ppss (line-beginning-position))))))
404 (or (> depth 0)
405 (if (< depth 0) ; Unbalanced brackets -- act locally
406 (save-excursion
407 (condition-case ()
408 (progn (backward-up-list) t) ; actually within brackets
409 (error nil))))))))
411 (defun python-comment-line-p ()
412 "Return non-nil if and only if current line has only a comment."
413 (save-excursion
414 (end-of-line)
415 (when (eq 'comment (syntax-ppss-context (syntax-ppss)))
416 (back-to-indentation)
417 (looking-at (rx (or (syntax comment-start) line-end))))))
419 (defun python-blank-line-p ()
420 "Return non-nil if and only if current line is blank."
421 (save-excursion
422 (beginning-of-line)
423 (looking-at "\\s-*$")))
425 (defun python-beginning-of-string ()
426 "Go to beginning of string around point.
427 Do nothing if not in string."
428 (let ((state (syntax-ppss)))
429 (when (eq 'string (syntax-ppss-context state))
430 (goto-char (nth 8 state)))))
432 (defun python-open-block-statement-p (&optional bos)
433 "Return non-nil if statement at point opens a block.
434 BOS non-nil means point is known to be at beginning of statement."
435 (save-excursion
436 (unless bos (python-beginning-of-statement))
437 (looking-at (rx (and (or "if" "else" "elif" "while" "for" "def"
438 "class" "try" "except" "finally" "with")
439 symbol-end)))))
441 (defun python-close-block-statement-p (&optional bos)
442 "Return non-nil if current line is a statement closing a block.
443 BOS non-nil means point is at beginning of statement.
444 The criteria are that the line isn't a comment or in string and
445 starts with keyword `raise', `break', `continue' or `pass'."
446 (save-excursion
447 (unless bos (python-beginning-of-statement))
448 (back-to-indentation)
449 (looking-at (rx (or "return" "raise" "break" "continue" "pass")
450 symbol-end))))
452 (defun python-outdent-p ()
453 "Return non-nil if current line should outdent a level."
454 (save-excursion
455 (back-to-indentation)
456 (and (looking-at (rx (and (or "else" "finally" "except" "elif")
457 symbol-end)))
458 (not (python-in-string/comment))
459 ;; Ensure there's a previous statement and move to it.
460 (zerop (python-previous-statement))
461 (not (python-close-block-statement-p t))
462 ;; Fixme: check this
463 (not (python-open-block-statement-p)))))
465 ;;;; Indentation.
467 (defcustom python-indent 4
468 "Number of columns for a unit of indentation in Python mode.
469 See also `\\[python-guess-indent]'"
470 :group 'python
471 :type 'integer)
472 (put 'python-indent 'safe-local-variable 'integerp)
474 (defcustom python-guess-indent t
475 "Non-nil means Python mode guesses `python-indent' for the buffer."
476 :type 'boolean
477 :group 'python)
479 (defcustom python-indent-string-contents t
480 "Non-nil means indent contents of multi-line strings together.
481 This means indent them the same as the preceding non-blank line.
482 Otherwise preserve their indentation.
484 This only applies to `doc' strings, i.e. those that form statements;
485 the indentation is preserved in others."
486 :type '(choice (const :tag "Align with preceding" t)
487 (const :tag "Preserve indentation" nil))
488 :group 'python)
490 (defcustom python-honour-comment-indentation nil
491 "Non-nil means indent relative to preceding comment line.
492 Only do this for comments where the leading comment character is
493 followed by space. This doesn't apply to comment lines, which
494 are always indented in lines with preceding comments."
495 :type 'boolean
496 :group 'python)
498 (defcustom python-continuation-offset 4
499 "Number of columns of additional indentation for continuation lines.
500 Continuation lines follow a backslash-terminated line starting a
501 statement."
502 :group 'python
503 :type 'integer)
506 (defcustom python-default-interpreter 'cpython
507 "*Which Python interpreter is used by default.
508 The value for this variable can be either `cpython' or `jpython'.
510 When the value is `cpython', the variables `python-python-command' and
511 `python-python-command-args' are consulted to determine the interpreter
512 and arguments to use.
514 When the value is `jpython', the variables `python-jpython-command' and
515 `python-jpython-command-args' are consulted to determine the interpreter
516 and arguments to use.
518 Note that this variable is consulted only the first time that a Python
519 mode buffer is visited during an Emacs session. After that, use
520 \\[python-toggle-shells] to change the interpreter shell."
521 :type '(choice (const :tag "Python (a.k.a. CPython)" cpython)
522 (const :tag "JPython" jpython))
523 :group 'python)
525 (defcustom python-python-command-args '("-i")
526 "*List of string arguments to be used when starting a Python shell."
527 :type '(repeat string)
528 :group 'python)
530 (defcustom python-jython-command-args '("-i")
531 "*List of string arguments to be used when starting a Jython shell."
532 :type '(repeat string)
533 :group 'python
534 :tag "JPython Command Args")
536 ;; for toggling between CPython and JPython
537 (defvar python-which-shell nil)
538 (defvar python-which-args python-python-command-args)
539 (defvar python-which-bufname "Python")
540 (make-variable-buffer-local 'python-which-shell)
541 (make-variable-buffer-local 'python-which-args)
542 (make-variable-buffer-local 'python-which-bufname)
544 (defcustom python-pdbtrack-do-tracking-p t
545 "*Controls whether the pdbtrack feature is enabled or not.
547 When non-nil, pdbtrack is enabled in all comint-based buffers,
548 e.g. shell interaction buffers and the *Python* buffer.
550 When using pdb to debug a Python program, pdbtrack notices the
551 pdb prompt and presents the line in the source file where the
552 program is stopped in a pop-up buffer. It's similar to what
553 gud-mode does for debugging C programs with gdb, but without
554 having to restart the program."
555 :type 'boolean
556 :group 'python)
557 (make-variable-buffer-local 'python-pdbtrack-do-tracking-p)
559 (defcustom python-pdbtrack-minor-mode-string " PDB"
560 "*Minor-mode sign to be displayed when pdbtrack is active."
561 :type 'string
562 :group 'python)
564 ;; Add a designator to the minor mode strings
565 (or (assq 'python-pdbtrack-is-tracking-p minor-mode-alist)
566 (push '(python-pdbtrack-is-tracking-p python-pdbtrack-minor-mode-string)
567 minor-mode-alist))
569 ;; Bind python-file-queue before installing the kill-emacs-hook.
570 (defvar python-file-queue nil
571 "Queue of Python temp files awaiting execution.
572 Currently-active file is at the head of the list.")
574 (defvar python-pdbtrack-is-tracking-p nil)
576 (defconst python-pdbtrack-stack-entry-regexp
577 "^> \\(.*\\)(\\([0-9]+\\))\\([?a-zA-Z0-9_]+\\)()"
578 "Regular expression pdbtrack uses to find a stack trace entry.")
580 (defconst python-pdbtrack-input-prompt "\n[(<]*[Pp]db[>)]+ "
581 "Regular expression pdbtrack uses to recognize a pdb prompt.")
583 (defconst python-pdbtrack-track-range 10000
584 "Max number of characters from end of buffer to search for stack entry.")
586 (defun python-guess-indent ()
587 "Guess step for indentation of current buffer.
588 Set `python-indent' locally to the value guessed."
589 (interactive)
590 (save-excursion
591 (save-restriction
592 (widen)
593 (goto-char (point-min))
594 (let (done indent)
595 (while (and (not done) (not (eobp)))
596 (when (and (re-search-forward (rx ?: (0+ space)
597 (or (syntax comment-start)
598 line-end))
599 nil 'move)
600 (python-open-block-statement-p))
601 (save-excursion
602 (python-beginning-of-statement)
603 (let ((initial (current-indentation)))
604 (if (zerop (python-next-statement))
605 (setq indent (- (current-indentation) initial)))
606 (if (and indent (>= indent 2) (<= indent 8)) ; sanity check
607 (setq done t))))))
608 (when done
609 (when (/= indent (default-value 'python-indent))
610 (set (make-local-variable 'python-indent) indent)
611 (unless (= tab-width python-indent)
612 (setq indent-tabs-mode nil)))
613 indent)))))
615 ;; Alist of possible indentations and start of statement they would
616 ;; close. Used in indentation cycling (below).
617 (defvar python-indent-list nil
618 "Internal use.")
619 ;; Length of the above
620 (defvar python-indent-list-length nil
621 "Internal use.")
622 ;; Current index into the alist.
623 (defvar python-indent-index nil
624 "Internal use.")
626 (defun python-calculate-indentation ()
627 "Calculate Python indentation for line at point."
628 (setq python-indent-list nil
629 python-indent-list-length 1)
630 (save-excursion
631 (beginning-of-line)
632 (let ((syntax (syntax-ppss))
633 start)
634 (cond
635 ((eq 'string (syntax-ppss-context syntax)) ; multi-line string
636 (if (not python-indent-string-contents)
637 (current-indentation)
638 ;; Only respect `python-indent-string-contents' in doc
639 ;; strings (defined as those which form statements).
640 (if (not (save-excursion
641 (python-beginning-of-statement)
642 (looking-at (rx (or (syntax string-delimiter)
643 (syntax string-quote))))))
644 (current-indentation)
645 ;; Find indentation of preceding non-blank line within string.
646 (setq start (nth 8 syntax))
647 (forward-line -1)
648 (while (and (< start (point)) (looking-at "\\s-*$"))
649 (forward-line -1))
650 (current-indentation))))
651 ((python-continuation-line-p) ; after backslash, or bracketed
652 (let ((point (point))
653 (open-start (cadr syntax))
654 (backslash (python-backslash-continuation-line-p))
655 (colon (eq ?: (char-before (1- (line-beginning-position))))))
656 (if open-start
657 ;; Inside bracketed expression.
658 (progn
659 (goto-char (1+ open-start))
660 ;; Look for first item in list (preceding point) and
661 ;; align with it, if found.
662 (if (with-syntax-table python-space-backslash-table
663 (let ((parse-sexp-ignore-comments t))
664 (condition-case ()
665 (progn (forward-sexp)
666 (backward-sexp)
667 (< (point) point))
668 (error nil))))
669 ;; Extra level if we're backslash-continued or
670 ;; following a key.
671 (if (or backslash colon)
672 (+ python-indent (current-column))
673 (current-column))
674 ;; Otherwise indent relative to statement start, one
675 ;; level per bracketing level.
676 (goto-char (1+ open-start))
677 (python-beginning-of-statement)
678 (+ (current-indentation) (* (car syntax) python-indent))))
679 ;; Otherwise backslash-continued.
680 (forward-line -1)
681 (if (python-continuation-line-p)
682 ;; We're past first continuation line. Align with
683 ;; previous line.
684 (current-indentation)
685 ;; First continuation line. Indent one step, with an
686 ;; extra one if statement opens a block.
687 (python-beginning-of-statement)
688 (+ (current-indentation) python-continuation-offset
689 (if (python-open-block-statement-p t)
690 python-indent
691 0))))))
692 ((bobp) 0)
693 ;; Fixme: Like python-mode.el; not convinced by this.
694 ((looking-at (rx (0+ space) (syntax comment-start)
695 (not (any " \t\n")))) ; non-indentable comment
696 (current-indentation))
697 ((and python-honour-comment-indentation
698 ;; Back over whitespace, newlines, non-indentable comments.
699 (catch 'done
700 (while (cond ((bobp) nil)
701 ((not (forward-comment -1))
702 nil) ; not at comment start
703 ;; Now at start of comment -- trailing one?
704 ((/= (current-column) (current-indentation))
705 nil)
706 ;; Indentable comment, like python-mode.el?
707 ((and (looking-at (rx (syntax comment-start)
708 (or space line-end)))
709 (/= 0 (current-column)))
710 (throw 'done (current-column)))
711 ;; Else skip it (loop).
712 (t))))))
714 (python-indentation-levels)
715 ;; Prefer to indent comments with an immediately-following
716 ;; statement, e.g.
717 ;; ...
718 ;; # ...
719 ;; def ...
720 (when (and (> python-indent-list-length 1)
721 (python-comment-line-p))
722 (forward-line)
723 (unless (python-comment-line-p)
724 (let ((elt (assq (current-indentation) python-indent-list)))
725 (setq python-indent-list
726 (nconc (delete elt python-indent-list)
727 (list elt))))))
728 (caar (last python-indent-list)))))))
730 ;;;; Cycling through the possible indentations with successive TABs.
732 ;; These don't need to be buffer-local since they're only relevant
733 ;; during a cycle.
735 (defun python-initial-text ()
736 "Text of line following indentation and ignoring any trailing comment."
737 (save-excursion
738 (buffer-substring (progn
739 (back-to-indentation)
740 (point))
741 (progn
742 (end-of-line)
743 (forward-comment -1)
744 (point)))))
746 (defconst python-block-pairs
747 '(("else" "if" "elif" "while" "for" "try" "except")
748 ("elif" "if" "elif")
749 ("except" "try" "except")
750 ("finally" "try" "except"))
751 "Alist of keyword matches.
752 The car of an element is a keyword introducing a statement which
753 can close a block opened by a keyword in the cdr.")
755 (defun python-first-word ()
756 "Return first word (actually symbol) on the line."
757 (save-excursion
758 (back-to-indentation)
759 (current-word t)))
761 (defun python-indentation-levels ()
762 "Return a list of possible indentations for this line.
763 It is assumed not to be a continuation line or in a multi-line string.
764 Includes the default indentation and those which would close all
765 enclosing blocks. Elements of the list are actually pairs:
766 \(INDENTATION . TEXT), where TEXT is the initial text of the
767 corresponding block opening (or nil)."
768 (save-excursion
769 (let ((initial "")
770 levels indent)
771 ;; Only one possibility immediately following a block open
772 ;; statement, assuming it doesn't have a `suite' on the same line.
773 (cond
774 ((save-excursion (and (python-previous-statement)
775 (python-open-block-statement-p t)
776 (setq indent (current-indentation))
777 ;; Check we don't have something like:
778 ;; if ...: ...
779 (if (progn (python-end-of-statement)
780 (python-skip-comments/blanks t)
781 (eq ?: (char-before)))
782 (setq indent (+ python-indent indent)))))
783 (push (cons indent initial) levels))
784 ;; Only one possibility for comment line immediately following
785 ;; another.
786 ((save-excursion
787 (when (python-comment-line-p)
788 (forward-line -1)
789 (if (python-comment-line-p)
790 (push (cons (current-indentation) initial) levels)))))
791 ;; Fixme: Maybe have a case here which indents (only) first
792 ;; line after a lambda.
794 (let ((start (car (assoc (python-first-word) python-block-pairs))))
795 (python-previous-statement)
796 ;; Is this a valid indentation for the line of interest?
797 (unless (or (if start ; potentially only outdentable
798 ;; Check for things like:
799 ;; if ...: ...
800 ;; else ...:
801 ;; where the second line need not be outdented.
802 (not (member (python-first-word)
803 (cdr (assoc start
804 python-block-pairs)))))
805 ;; Not sensible to indent to the same level as
806 ;; previous `return' &c.
807 (python-close-block-statement-p))
808 (push (cons (current-indentation) (python-initial-text))
809 levels))
810 (while (python-beginning-of-block)
811 (when (or (not start)
812 (member (python-first-word)
813 (cdr (assoc start python-block-pairs))))
814 (push (cons (current-indentation) (python-initial-text))
815 levels))))))
816 (prog1 (or levels (setq levels '((0 . ""))))
817 (setq python-indent-list levels
818 python-indent-list-length (length python-indent-list))))))
820 ;; This is basically what `python-indent-line' would be if we didn't
821 ;; do the cycling.
822 (defun python-indent-line-1 (&optional leave)
823 "Subroutine of `python-indent-line'.
824 Does non-repeated indentation. LEAVE non-nil means leave
825 indentation if it is valid, i.e. one of the positions returned by
826 `python-calculate-indentation'."
827 (let ((target (python-calculate-indentation))
828 (pos (- (point-max) (point))))
829 (if (or (= target (current-indentation))
830 ;; Maybe keep a valid indentation.
831 (and leave python-indent-list
832 (assq (current-indentation) python-indent-list)))
833 (if (< (current-column) (current-indentation))
834 (back-to-indentation))
835 (beginning-of-line)
836 (delete-horizontal-space)
837 (indent-to target)
838 (if (> (- (point-max) pos) (point))
839 (goto-char (- (point-max) pos))))))
841 (defun python-indent-line ()
842 "Indent current line as Python code.
843 When invoked via `indent-for-tab-command', cycle through possible
844 indentations for current line. The cycle is broken by a command
845 different from `indent-for-tab-command', i.e. successive TABs do
846 the cycling."
847 (interactive)
848 (if (and (eq this-command 'indent-for-tab-command)
849 (eq last-command this-command))
850 (if (= 1 python-indent-list-length)
851 (message "Sole indentation")
852 (progn (setq python-indent-index
853 (% (1+ python-indent-index) python-indent-list-length))
854 (beginning-of-line)
855 (delete-horizontal-space)
856 (indent-to (car (nth python-indent-index python-indent-list)))
857 (if (python-block-end-p)
858 (let ((text (cdr (nth python-indent-index
859 python-indent-list))))
860 (if text
861 (message "Closes: %s" text))))))
862 (python-indent-line-1)
863 (setq python-indent-index (1- python-indent-list-length))))
865 (defun python-indent-region (start end)
866 "`indent-region-function' for Python.
867 Leaves validly-indented lines alone, i.e. doesn't indent to
868 another valid position."
869 (save-excursion
870 (goto-char end)
871 (setq end (point-marker))
872 (goto-char start)
873 (or (bolp) (forward-line 1))
874 (while (< (point) end)
875 (or (and (bolp) (eolp))
876 (python-indent-line-1 t))
877 (forward-line 1))
878 (move-marker end nil)))
880 (defun python-block-end-p ()
881 "Non-nil if this is a line in a statement closing a block,
882 or a blank line indented to where it would close a block."
883 (and (not (python-comment-line-p))
884 (or (python-close-block-statement-p t)
885 (< (current-indentation)
886 (save-excursion
887 (python-previous-statement)
888 (current-indentation))))))
890 ;;;; Movement.
892 ;; Fixme: Define {for,back}ward-sexp-function? Maybe skip units like
893 ;; block, statement, depending on context.
895 (defun python-beginning-of-defun ()
896 "`beginning-of-defun-function' for Python.
897 Finds beginning of innermost nested class or method definition.
898 Returns the name of the definition found at the end, or nil if
899 reached start of buffer."
900 (let ((ci (current-indentation))
901 (def-re (rx line-start (0+ space) (or "def" "class") (1+ space)
902 (group (1+ (or word (syntax symbol))))))
903 found lep) ;; def-line
904 (if (python-comment-line-p)
905 (setq ci most-positive-fixnum))
906 (while (and (not (bobp)) (not found))
907 ;; Treat bol at beginning of function as outside function so
908 ;; that successive C-M-a makes progress backwards.
909 ;;(setq def-line (looking-at def-re))
910 (unless (bolp) (end-of-line))
911 (setq lep (line-end-position))
912 (if (and (re-search-backward def-re nil 'move)
913 ;; Must be less indented or matching top level, or
914 ;; equally indented if we started on a definition line.
915 (let ((in (current-indentation)))
916 (or (and (zerop ci) (zerop in))
917 (= lep (line-end-position)) ; on initial line
918 ;; Not sure why it was like this -- fails in case of
919 ;; last internal function followed by first
920 ;; non-def statement of the main body.
921 ;; (and def-line (= in ci))
922 (= in ci)
923 (< in ci)))
924 (not (python-in-string/comment)))
925 (setq found t)))
926 found))
928 (defun python-end-of-defun ()
929 "`end-of-defun-function' for Python.
930 Finds end of innermost nested class or method definition."
931 (let ((orig (point))
932 (pattern (rx line-start (0+ space) (or "def" "class") space)))
933 ;; Go to start of current block and check whether it's at top
934 ;; level. If it is, and not a block start, look forward for
935 ;; definition statement.
936 (when (python-comment-line-p)
937 (end-of-line)
938 (forward-comment most-positive-fixnum))
939 (if (not (python-open-block-statement-p))
940 (python-beginning-of-block))
941 (if (zerop (current-indentation))
942 (unless (python-open-block-statement-p)
943 (while (and (re-search-forward pattern nil 'move)
944 (python-in-string/comment))) ; just loop
945 (unless (eobp)
946 (beginning-of-line)))
947 ;; Don't move before top-level statement that would end defun.
948 (end-of-line)
949 (python-beginning-of-defun))
950 ;; If we got to the start of buffer, look forward for
951 ;; definition statement.
952 (if (and (bobp) (not (looking-at "def\\|class")))
953 (while (and (not (eobp))
954 (re-search-forward pattern nil 'move)
955 (python-in-string/comment)))) ; just loop
956 ;; We're at a definition statement (or end-of-buffer).
957 (unless (eobp)
958 (python-end-of-block)
959 ;; Count trailing space in defun (but not trailing comments).
960 (skip-syntax-forward " >")
961 (unless (eobp) ; e.g. missing final newline
962 (beginning-of-line)))
963 ;; Catch pathological cases like this, where the beginning-of-defun
964 ;; skips to a definition we're not in:
965 ;; if ...:
966 ;; ...
967 ;; else:
968 ;; ... # point here
969 ;; ...
970 ;; def ...
971 (if (< (point) orig)
972 (goto-char (point-max)))))
974 (defun python-beginning-of-statement ()
975 "Go to start of current statement.
976 Accounts for continuation lines, multi-line strings, and
977 multi-line bracketed expressions."
978 (beginning-of-line)
979 (python-beginning-of-string)
980 (let (point)
981 (while (and (python-continuation-line-p)
982 (if point
983 (< (point) point)
985 (beginning-of-line)
986 (if (python-backslash-continuation-line-p)
987 (progn
988 (forward-line -1)
989 (while (python-backslash-continuation-line-p)
990 (forward-line -1)))
991 (python-beginning-of-string)
992 (python-skip-out))
993 (setq point (point))))
994 (back-to-indentation))
996 (defun python-skip-out (&optional forward syntax)
997 "Skip out of any nested brackets.
998 Skip forward if FORWARD is non-nil, else backward.
999 If SYNTAX is non-nil it is the state returned by `syntax-ppss' at point.
1000 Return non-nil if and only if skipping was done."
1001 (let ((depth (syntax-ppss-depth (or syntax (syntax-ppss))))
1002 (forward (if forward -1 1)))
1003 (unless (zerop depth)
1004 (if (> depth 0)
1005 ;; Skip forward out of nested brackets.
1006 (condition-case () ; beware invalid syntax
1007 (progn (backward-up-list (* forward depth)) t)
1008 (error nil))
1009 ;; Invalid syntax (too many closed brackets).
1010 ;; Skip out of as many as possible.
1011 (let (done)
1012 (while (condition-case ()
1013 (progn (backward-up-list forward)
1014 (setq done t))
1015 (error nil)))
1016 done)))))
1018 (defun python-end-of-statement ()
1019 "Go to the end of the current statement and return point.
1020 Usually this is the start of the next line, but if this is a
1021 multi-line statement we need to skip over the continuation lines.
1022 On a comment line, go to end of line."
1023 (end-of-line)
1024 (while (let (comment)
1025 ;; Move past any enclosing strings and sexps, or stop if
1026 ;; we're in a comment.
1027 (while (let ((s (syntax-ppss)))
1028 (cond ((eq 'comment (syntax-ppss-context s))
1029 (setq comment t)
1030 nil)
1031 ((eq 'string (syntax-ppss-context s))
1032 ;; Go to start of string and skip it.
1033 (let ((pos (point)))
1034 (goto-char (nth 8 s))
1035 (condition-case () ; beware invalid syntax
1036 (progn (forward-sexp) t)
1037 ;; If there's a mismatched string, make sure
1038 ;; we still overall move *forward*.
1039 (error (goto-char pos) (end-of-line)))))
1040 ((python-skip-out t s))))
1041 (end-of-line))
1042 (unless comment
1043 (eq ?\\ (char-before)))) ; Line continued?
1044 (end-of-line 2)) ; Try next line.
1045 (point))
1047 (defun python-previous-statement (&optional count)
1048 "Go to start of previous statement.
1049 With argument COUNT, do it COUNT times. Stop at beginning of buffer.
1050 Return count of statements left to move."
1051 (interactive "p")
1052 (unless count (setq count 1))
1053 (if (< count 0)
1054 (python-next-statement (- count))
1055 (python-beginning-of-statement)
1056 (while (and (> count 0) (not (bobp)))
1057 (python-skip-comments/blanks t)
1058 (python-beginning-of-statement)
1059 (unless (bobp) (setq count (1- count))))
1060 count))
1062 (defun python-next-statement (&optional count)
1063 "Go to start of next statement.
1064 With argument COUNT, do it COUNT times. Stop at end of buffer.
1065 Return count of statements left to move."
1066 (interactive "p")
1067 (unless count (setq count 1))
1068 (if (< count 0)
1069 (python-previous-statement (- count))
1070 (beginning-of-line)
1071 (let (bogus)
1072 (while (and (> count 0) (not (eobp)) (not bogus))
1073 (python-end-of-statement)
1074 (python-skip-comments/blanks)
1075 (if (eq 'string (syntax-ppss-context (syntax-ppss)))
1076 (setq bogus t)
1077 (unless (eobp)
1078 (setq count (1- count))))))
1079 count))
1081 (defun python-beginning-of-block (&optional arg)
1082 "Go to start of current block.
1083 With numeric arg, do it that many times. If ARG is negative, call
1084 `python-end-of-block' instead.
1085 If point is on the first line of a block, use its outer block.
1086 If current statement is in column zero, don't move and return nil.
1087 Otherwise return non-nil."
1088 (interactive "p")
1089 (unless arg (setq arg 1))
1090 (cond
1091 ((zerop arg))
1092 ((< arg 0) (python-end-of-block (- arg)))
1094 (let ((point (point)))
1095 (if (or (python-comment-line-p)
1096 (python-blank-line-p))
1097 (python-skip-comments/blanks t))
1098 (python-beginning-of-statement)
1099 (let ((ci (current-indentation)))
1100 (if (zerop ci)
1101 (not (goto-char point)) ; return nil
1102 ;; Look upwards for less indented statement.
1103 (if (catch 'done
1104 ;;; This is slower than the below.
1105 ;;; (while (zerop (python-previous-statement))
1106 ;;; (when (and (< (current-indentation) ci)
1107 ;;; (python-open-block-statement-p t))
1108 ;;; (beginning-of-line)
1109 ;;; (throw 'done t)))
1110 (while (and (zerop (forward-line -1)))
1111 (when (and (< (current-indentation) ci)
1112 (not (python-comment-line-p))
1113 ;; Move to beginning to save effort in case
1114 ;; this is in string.
1115 (progn (python-beginning-of-statement) t)
1116 (python-open-block-statement-p t))
1117 (beginning-of-line)
1118 (throw 'done t)))
1119 (not (goto-char point))) ; Failed -- return nil
1120 (python-beginning-of-block (1- arg)))))))))
1122 (defun python-end-of-block (&optional arg)
1123 "Go to end of current block.
1124 With numeric arg, do it that many times. If ARG is negative,
1125 call `python-beginning-of-block' instead.
1126 If current statement is in column zero and doesn't open a block,
1127 don't move and return nil. Otherwise return t."
1128 (interactive "p")
1129 (unless arg (setq arg 1))
1130 (if (< arg 0)
1131 (python-beginning-of-block (- arg))
1132 (while (and (> arg 0)
1133 (let* ((point (point))
1134 (_ (if (python-comment-line-p)
1135 (python-skip-comments/blanks t)))
1136 (ci (current-indentation))
1137 (open (python-open-block-statement-p)))
1138 (if (and (zerop ci) (not open))
1139 (not (goto-char point))
1140 (catch 'done
1141 (while (zerop (python-next-statement))
1142 (when (or (and open (<= (current-indentation) ci))
1143 (< (current-indentation) ci))
1144 (python-skip-comments/blanks t)
1145 (beginning-of-line 2)
1146 (throw 'done t)))))))
1147 (setq arg (1- arg)))
1148 (zerop arg)))
1150 (defvar python-which-func-length-limit 40
1151 "Non-strict length limit for `python-which-func' output.")
1153 (defun python-which-func ()
1154 (let ((function-name (python-current-defun python-which-func-length-limit)))
1155 (set-text-properties 0 (length function-name) nil function-name)
1156 function-name))
1159 ;;;; Imenu.
1161 ;; For possibily speeding this up, here's the top of the ELP profile
1162 ;; for rescanning pydoc.py (2.2k lines, 90kb):
1163 ;; Function Name Call Count Elapsed Time Average Time
1164 ;; ==================================== ========== ============= ============
1165 ;; python-imenu-create-index 156 2.430906 0.0155827307
1166 ;; python-end-of-defun 155 1.2718260000 0.0082053290
1167 ;; python-end-of-block 155 1.1898689999 0.0076765741
1168 ;; python-next-statement 2970 1.024717 0.0003450225
1169 ;; python-end-of-statement 2970 0.4332190000 0.0001458649
1170 ;; python-beginning-of-defun 265 0.0918479999 0.0003465962
1171 ;; python-skip-comments/blanks 3125 0.0753319999 2.410...e-05
1173 (defvar python-recursing)
1174 (defun python-imenu-create-index ()
1175 "`imenu-create-index-function' for Python.
1177 Makes nested Imenu menus from nested `class' and `def' statements.
1178 The nested menus are headed by an item referencing the outer
1179 definition; it has a space prepended to the name so that it sorts
1180 first with `imenu--sort-by-name' (though, unfortunately, sub-menus
1181 precede it)."
1182 (unless (boundp 'python-recursing) ; dynamically bound below
1183 ;; Normal call from Imenu.
1184 (goto-char (point-min))
1185 ;; Without this, we can get an infloop if the buffer isn't all
1186 ;; fontified. I guess this is really a bug in syntax.el. OTOH,
1187 ;; _with_ this, imenu doesn't immediately work; I can't figure out
1188 ;; what's going on, but it must be something to do with timers in
1189 ;; font-lock.
1190 ;; This can't be right, especially not when jit-lock is not used. --Stef
1191 ;; (unless (get-text-property (1- (point-max)) 'fontified)
1192 ;; (font-lock-fontify-region (point-min) (point-max)))
1194 (let (index-alist) ; accumulated value to return
1195 (while (re-search-forward
1196 (rx line-start (0+ space) ; leading space
1197 (or (group "def") (group "class")) ; type
1198 (1+ space) (group (1+ (or word ?_)))) ; name
1199 nil t)
1200 (unless (python-in-string/comment)
1201 (let ((pos (match-beginning 0))
1202 (name (match-string-no-properties 3)))
1203 (if (match-beginning 2) ; def or class?
1204 (setq name (concat "class " name)))
1205 (save-restriction
1206 (narrow-to-defun)
1207 (let* ((python-recursing t)
1208 (sublist (python-imenu-create-index)))
1209 (if sublist
1210 (progn (push (cons (concat " " name) pos) sublist)
1211 (push (cons name sublist) index-alist))
1212 (push (cons name pos) index-alist)))))))
1213 (unless (boundp 'python-recursing)
1214 ;; Look for module variables.
1215 (let (vars)
1216 (goto-char (point-min))
1217 (while (re-search-forward
1218 (rx line-start (group (1+ (or word ?_))) (0+ space) "=")
1219 nil t)
1220 (unless (python-in-string/comment)
1221 (push (cons (match-string 1) (match-beginning 1))
1222 vars)))
1223 (setq index-alist (nreverse index-alist))
1224 (if vars
1225 (push (cons "Module variables"
1226 (nreverse vars))
1227 index-alist))))
1228 index-alist))
1230 ;;;; `Electric' commands.
1232 (defun python-electric-colon (arg)
1233 "Insert a colon and maybe outdent the line if it is a statement like `else'.
1234 With numeric ARG, just insert that many colons. With \\[universal-argument],
1235 just insert a single colon."
1236 (interactive "*P")
1237 (self-insert-command (if (not (integerp arg)) 1 arg))
1238 (and (not arg)
1239 (eolp)
1240 (python-outdent-p)
1241 (not (python-in-string/comment))
1242 (> (current-indentation) (python-calculate-indentation))
1243 (python-indent-line))) ; OK, do it
1244 (put 'python-electric-colon 'delete-selection t)
1246 (defun python-backspace (arg)
1247 "Maybe delete a level of indentation on the current line.
1248 Do so if point is at the end of the line's indentation outside
1249 strings and comments.
1250 Otherwise just call `backward-delete-char-untabify'.
1251 Repeat ARG times."
1252 (interactive "*p")
1253 (if (or (/= (current-indentation) (current-column))
1254 (bolp)
1255 (python-continuation-line-p)
1256 (python-in-string/comment))
1257 (backward-delete-char-untabify arg)
1258 ;; Look for the largest valid indentation which is smaller than
1259 ;; the current indentation.
1260 (let ((indent 0)
1261 (ci (current-indentation))
1262 (indents (python-indentation-levels))
1263 initial)
1264 (dolist (x indents)
1265 (if (< (car x) ci)
1266 (setq indent (max indent (car x)))))
1267 (setq initial (cdr (assq indent indents)))
1268 (if (> (length initial) 0)
1269 (message "Closes %s" initial))
1270 (delete-horizontal-space)
1271 (indent-to indent))))
1272 (put 'python-backspace 'delete-selection 'supersede)
1274 ;;;; pychecker
1276 (defcustom python-check-command "pychecker --stdlib"
1277 "Command used to check a Python file."
1278 :type 'string
1279 :group 'python)
1281 (defvar python-saved-check-command nil
1282 "Internal use.")
1284 ;; After `sgml-validate-command'.
1285 (defun python-check (command)
1286 "Check a Python file (default current buffer's file).
1287 Runs COMMAND, a shell command, as if by `compile'.
1288 See `python-check-command' for the default."
1289 (interactive
1290 (list (read-string "Checker command: "
1291 (or python-saved-check-command
1292 (concat python-check-command " "
1293 (let ((name (buffer-file-name)))
1294 (if name
1295 (file-name-nondirectory name))))))))
1296 (setq python-saved-check-command command)
1297 (require 'compile) ;To define compilation-* variables.
1298 (save-some-buffers (not compilation-ask-about-save) nil)
1299 (let ((compilation-error-regexp-alist
1300 (cons '("(\\([^,]+\\), line \\([0-9]+\\))" 1 2)
1301 compilation-error-regexp-alist)))
1302 (compilation-start command)))
1304 ;;;; Inferior mode stuff (following cmuscheme).
1306 ;; Fixme: Make sure we can work with IPython.
1308 (defcustom python-python-command "python"
1309 "Shell command to run Python interpreter.
1310 Any arguments can't contain whitespace.
1311 Note that IPython may not work properly; it must at least be used
1312 with the `-cl' flag, i.e. use `ipython -cl'."
1313 :group 'python
1314 :type 'string)
1316 (defcustom python-jython-command "jython"
1317 "Shell command to run Jython interpreter.
1318 Any arguments can't contain whitespace."
1319 :group 'python
1320 :type 'string)
1322 (defvar python-command python-python-command
1323 "Actual command used to run Python.
1324 May be `python-python-command' or `python-jython-command', possibly
1325 modified by the user. Additional arguments are added when the command
1326 is used by `run-python' et al.")
1328 (defvar python-buffer nil
1329 "*The current Python process buffer.
1331 Commands that send text from source buffers to Python processes have
1332 to choose a process to send to. This is determined by buffer-local
1333 value of `python-buffer'. If its value in the current buffer,
1334 i.e. both any local value and the default one, is nil, `run-python'
1335 and commands that send to the Python process will start a new process.
1337 Whenever \\[run-python] starts a new process, it resets the default
1338 value of `python-buffer' to be the new process's buffer and sets the
1339 buffer-local value similarly if the current buffer is in Python mode
1340 or Inferior Python mode, so that source buffer stays associated with a
1341 specific sub-process.
1343 Use \\[python-set-proc] to set the default value from a buffer with a
1344 local value.")
1345 (make-variable-buffer-local 'python-buffer)
1347 (defconst python-compilation-regexp-alist
1348 ;; FIXME: maybe these should move to compilation-error-regexp-alist-alist.
1349 ;; The first already is (for CAML), but the second isn't. Anyhow,
1350 ;; these are specific to the inferior buffer. -- fx
1351 `((,(rx line-start (1+ (any " \t")) "File \""
1352 (group (1+ (not (any "\"<")))) ; avoid `<stdin>' &c
1353 "\", line " (group (1+ digit)))
1354 1 2)
1355 (,(rx " in file " (group (1+ not-newline)) " on line "
1356 (group (1+ digit)))
1357 1 2)
1358 ;; pdb stack trace
1359 (,(rx line-start "> " (group (1+ (not (any "(\"<"))))
1360 "(" (group (1+ digit)) ")" (1+ (not (any "("))) "()")
1361 1 2))
1362 "`compilation-error-regexp-alist' for inferior Python.")
1364 (defvar inferior-python-mode-map
1365 (let ((map (make-sparse-keymap)))
1366 ;; This will inherit from comint-mode-map.
1367 (define-key map "\C-c\C-l" 'python-load-file)
1368 (define-key map "\C-c\C-v" 'python-check)
1369 ;; Note that we _can_ still use these commands which send to the
1370 ;; Python process even at the prompt iff we have a normal prompt,
1371 ;; i.e. '>>> ' and not '... '. See the comment before
1372 ;; python-send-region. Fixme: uncomment these if we address that.
1374 ;; (define-key map [(meta ?\t)] 'python-complete-symbol)
1375 ;; (define-key map "\C-c\C-f" 'python-describe-symbol)
1376 map))
1378 (defvar inferior-python-mode-syntax-table
1379 (let ((st (make-syntax-table python-mode-syntax-table)))
1380 ;; Don't get confused by apostrophes in the process's output (e.g. if
1381 ;; you execute "help(os)").
1382 (modify-syntax-entry ?\' "." st)
1383 ;; Maybe we should do the same for double quotes?
1384 ;; (modify-syntax-entry ?\" "." st)
1385 st))
1387 ;; Autoloaded.
1388 (declare-function compilation-shell-minor-mode "compile" (&optional arg))
1390 ;; Fixme: This should inherit some stuff from `python-mode', but I'm
1391 ;; not sure how much: at least some keybindings, like C-c C-f;
1392 ;; syntax?; font-locking, e.g. for triple-quoted strings?
1393 (define-derived-mode inferior-python-mode comint-mode "Inferior Python"
1394 "Major mode for interacting with an inferior Python process.
1395 A Python process can be started with \\[run-python].
1397 Hooks `comint-mode-hook' and `inferior-python-mode-hook' are run in
1398 that order.
1400 You can send text to the inferior Python process from other buffers
1401 containing Python source.
1402 * \\[python-switch-to-python] switches the current buffer to the Python
1403 process buffer.
1404 * \\[python-send-region] sends the current region to the Python process.
1405 * \\[python-send-region-and-go] switches to the Python process buffer
1406 after sending the text.
1407 For running multiple processes in multiple buffers, see `run-python' and
1408 `python-buffer'.
1410 \\{inferior-python-mode-map}"
1411 :group 'python
1412 (setq mode-line-process '(":%s"))
1413 (set (make-local-variable 'comint-input-filter) 'python-input-filter)
1414 (add-hook 'comint-preoutput-filter-functions #'python-preoutput-filter
1415 nil t)
1416 ;; Still required by `comint-redirect-send-command', for instance
1417 ;; (and we need to match things like `>>> ... >>> '):
1418 (set (make-local-variable 'comint-prompt-regexp)
1419 (rx line-start (1+ (and (or (repeat 3 (any ">.")) "(Pdb)") " "))))
1420 (set (make-local-variable 'compilation-error-regexp-alist)
1421 python-compilation-regexp-alist)
1422 (compilation-shell-minor-mode 1))
1424 (defcustom inferior-python-filter-regexp "\\`\\s-*\\S-?\\S-?\\s-*\\'"
1425 "Input matching this regexp is not saved on the history list.
1426 Default ignores all inputs of 0, 1, or 2 non-blank characters."
1427 :type 'regexp
1428 :group 'python)
1430 (defun python-input-filter (str)
1431 "`comint-input-filter' function for inferior Python.
1432 Don't save anything for STR matching `inferior-python-filter-regexp'."
1433 (not (string-match inferior-python-filter-regexp str)))
1435 ;; Fixme: Loses with quoted whitespace.
1436 (defun python-args-to-list (string)
1437 (let ((where (string-match "[ \t]" string)))
1438 (cond ((null where) (list string))
1439 ((not (= where 0))
1440 (cons (substring string 0 where)
1441 (python-args-to-list (substring string (+ 1 where)))))
1442 (t (let ((pos (string-match "[^ \t]" string)))
1443 (if pos (python-args-to-list (substring string pos))))))))
1445 (defvar python-preoutput-result nil
1446 "Data from last `_emacs_out' line seen by the preoutput filter.")
1448 (defvar python-preoutput-continuation nil
1449 "If non-nil, funcall this when `python-preoutput-filter' sees `_emacs_ok'.")
1451 (defvar python-preoutput-leftover nil)
1452 (defvar python-preoutput-skip-next-prompt nil)
1454 ;; Using this stops us getting lines in the buffer like
1455 ;; >>> ... ... >>>
1456 ;; Also look for (and delete) an `_emacs_ok' string and call
1457 ;; `python-preoutput-continuation' if we get it.
1458 (defun python-preoutput-filter (s)
1459 "`comint-preoutput-filter-functions' function: ignore prompts not at bol."
1460 (when python-preoutput-leftover
1461 (setq s (concat python-preoutput-leftover s))
1462 (setq python-preoutput-leftover nil))
1463 (let ((start 0)
1464 (res ""))
1465 ;; First process whole lines.
1466 (while (string-match "\n" s start)
1467 (let ((line (substring s start (setq start (match-end 0)))))
1468 ;; Skip prompt if needed.
1469 (when (and python-preoutput-skip-next-prompt
1470 (string-match comint-prompt-regexp line))
1471 (setq python-preoutput-skip-next-prompt nil)
1472 (setq line (substring line (match-end 0))))
1473 ;; Recognize special _emacs_out lines.
1474 (if (and (string-match "\\`_emacs_out \\(.*\\)\n\\'" line)
1475 (local-variable-p 'python-preoutput-result))
1476 (progn
1477 (setq python-preoutput-result (match-string 1 line))
1478 (set (make-local-variable 'python-preoutput-skip-next-prompt) t))
1479 (setq res (concat res line)))))
1480 ;; Then process the remaining partial line.
1481 (unless (zerop start) (setq s (substring s start)))
1482 (cond ((and (string-match comint-prompt-regexp s)
1483 ;; Drop this prompt if it follows an _emacs_out...
1484 (or python-preoutput-skip-next-prompt
1485 ;; ... or if it's not gonna be inserted at BOL.
1486 ;; Maybe we could be more selective here.
1487 (if (zerop (length res))
1488 (not (bolp))
1489 (string-match ".\\'" res))))
1490 ;; The need for this seems to be system-dependent:
1491 ;; What is this all about, exactly? --Stef
1492 ;; (if (and (eq ?. (aref s 0)))
1493 ;; (accept-process-output (get-buffer-process (current-buffer)) 1))
1494 (setq python-preoutput-skip-next-prompt nil)
1495 res)
1496 ((let ((end (min (length "_emacs_out ") (length s))))
1497 (eq t (compare-strings s nil end "_emacs_out " nil end)))
1498 ;; The leftover string is a prefix of _emacs_out so we don't know
1499 ;; yet whether it's an _emacs_out or something else: wait until we
1500 ;; get more output so we can resolve this ambiguity.
1501 (set (make-local-variable 'python-preoutput-leftover) s)
1502 res)
1503 (t (concat res s)))))
1505 (autoload 'comint-check-proc "comint")
1507 (defvar python-version-checked nil)
1508 (defun python-check-version (cmd)
1509 "Check that CMD runs a suitable version of Python."
1510 ;; Fixme: Check on Jython.
1511 (unless (or python-version-checked
1512 (equal 0 (string-match (regexp-quote python-python-command)
1513 cmd)))
1514 (unless (shell-command-to-string cmd)
1515 (error "Can't run Python command `%s'" cmd))
1516 (let* ((res (shell-command-to-string (concat cmd " --version"))))
1517 (string-match "Python \\([0-9]\\)\\.\\([0-9]\\)" res)
1518 (unless (and (equal "2" (match-string 1 res))
1519 (match-beginning 2)
1520 (>= (string-to-number (match-string 2 res)) 2))
1521 (error "Only Python versions >= 2.2 and < 3.0 supported")))
1522 (setq python-version-checked t)))
1524 ;;;###autoload
1525 (defun run-python (&optional cmd noshow new)
1526 "Run an inferior Python process, input and output via buffer *Python*.
1527 CMD is the Python command to run. NOSHOW non-nil means don't show the
1528 buffer automatically.
1530 Normally, if there is a process already running in `python-buffer',
1531 switch to that buffer. Interactively, a prefix arg allows you to edit
1532 the initial command line (default is `python-command'); `-i' etc. args
1533 will be added to this as appropriate. A new process is started if:
1534 one isn't running attached to `python-buffer', or interactively the
1535 default `python-command', or argument NEW is non-nil. See also the
1536 documentation for `python-buffer'.
1538 Runs the hook `inferior-python-mode-hook' \(after the
1539 `comint-mode-hook' is run). \(Type \\[describe-mode] in the process
1540 buffer for a list of commands.)"
1541 (interactive (if current-prefix-arg
1542 (list (read-string "Run Python: " python-command) nil t)
1543 (list python-command)))
1544 (unless cmd (setq cmd python-command))
1545 (python-check-version cmd)
1546 (setq python-command cmd)
1547 ;; Fixme: Consider making `python-buffer' buffer-local as a buffer
1548 ;; (not a name) in Python buffers from which `run-python' &c is
1549 ;; invoked. Would support multiple processes better.
1550 (when (or new (not (comint-check-proc python-buffer)))
1551 (with-current-buffer
1552 (let* ((cmdlist
1553 (append (python-args-to-list cmd)
1554 '("-i" "-c" "import sys; sys.path.remove('')")))
1555 (path (getenv "PYTHONPATH"))
1556 (process-environment ; to import emacs.py
1557 (cons (concat "PYTHONPATH="
1558 (if path (concat path path-separator))
1559 data-directory)
1560 process-environment))
1561 ;; Suppress use of pager for help output:
1562 (process-connection-type nil))
1563 (apply 'make-comint-in-buffer "Python"
1564 (generate-new-buffer "*Python*")
1565 (car cmdlist) nil (cdr cmdlist)))
1566 (setq-default python-buffer (current-buffer))
1567 (setq python-buffer (current-buffer))
1568 (accept-process-output (get-buffer-process python-buffer) 5)
1569 (inferior-python-mode)
1570 ;; Load function definitions we need.
1571 ;; Before the preoutput function was used, this was done via -c in
1572 ;; cmdlist, but that loses the banner and doesn't run the startup
1573 ;; file. The code might be inline here, but there's enough that it
1574 ;; seems worth putting in a separate file, and it's probably cleaner
1575 ;; to put it in a module.
1576 ;; Ensure we're at a prompt before doing anything else.
1577 (python-send-string "import emacs")
1578 ;; The following line was meant to ensure that we're at a prompt
1579 ;; before doing anything else. However, this can cause Emacs to
1580 ;; hang waiting for a response, if that Python function fails
1581 ;; (i.e. raises an exception).
1582 ;; (python-send-receive "print '_emacs_out ()'")
1584 (if (derived-mode-p 'python-mode)
1585 (setq python-buffer (default-value 'python-buffer))) ; buffer-local
1586 ;; Without this, help output goes into the inferior python buffer if
1587 ;; the process isn't already running.
1588 (sit-for 1 t) ;Should we use accept-process-output instead? --Stef
1589 (unless noshow (pop-to-buffer python-buffer t)))
1591 (defun python-send-command (command)
1592 "Like `python-send-string' but resets `compilation-shell-minor-mode'."
1593 (when (python-check-comint-prompt)
1594 (with-current-buffer (process-buffer (python-proc))
1595 (goto-char (point-max))
1596 (compilation-forget-errors)
1597 (python-send-string command)
1598 (setq compilation-last-buffer (current-buffer)))))
1600 (defun python-send-region (start end)
1601 "Send the region to the inferior Python process."
1602 ;; The region is evaluated from a temporary file. This avoids
1603 ;; problems with blank lines, which have different semantics
1604 ;; interactively and in files. It also saves the inferior process
1605 ;; buffer filling up with interpreter prompts. We need a Python
1606 ;; function to remove the temporary file when it has been evaluated
1607 ;; (though we could probably do it in Lisp with a Comint output
1608 ;; filter). This function also catches exceptions and truncates
1609 ;; tracebacks not to mention the frame of the function itself.
1611 ;; The `compilation-shell-minor-mode' parsing takes care of relating
1612 ;; the reference to the temporary file to the source.
1614 ;; Fixme: Write a `coding' header to the temp file if the region is
1615 ;; non-ASCII.
1616 (interactive "r")
1617 (let* ((f (make-temp-file "py"))
1618 (command (format "emacs.eexecfile(%S)" f))
1619 (orig-start (copy-marker start)))
1620 (when (save-excursion
1621 (goto-char start)
1622 (/= 0 (current-indentation))) ; need dummy block
1623 (save-excursion
1624 (goto-char orig-start)
1625 ;; Wrong if we had indented code at buffer start.
1626 (set-marker orig-start (line-beginning-position 0)))
1627 (write-region "if True:\n" nil f nil 'nomsg))
1628 (write-region start end f t 'nomsg)
1629 (python-send-command command)
1630 (with-current-buffer (process-buffer (python-proc))
1631 ;; Tell compile.el to redirect error locations in file `f' to
1632 ;; positions past marker `orig-start'. It has to be done *after*
1633 ;; `python-send-command''s call to `compilation-forget-errors'.
1634 (compilation-fake-loc orig-start f))))
1636 (defun python-send-string (string)
1637 "Evaluate STRING in inferior Python process."
1638 (interactive "sPython command: ")
1639 (comint-send-string (python-proc) string)
1640 (unless (string-match "\n\\'" string)
1641 ;; Make sure the text is properly LF-terminated.
1642 (comint-send-string (python-proc) "\n"))
1643 (when (string-match "\n[ \t].*\n?\\'" string)
1644 ;; If the string contains a final indented line, add a second newline so
1645 ;; as to make sure we terminate the multiline instruction.
1646 (comint-send-string (python-proc) "\n")))
1648 (defun python-send-buffer ()
1649 "Send the current buffer to the inferior Python process."
1650 (interactive)
1651 (python-send-region (point-min) (point-max)))
1653 ;; Fixme: Try to define the function or class within the relevant
1654 ;; module, not just at top level.
1655 (defun python-send-defun ()
1656 "Send the current defun (class or method) to the inferior Python process."
1657 (interactive)
1658 (save-excursion (python-send-region (progn (beginning-of-defun) (point))
1659 (progn (end-of-defun) (point)))))
1661 (defun python-switch-to-python (eob-p)
1662 "Switch to the Python process buffer, maybe starting new process.
1663 With prefix arg, position cursor at end of buffer."
1664 (interactive "P")
1665 (pop-to-buffer (process-buffer (python-proc)) t) ;Runs python if needed.
1666 (when eob-p
1667 (push-mark)
1668 (goto-char (point-max))))
1670 (defun python-send-region-and-go (start end)
1671 "Send the region to the inferior Python process.
1672 Then switch to the process buffer."
1673 (interactive "r")
1674 (python-send-region start end)
1675 (python-switch-to-python t))
1677 (defcustom python-source-modes '(python-mode jython-mode)
1678 "Used to determine if a buffer contains Python source code.
1679 If a file is loaded into a buffer that is in one of these major modes,
1680 it is considered Python source by `python-load-file', which uses the
1681 value to determine defaults."
1682 :type '(repeat function)
1683 :group 'python)
1685 (defvar python-prev-dir/file nil
1686 "Caches (directory . file) pair used in the last `python-load-file' command.
1687 Used for determining the default in the next one.")
1689 (autoload 'comint-get-source "comint")
1691 (defun python-load-file (file-name)
1692 "Load a Python file FILE-NAME into the inferior Python process.
1693 If the file has extension `.py' import or reload it as a module.
1694 Treating it as a module keeps the global namespace clean, provides
1695 function location information for debugging, and supports users of
1696 module-qualified names."
1697 (interactive (comint-get-source "Load Python file: " python-prev-dir/file
1698 python-source-modes
1699 t)) ; because execfile needs exact name
1700 (comint-check-source file-name) ; Check to see if buffer needs saving.
1701 (setq python-prev-dir/file (cons (file-name-directory file-name)
1702 (file-name-nondirectory file-name)))
1703 (with-current-buffer (process-buffer (python-proc)) ;Runs python if needed.
1704 ;; Fixme: I'm not convinced by this logic from python-mode.el.
1705 (python-send-command
1706 (if (string-match "\\.py\\'" file-name)
1707 (let ((module (file-name-sans-extension
1708 (file-name-nondirectory file-name))))
1709 (format "emacs.eimport(%S,%S)"
1710 module (file-name-directory file-name)))
1711 (format "execfile(%S)" file-name)))
1712 (message "%s loaded" file-name)))
1714 (defun python-proc ()
1715 "Return the current Python process.
1716 See variable `python-buffer'. Starts a new process if necessary."
1717 ;; Fixme: Maybe should look for another active process if there
1718 ;; isn't one for `python-buffer'.
1719 (unless (comint-check-proc python-buffer)
1720 (run-python nil t))
1721 (get-buffer-process (if (derived-mode-p 'inferior-python-mode)
1722 (current-buffer)
1723 python-buffer)))
1725 (defun python-set-proc ()
1726 "Set the default value of `python-buffer' to correspond to this buffer.
1727 If the current buffer has a local value of `python-buffer', set the
1728 default (global) value to that. The associated Python process is
1729 the one that gets input from \\[python-send-region] et al when used
1730 in a buffer that doesn't have a local value of `python-buffer'."
1731 (interactive)
1732 (if (local-variable-p 'python-buffer)
1733 (setq-default python-buffer python-buffer)
1734 (error "No local value of `python-buffer'")))
1736 ;;;; Context-sensitive help.
1738 (defconst python-dotty-syntax-table
1739 (let ((table (make-syntax-table)))
1740 (set-char-table-parent table python-mode-syntax-table)
1741 (modify-syntax-entry ?. "_" table)
1742 table)
1743 "Syntax table giving `.' symbol syntax.
1744 Otherwise inherits from `python-mode-syntax-table'.")
1746 (defvar view-return-to-alist)
1747 (eval-when-compile (autoload 'help-buffer "help-fns"))
1749 (defvar python-imports) ; forward declaration
1751 ;; Fixme: Should this actually be used instead of info-look, i.e. be
1752 ;; bound to C-h S? [Probably not, since info-look may work in cases
1753 ;; where this doesn't.]
1754 (defun python-describe-symbol (symbol)
1755 "Get help on SYMBOL using `help'.
1756 Interactively, prompt for symbol.
1758 Symbol may be anything recognized by the interpreter's `help'
1759 command -- e.g. `CALLS' -- not just variables in scope in the
1760 interpreter. This only works for Python version 2.2 or newer
1761 since earlier interpreters don't support `help'.
1763 In some cases where this doesn't find documentation, \\[info-lookup-symbol]
1764 will."
1765 ;; Note that we do this in the inferior process, not a separate one, to
1766 ;; ensure the environment is appropriate.
1767 (interactive
1768 (let ((symbol (with-syntax-table python-dotty-syntax-table
1769 (current-word)))
1770 (enable-recursive-minibuffers t))
1771 (list (read-string (if symbol
1772 (format "Describe symbol (default %s): " symbol)
1773 "Describe symbol: ")
1774 nil nil symbol))))
1775 (if (equal symbol "") (error "No symbol"))
1776 ;; Ensure we have a suitable help buffer.
1777 ;; Fixme: Maybe process `Related help topics' a la help xrefs and
1778 ;; allow C-c C-f in help buffer.
1779 (let ((temp-buffer-show-hook ; avoid xref stuff
1780 (lambda ()
1781 (toggle-read-only 1)
1782 (setq view-return-to-alist
1783 (list (cons (selected-window) help-return-method))))))
1784 (with-output-to-temp-buffer (help-buffer)
1785 (with-current-buffer standard-output
1786 ;; Fixme: Is this actually useful?
1787 (help-setup-xref (list 'python-describe-symbol symbol)
1788 (called-interactively-p 'interactive))
1789 (set (make-local-variable 'comint-redirect-subvert-readonly) t)
1790 (help-print-return-message))))
1791 (comint-redirect-send-command-to-process (format "emacs.ehelp(%S, %s)"
1792 symbol python-imports)
1793 "*Help*" (python-proc) nil nil))
1795 (add-to-list 'debug-ignored-errors "^No symbol")
1797 (defun python-send-receive (string)
1798 "Send STRING to inferior Python (if any) and return result.
1799 The result is what follows `_emacs_out' in the output.
1800 This is a no-op if `python-check-comint-prompt' returns nil."
1801 (python-send-string string)
1802 (let ((proc (python-proc)))
1803 (with-current-buffer (process-buffer proc)
1804 (when (python-check-comint-prompt proc)
1805 (set (make-local-variable 'python-preoutput-result) nil)
1806 (while (progn
1807 (accept-process-output proc 5)
1808 (null python-preoutput-result)))
1809 (prog1 python-preoutput-result
1810 (kill-local-variable 'python-preoutput-result))))))
1812 (defun python-check-comint-prompt (&optional proc)
1813 "Return non-nil if and only if there's a normal prompt in the inferior buffer.
1814 If there isn't, it's probably not appropriate to send input to return Eldoc
1815 information etc. If PROC is non-nil, check the buffer for that process."
1816 (with-current-buffer (process-buffer (or proc (python-proc)))
1817 (save-excursion
1818 (save-match-data (re-search-backward ">>> \\=" nil t)))))
1820 ;; Fixme: Is there anything reasonable we can do with random methods?
1821 ;; (Currently only works with functions.)
1822 (defun python-eldoc-function ()
1823 "`eldoc-documentation-function' for Python.
1824 Only works when point is in a function name, not its arg list, for
1825 instance. Assumes an inferior Python is running."
1826 (let ((symbol (with-syntax-table python-dotty-syntax-table
1827 (current-word))))
1828 ;; This is run from timers, so inhibit-quit tends to be set.
1829 (with-local-quit
1830 ;; First try the symbol we're on.
1831 (or (and symbol
1832 (python-send-receive (format "emacs.eargs(%S, %s)"
1833 symbol python-imports)))
1834 ;; Try moving to symbol before enclosing parens.
1835 (let ((s (syntax-ppss)))
1836 (unless (zerop (car s))
1837 (when (eq ?\( (char-after (nth 1 s)))
1838 (save-excursion
1839 (goto-char (nth 1 s))
1840 (skip-syntax-backward "-")
1841 (let ((point (point)))
1842 (skip-chars-backward "a-zA-Z._")
1843 (if (< (point) point)
1844 (python-send-receive
1845 (format "emacs.eargs(%S, %s)"
1846 (buffer-substring-no-properties (point) point)
1847 python-imports))))))))))))
1849 ;;;; Info-look functionality.
1851 (declare-function info-lookup-maybe-add-help "info-look" (&rest arg))
1853 (defun python-after-info-look ()
1854 "Set up info-look for Python.
1855 Used with `eval-after-load'."
1856 (let* ((version (let ((s (shell-command-to-string (concat python-command
1857 " -V"))))
1858 (string-match "^Python \\([0-9]+\\.[0-9]+\\>\\)" s)
1859 (match-string 1 s)))
1860 ;; Whether info files have a Python version suffix, e.g. in Debian.
1861 (versioned
1862 (with-temp-buffer
1863 (with-no-warnings (Info-mode))
1864 (condition-case ()
1865 ;; Don't use `info' because it would pop-up a *info* buffer.
1866 (with-no-warnings
1867 (Info-goto-node (format "(python%s-lib)Miscellaneous Index"
1868 version))
1870 (error nil)))))
1871 (info-lookup-maybe-add-help
1872 :mode 'python-mode
1873 :regexp "[[:alnum:]_]+"
1874 :doc-spec
1875 ;; Fixme: Can this reasonably be made specific to indices with
1876 ;; different rules? Is the order of indices optimal?
1877 ;; (Miscellaneous in -ref first prefers lookup of keywords, for
1878 ;; instance.)
1879 (if versioned
1880 ;; The empty prefix just gets us highlighted terms.
1881 `((,(concat "(python" version "-ref)Miscellaneous Index") nil "")
1882 (,(concat "(python" version "-ref)Module Index" nil ""))
1883 (,(concat "(python" version "-ref)Function-Method-Variable Index"
1884 nil ""))
1885 (,(concat "(python" version "-ref)Class-Exception-Object Index"
1886 nil ""))
1887 (,(concat "(python" version "-lib)Module Index" nil ""))
1888 (,(concat "(python" version "-lib)Class-Exception-Object Index"
1889 nil ""))
1890 (,(concat "(python" version "-lib)Function-Method-Variable Index"
1891 nil ""))
1892 (,(concat "(python" version "-lib)Miscellaneous Index" nil "")))
1893 '(("(python-ref)Miscellaneous Index" nil "")
1894 ("(python-ref)Module Index" nil "")
1895 ("(python-ref)Function-Method-Variable Index" nil "")
1896 ("(python-ref)Class-Exception-Object Index" nil "")
1897 ("(python-lib)Module Index" nil "")
1898 ("(python-lib)Class-Exception-Object Index" nil "")
1899 ("(python-lib)Function-Method-Variable Index" nil "")
1900 ("(python-lib)Miscellaneous Index" nil ""))))))
1901 (eval-after-load "info-look" '(python-after-info-look))
1903 ;;;; Miscellany.
1905 (defcustom python-jython-packages '("java" "javax" "org" "com")
1906 "Packages implying `jython-mode'.
1907 If these are imported near the beginning of the buffer, `python-mode'
1908 actually punts to `jython-mode'."
1909 :type '(repeat string)
1910 :group 'python)
1912 ;; Called from `python-mode', this causes a recursive call of the
1913 ;; mode. See logic there to break out of the recursion.
1914 (defun python-maybe-jython ()
1915 "Invoke `jython-mode' if the buffer appears to contain Jython code.
1916 The criterion is either a match for `jython-mode' via
1917 `interpreter-mode-alist' or an import of a module from the list
1918 `python-jython-packages'."
1919 ;; The logic is taken from python-mode.el.
1920 (save-excursion
1921 (save-restriction
1922 (widen)
1923 (goto-char (point-min))
1924 (let ((interpreter (if (looking-at auto-mode-interpreter-regexp)
1925 (match-string 2))))
1926 (if (and interpreter (eq 'jython-mode
1927 (cdr (assoc (file-name-nondirectory
1928 interpreter)
1929 interpreter-mode-alist))))
1930 (jython-mode)
1931 (if (catch 'done
1932 (while (re-search-forward
1933 (rx line-start (or "import" "from") (1+ space)
1934 (group (1+ (not (any " \t\n.")))))
1935 (+ (point-min) 10000) ; Probably not worth customizing.
1937 (if (member (match-string 1) python-jython-packages)
1938 (throw 'done t))))
1939 (jython-mode)))))))
1941 (defun python-fill-paragraph (&optional justify)
1942 "`fill-paragraph-function' handling multi-line strings and possibly comments.
1943 If any of the current line is in or at the end of a multi-line string,
1944 fill the string or the paragraph of it that point is in, preserving
1945 the string's indentation."
1946 (interactive "P")
1947 (or (fill-comment-paragraph justify)
1948 (save-excursion
1949 (end-of-line)
1950 (let* ((syntax (syntax-ppss))
1951 (orig (point))
1952 start end)
1953 (cond ((nth 4 syntax) ; comment. fixme: loses with trailing one
1954 (let (fill-paragraph-function)
1955 (fill-paragraph justify)))
1956 ;; The `paragraph-start' and `paragraph-separate'
1957 ;; variables don't allow us to delimit the last
1958 ;; paragraph in a multi-line string properly, so narrow
1959 ;; to the string and then fill around (the end of) the
1960 ;; current line.
1961 ((eq t (nth 3 syntax)) ; in fenced string
1962 (goto-char (nth 8 syntax)) ; string start
1963 (setq start (line-beginning-position))
1964 (setq end (condition-case () ; for unbalanced quotes
1965 (progn (forward-sexp)
1966 (- (point) 3))
1967 (error (point-max)))))
1968 ((re-search-backward "\\s|\\s-*\\=" nil t) ; end of fenced string
1969 (forward-char)
1970 (setq end (point))
1971 (condition-case ()
1972 (progn (backward-sexp)
1973 (setq start (line-beginning-position)))
1974 (error nil))))
1975 (when end
1976 (save-restriction
1977 (narrow-to-region start end)
1978 (goto-char orig)
1979 ;; Avoid losing leading and trailing newlines in doc
1980 ;; strings written like:
1981 ;; """
1982 ;; ...
1983 ;; """
1984 (let ((paragraph-separate
1985 ;; Note that the string could be part of an
1986 ;; expression, so it can have preceding and
1987 ;; trailing non-whitespace.
1988 (concat
1989 (rx (or
1990 ;; Opening triple quote without following text.
1991 (and (* nonl)
1992 (group (syntax string-delimiter))
1993 (repeat 2 (backref 1))
1994 ;; Fixme: Not sure about including
1995 ;; trailing whitespace.
1996 (* (any " \t"))
1997 eol)
1998 ;; Closing trailing quote without preceding text.
1999 (and (group (any ?\" ?')) (backref 2)
2000 (syntax string-delimiter))))
2001 "\\(?:" paragraph-separate "\\)"))
2002 fill-paragraph-function)
2003 (fill-paragraph justify))))))) t)
2005 (defun python-shift-left (start end &optional count)
2006 "Shift lines in region COUNT (the prefix arg) columns to the left.
2007 COUNT defaults to `python-indent'. If region isn't active, just shift
2008 current line. The region shifted includes the lines in which START and
2009 END lie. It is an error if any lines in the region are indented less than
2010 COUNT columns."
2011 (interactive
2012 (if mark-active
2013 (list (region-beginning) (region-end) current-prefix-arg)
2014 (list (line-beginning-position) (line-end-position) current-prefix-arg)))
2015 (if count
2016 (setq count (prefix-numeric-value count))
2017 (setq count python-indent))
2018 (when (> count 0)
2019 (save-excursion
2020 (goto-char start)
2021 (while (< (point) end)
2022 (if (and (< (current-indentation) count)
2023 (not (looking-at "[ \t]*$")))
2024 (error "Can't shift all lines enough"))
2025 (forward-line))
2026 (indent-rigidly start end (- count)))))
2028 (add-to-list 'debug-ignored-errors "^Can't shift all lines enough")
2030 (defun python-shift-right (start end &optional count)
2031 "Shift lines in region COUNT (the prefix arg) columns to the right.
2032 COUNT defaults to `python-indent'. If region isn't active, just shift
2033 current line. The region shifted includes the lines in which START and
2034 END lie."
2035 (interactive
2036 (if mark-active
2037 (list (region-beginning) (region-end) current-prefix-arg)
2038 (list (line-beginning-position) (line-end-position) current-prefix-arg)))
2039 (if count
2040 (setq count (prefix-numeric-value count))
2041 (setq count python-indent))
2042 (indent-rigidly start end count))
2044 (defun python-outline-level ()
2045 "`outline-level' function for Python mode.
2046 The level is the number of `python-indent' steps of indentation
2047 of current line."
2048 (1+ (/ (current-indentation) python-indent)))
2050 ;; Fixme: Consider top-level assignments, imports, &c.
2051 (defun python-current-defun (&optional length-limit)
2052 "`add-log-current-defun-function' for Python."
2053 (save-excursion
2054 ;; Move up the tree of nested `class' and `def' blocks until we
2055 ;; get to zero indentation, accumulating the defined names.
2056 (let ((accum)
2057 (length -1))
2058 (catch 'done
2059 (while (or (null length-limit)
2060 (null (cdr accum))
2061 (< length length-limit))
2062 (let ((started-from (point)))
2063 (python-beginning-of-block)
2064 (end-of-line)
2065 (beginning-of-defun)
2066 (when (= (point) started-from)
2067 (throw 'done nil)))
2068 (when (looking-at (rx (0+ space) (or "def" "class") (1+ space)
2069 (group (1+ (or word (syntax symbol))))))
2070 (push (match-string 1) accum)
2071 (setq length (+ length 1 (length (car accum)))))
2072 (when (= (current-indentation) 0)
2073 (throw 'done nil))))
2074 (when accum
2075 (when (and length-limit (> length length-limit))
2076 (setcar accum ".."))
2077 (mapconcat 'identity accum ".")))))
2079 (defun python-mark-block ()
2080 "Mark the block around point.
2081 Uses `python-beginning-of-block', `python-end-of-block'."
2082 (interactive)
2083 (push-mark)
2084 (python-beginning-of-block)
2085 (push-mark (point) nil t)
2086 (python-end-of-block)
2087 (exchange-point-and-mark))
2089 ;; Fixme: Provide a find-function-like command to find source of a
2090 ;; definition (separate from BicycleRepairMan). Complicated by
2091 ;; finding the right qualified name.
2093 ;;;; Completion.
2095 ;; http://lists.gnu.org/archive/html/bug-gnu-emacs/2008-01/msg00076.html
2096 (defvar python-imports "None"
2097 "String of top-level import statements updated by `python-find-imports'.")
2098 (make-variable-buffer-local 'python-imports)
2100 ;; Fixme: Should font-lock try to run this when it deals with an import?
2101 ;; Maybe not a good idea if it gets run multiple times when the
2102 ;; statement is being edited, and is more likely to end up with
2103 ;; something syntactically incorrect.
2104 ;; However, what we should do is to trundle up the block tree from point
2105 ;; to extract imports that appear to be in scope, and add those.
2106 (defun python-find-imports ()
2107 "Find top-level imports, updating `python-imports'."
2108 (interactive)
2109 (save-excursion
2110 (let (lines)
2111 (goto-char (point-min))
2112 (while (re-search-forward "^import\\>\\|^from\\>" nil t)
2113 (unless (syntax-ppss-context (syntax-ppss))
2114 (let ((start (line-beginning-position)))
2115 ;; Skip over continued lines.
2116 (while (and (eq ?\\ (char-before (line-end-position)))
2117 (= 0 (forward-line 1)))
2119 (push (buffer-substring start (line-beginning-position 2))
2120 lines))))
2121 (setq python-imports
2122 (if lines
2123 (apply #'concat
2124 ;; This is probably best left out since you're unlikely to need the
2125 ;; doc for a function in the buffer and the import will lose if the
2126 ;; Python sub-process' working directory isn't the same as the
2127 ;; buffer's.
2128 ;; (if buffer-file-name
2129 ;; (concat
2130 ;; "import "
2131 ;; (file-name-sans-extension
2132 ;; (file-name-nondirectory buffer-file-name))))
2133 (nreverse lines))
2134 "None"))
2135 (when lines
2136 (set-text-properties 0 (length python-imports) nil python-imports)
2137 ;; The output ends up in the wrong place if the string we
2138 ;; send contains newlines (from the imports).
2139 (setq python-imports
2140 (replace-regexp-in-string "\n" "\\n"
2141 (format "%S" python-imports) t t))))))
2143 ;; Fixme: This fails the first time if the sub-process isn't already
2144 ;; running. Presumably a timing issue with i/o to the process.
2145 (defun python-symbol-completions (symbol)
2146 "Return a list of completions of the string SYMBOL from Python process.
2147 The list is sorted.
2148 Uses `python-imports' to load modules against which to complete."
2149 (when (stringp symbol)
2150 (let ((completions
2151 (condition-case ()
2152 (car (read-from-string
2153 (python-send-receive
2154 (format "emacs.complete(%S,%s)"
2155 (substring-no-properties symbol)
2156 python-imports))))
2157 (error nil))))
2158 (sort
2159 ;; We can get duplicates from the above -- don't know why.
2160 (delete-dups completions)
2161 #'string<))))
2163 (defun python-completion-at-point ()
2164 (let ((end (point))
2165 (start (save-excursion
2166 (and (re-search-backward
2167 (rx (or buffer-start (regexp "[^[:alnum:]._]"))
2168 (group (1+ (regexp "[[:alnum:]._]"))) point)
2169 nil t)
2170 (match-beginning 1)))))
2171 (when start
2172 (list start end
2173 (completion-table-dynamic 'python-symbol-completions)))))
2175 ;;;; FFAP support
2177 (defun python-module-path (module)
2178 "Function for `ffap-alist' to return path to MODULE."
2179 (python-send-receive (format "emacs.modpath (%S)" module)))
2181 (eval-after-load "ffap"
2182 '(push '(python-mode . python-module-path) ffap-alist))
2184 ;;;; Find-function support
2186 ;; Fixme: key binding?
2188 (defun python-find-function (name)
2189 "Find source of definition of function NAME.
2190 Interactively, prompt for name."
2191 (interactive
2192 (let ((symbol (with-syntax-table python-dotty-syntax-table
2193 (current-word)))
2194 (enable-recursive-minibuffers t))
2195 (list (read-string (if symbol
2196 (format "Find location of (default %s): " symbol)
2197 "Find location of: ")
2198 nil nil symbol))))
2199 (unless python-imports
2200 (error "Not called from buffer visiting Python file"))
2201 (let* ((loc (python-send-receive (format "emacs.location_of (%S, %s)"
2202 name python-imports)))
2203 (loc (car (read-from-string loc)))
2204 (file (car loc))
2205 (line (cdr loc)))
2206 (unless file (error "Don't know where `%s' is defined" name))
2207 (pop-to-buffer (find-file-noselect file))
2208 (when (integerp line)
2209 (goto-char (point-min))
2210 (forward-line (1- line)))))
2212 ;;;; Skeletons
2214 (defcustom python-use-skeletons nil
2215 "Non-nil means template skeletons will be automagically inserted.
2216 This happens when pressing \"if<SPACE>\", for example, to prompt for
2217 the if condition."
2218 :type 'boolean
2219 :group 'python)
2221 (define-abbrev-table 'python-mode-abbrev-table ()
2222 "Abbrev table for Python mode."
2223 :case-fixed t
2224 ;; Allow / inside abbrevs.
2225 :regexp "\\(?:^\\|[^/]\\)\\<\\([[:word:]/]+\\)\\W*"
2226 ;; Only expand in code.
2227 :enable-function (lambda () (not (python-in-string/comment))))
2229 (eval-when-compile
2230 ;; Define a user-level skeleton and add it to the abbrev table.
2231 (defmacro def-python-skeleton (name &rest elements)
2232 (let* ((name (symbol-name name))
2233 (function (intern (concat "python-insert-" name))))
2234 `(progn
2235 ;; Usual technique for inserting a skeleton, but expand
2236 ;; to the original abbrev instead if in a comment or string.
2237 (when python-use-skeletons
2238 (define-abbrev python-mode-abbrev-table ,name ""
2239 ',function
2240 nil t)) ; system abbrev
2241 (define-skeleton ,function
2242 ,(format "Insert Python \"%s\" template." name)
2243 ,@elements)))))
2244 (put 'def-python-skeleton 'lisp-indent-function 2)
2246 ;; From `skeleton-further-elements' set below:
2247 ;; `<': outdent a level;
2248 ;; `^': delete indentation on current line and also previous newline.
2249 ;; Not quite like `delete-indentation'. Assumes point is at
2250 ;; beginning of indentation.
2252 (def-python-skeleton if
2253 "Condition: "
2254 "if " str ":" \n
2255 > -1 ; Fixme: I don't understand the spurious space this removes.
2256 _ \n
2257 ("other condition, %s: "
2258 < ; Avoid wrong indentation after block opening.
2259 "elif " str ":" \n
2260 > _ \n nil)
2261 '(python-else) | ^)
2263 (define-skeleton python-else
2264 "Auxiliary skeleton."
2266 (unless (eq ?y (read-char "Add `else' clause? (y for yes or RET for no) "))
2267 (signal 'quit t))
2268 < "else:" \n
2269 > _ \n)
2271 (def-python-skeleton while
2272 "Condition: "
2273 "while " str ":" \n
2274 > -1 _ \n
2275 '(python-else) | ^)
2277 (def-python-skeleton for
2278 "Target, %s: "
2279 "for " str " in " (skeleton-read "Expression, %s: ") ":" \n
2280 > -1 _ \n
2281 '(python-else) | ^)
2283 (def-python-skeleton try/except
2285 "try:" \n
2286 > -1 _ \n
2287 ("Exception, %s: "
2288 < "except " str '(python-target) ":" \n
2289 > _ \n nil)
2290 < "except:" \n
2291 > _ \n
2292 '(python-else) | ^)
2294 (define-skeleton python-target
2295 "Auxiliary skeleton."
2296 "Target, %s: " ", " str | -2)
2298 (def-python-skeleton try/finally
2300 "try:" \n
2301 > -1 _ \n
2302 < "finally:" \n
2303 > _ \n)
2305 (def-python-skeleton def
2306 "Name: "
2307 "def " str " (" ("Parameter, %s: " (unless (equal ?\( (char-before)) ", ")
2308 str) "):" \n
2309 "\"\"\"" - "\"\"\"" \n ; Fixme: extra space inserted -- why?).
2310 > _ \n)
2312 (def-python-skeleton class
2313 "Name: "
2314 "class " str " (" ("Inheritance, %s: "
2315 (unless (equal ?\( (char-before)) ", ")
2316 str)
2317 & ")" | -2 ; close list or remove opening
2318 ":" \n
2319 "\"\"\"" - "\"\"\"" \n
2320 > _ \n)
2322 (defvar python-default-template "if"
2323 "Default template to expand by `python-expand-template'.
2324 Updated on each expansion.")
2326 (defun python-expand-template (name)
2327 "Expand template named NAME.
2328 Interactively, prompt for the name with completion."
2329 (interactive
2330 (list (completing-read (format "Template to expand (default %s): "
2331 python-default-template)
2332 python-mode-abbrev-table nil t nil nil
2333 python-default-template)))
2334 (if (equal "" name)
2335 (setq name python-default-template)
2336 (setq python-default-template name))
2337 (let ((sym (abbrev-symbol name python-mode-abbrev-table)))
2338 (if sym
2339 (abbrev-insert sym)
2340 (error "Undefined template: %s" name))))
2342 ;;;; Bicycle Repair Man support
2344 (autoload 'pymacs-load "pymacs" nil t)
2345 (autoload 'brm-init "bikemacs")
2347 ;; I'm not sure how useful BRM really is, and it's certainly dangerous
2348 ;; the way it modifies files outside Emacs... Also note that the
2349 ;; current BRM loses with tabs used for indentation -- I submitted a
2350 ;; fix <URL:http://www.loveshack.ukfsn.org/emacs/bikeemacs.py.diff>.
2351 (defun python-setup-brm ()
2352 "Set up Bicycle Repair Man refactoring tool (if available).
2354 Note that the `refactoring' features change files independently of
2355 Emacs and may modify and save the contents of the current buffer
2356 without confirmation."
2357 (interactive)
2358 (condition-case data
2359 (unless (fboundp 'brm-rename)
2360 (pymacs-load "bikeemacs" "brm-") ; first line of normal recipe
2361 (let ((py-mode-map (make-sparse-keymap)) ; it assumes this
2362 (features (cons 'python-mode features))) ; and requires this
2363 (brm-init) ; second line of normal recipe
2364 (remove-hook 'python-mode-hook ; undo this from `brm-init'
2365 '(lambda () (easy-menu-add brm-menu)))
2366 (easy-menu-define
2367 python-brm-menu python-mode-map
2368 "Bicycle Repair Man"
2369 '("BicycleRepairMan"
2370 :help "Interface to navigation and refactoring tool"
2371 "Queries"
2372 ["Find References" brm-find-references
2373 :help "Find references to name at point in compilation buffer"]
2374 ["Find Definition" brm-find-definition
2375 :help "Find definition of name at point"]
2377 "Refactoring"
2378 ["Rename" brm-rename
2379 :help "Replace name at point with a new name everywhere"]
2380 ["Extract Method" brm-extract-method
2381 :active (and mark-active (not buffer-read-only))
2382 :help "Replace statements in region with a method"]
2383 ["Extract Local Variable" brm-extract-local-variable
2384 :active (and mark-active (not buffer-read-only))
2385 :help "Replace expression in region with an assignment"]
2386 ["Inline Local Variable" brm-inline-local-variable
2387 :help
2388 "Substitute uses of variable at point with its definition"]
2389 ;; Fixme: Should check for anything to revert.
2390 ["Undo Last Refactoring" brm-undo :help ""]))))
2391 (error (error "BicycleRepairMan setup failed: %s" data))))
2393 ;;;; Modes.
2395 ;; pdb tracking is alert once this file is loaded, but takes no action if
2396 ;; `python-pdbtrack-do-tracking-p' is nil.
2397 (add-hook 'comint-output-filter-functions 'python-pdbtrack-track-stack-file)
2399 (defvar outline-heading-end-regexp)
2400 (defvar eldoc-documentation-function)
2401 (defvar python-mode-running) ;Dynamically scoped var.
2403 ;;;###autoload
2404 (define-derived-mode python-mode fundamental-mode "Python"
2405 "Major mode for editing Python files.
2406 Turns on Font Lock mode unconditionally since it is currently required
2407 for correct parsing of the source.
2408 See also `jython-mode', which is actually invoked if the buffer appears to
2409 contain Jython code. See also `run-python' and associated Python mode
2410 commands for running Python under Emacs.
2412 The Emacs commands which work with `defun's, e.g. \\[beginning-of-defun], deal
2413 with nested `def' and `class' blocks. They take the innermost one as
2414 current without distinguishing method and class definitions. Used multiple
2415 times, they move over others at the same indentation level until they reach
2416 the end of definitions at that level, when they move up a level.
2417 \\<python-mode-map>
2418 Colon is electric: it outdents the line if appropriate, e.g. for
2419 an else statement. \\[python-backspace] at the beginning of an indented statement
2420 deletes a level of indentation to close the current block; otherwise it
2421 deletes a character backward. TAB indents the current line relative to
2422 the preceding code. Successive TABs, with no intervening command, cycle
2423 through the possibilities for indentation on the basis of enclosing blocks.
2425 \\[fill-paragraph] fills comments and multi-line strings appropriately, but has no
2426 effect outside them.
2428 Supports Eldoc mode (only for functions, using a Python process),
2429 Info-Look and Imenu. In Outline minor mode, `class' and `def'
2430 lines count as headers. Symbol completion is available in the
2431 same way as in the Python shell using the `rlcompleter' module
2432 and this is added to the Hippie Expand functions locally if
2433 Hippie Expand mode is turned on. Completion of symbols of the
2434 form x.y only works if the components are literal
2435 module/attribute names, not variables. An abbrev table is set up
2436 with skeleton expansions for compound statement templates.
2438 \\{python-mode-map}"
2439 :group 'python
2440 (set (make-local-variable 'font-lock-defaults)
2441 '(python-font-lock-keywords nil nil nil nil
2442 (font-lock-syntactic-keywords
2443 . python-font-lock-syntactic-keywords)
2444 ;; This probably isn't worth it.
2445 ;; (font-lock-syntactic-face-function
2446 ;; . python-font-lock-syntactic-face-function)
2448 (set (make-local-variable 'parse-sexp-lookup-properties) t)
2449 (set (make-local-variable 'parse-sexp-ignore-comments) t)
2450 (set (make-local-variable 'comment-start) "# ")
2451 (set (make-local-variable 'indent-line-function) #'python-indent-line)
2452 (set (make-local-variable 'indent-region-function) #'python-indent-region)
2453 (set (make-local-variable 'paragraph-start) "\\s-*$")
2454 (set (make-local-variable 'fill-paragraph-function) 'python-fill-paragraph)
2455 (set (make-local-variable 'require-final-newline) mode-require-final-newline)
2456 (set (make-local-variable 'add-log-current-defun-function)
2457 #'python-current-defun)
2458 (set (make-local-variable 'outline-regexp)
2459 (rx (* space) (or "class" "def" "elif" "else" "except" "finally"
2460 "for" "if" "try" "while" "with")
2461 symbol-end))
2462 (set (make-local-variable 'outline-heading-end-regexp) ":\\s-*\n")
2463 (set (make-local-variable 'outline-level) #'python-outline-level)
2464 (set (make-local-variable 'open-paren-in-column-0-is-defun-start) nil)
2465 (make-local-variable 'python-saved-check-command)
2466 (set (make-local-variable 'beginning-of-defun-function)
2467 'python-beginning-of-defun)
2468 (set (make-local-variable 'end-of-defun-function) 'python-end-of-defun)
2469 (add-hook 'which-func-functions 'python-which-func nil t)
2470 (setq imenu-create-index-function #'python-imenu-create-index)
2471 (set (make-local-variable 'eldoc-documentation-function)
2472 #'python-eldoc-function)
2473 (add-hook 'eldoc-mode-hook
2474 (lambda () (run-python nil t)) ; need it running
2475 nil t)
2476 (add-hook 'completion-at-point-functions
2477 'python-completion-at-point nil 'local)
2478 ;; Fixme: should be in hideshow. This seems to be of limited use
2479 ;; since it isn't (can't be) indentation-based. Also hide-level
2480 ;; doesn't seem to work properly.
2481 (add-to-list 'hs-special-modes-alist
2482 `(python-mode "^\\s-*\\(?:def\\|class\\)\\>" nil "#"
2483 ,(lambda (arg)
2484 (python-end-of-defun)
2485 (skip-chars-backward " \t\n"))
2486 nil))
2487 (set (make-local-variable 'skeleton-further-elements)
2488 '((< '(backward-delete-char-untabify (min python-indent
2489 (current-column))))
2490 (^ '(- (1+ (current-indentation))))))
2491 ;; Python defines TABs as being 8-char wide.
2492 (set (make-local-variable 'tab-width) 8)
2493 (unless font-lock-mode (font-lock-mode 1))
2494 (when python-guess-indent (python-guess-indent))
2495 ;; Let's make it harder for the user to shoot himself in the foot.
2496 (unless (= tab-width python-indent)
2497 (setq indent-tabs-mode nil))
2498 (set (make-local-variable 'python-command) python-python-command)
2499 (python-find-imports)
2500 (unless (boundp 'python-mode-running) ; kill the recursion from jython-mode
2501 (let ((python-mode-running t))
2502 (python-maybe-jython))))
2504 ;; Not done automatically in Emacs 21 or 22.
2505 (defcustom python-mode-hook nil
2506 "Hook run when entering Python mode."
2507 :group 'python
2508 :type 'hook)
2509 (custom-add-option 'python-mode-hook 'imenu-add-menubar-index)
2510 (custom-add-option 'python-mode-hook
2511 (lambda ()
2512 "Turn off Indent Tabs mode."
2513 (setq indent-tabs-mode nil)))
2514 (custom-add-option 'python-mode-hook 'turn-on-eldoc-mode)
2515 (custom-add-option 'python-mode-hook 'abbrev-mode)
2516 (custom-add-option 'python-mode-hook 'python-setup-brm)
2518 ;;;###autoload
2519 (define-derived-mode jython-mode python-mode "Jython"
2520 "Major mode for editing Jython files.
2521 Like `python-mode', but sets up parameters for Jython subprocesses.
2522 Runs `jython-mode-hook' after `python-mode-hook'."
2523 :group 'python
2524 (set (make-local-variable 'python-command) python-jython-command))
2528 ;; pdbtrack features
2530 (defun python-comint-output-filter-function (string)
2531 "Watch output for Python prompt and exec next file waiting in queue.
2532 This function is appropriate for `comint-output-filter-functions'."
2533 ;; TBD: this should probably use split-string
2534 (when (and (or (string-equal string ">>> ")
2535 (and (>= (length string) 5)
2536 (string-equal (substring string -5) "\n>>> ")))
2537 python-file-queue)
2538 (condition-case nil
2539 (delete-file (car python-file-queue))
2540 (error nil))
2541 (setq python-file-queue (cdr python-file-queue))
2542 (if python-file-queue
2543 (let ((pyproc (get-buffer-process (current-buffer))))
2544 (python-execute-file pyproc (car python-file-queue))))))
2546 (defun python-pdbtrack-overlay-arrow (activation)
2547 "Activate or deactivate arrow at beginning-of-line in current buffer."
2548 (if activation
2549 (progn
2550 (setq overlay-arrow-position (make-marker)
2551 overlay-arrow-string "=>"
2552 python-pdbtrack-is-tracking-p t)
2553 (set-marker overlay-arrow-position
2554 (save-excursion (beginning-of-line) (point))
2555 (current-buffer)))
2556 (setq overlay-arrow-position nil
2557 python-pdbtrack-is-tracking-p nil)))
2559 (defun python-pdbtrack-track-stack-file (text)
2560 "Show the file indicated by the pdb stack entry line, in a separate window.
2562 Activity is disabled if the buffer-local variable
2563 `python-pdbtrack-do-tracking-p' is nil.
2565 We depend on the pdb input prompt being a match for
2566 `python-pdbtrack-input-prompt'.
2568 If the traceback target file path is invalid, we look for the
2569 most recently visited python-mode buffer which either has the
2570 name of the current function or class, or which defines the
2571 function or class. This is to provide for scripts not in the
2572 local filesytem (e.g., Zope's 'Script \(Python)', but it's not
2573 Zope specific). If you put a copy of the script in a buffer
2574 named for the script and activate python-mode, then pdbtrack will
2575 find it."
2576 ;; Instead of trying to piece things together from partial text
2577 ;; (which can be almost useless depending on Emacs version), we
2578 ;; monitor to the point where we have the next pdb prompt, and then
2579 ;; check all text from comint-last-input-end to process-mark.
2581 ;; Also, we're very conservative about clearing the overlay arrow,
2582 ;; to minimize residue. This means, for instance, that executing
2583 ;; other pdb commands wipe out the highlight. You can always do a
2584 ;; 'where' (aka 'w') PDB command to reveal the overlay arrow.
2586 (let* ((origbuf (current-buffer))
2587 (currproc (get-buffer-process origbuf)))
2589 (if (not (and currproc python-pdbtrack-do-tracking-p))
2590 (python-pdbtrack-overlay-arrow nil)
2592 (let* ((procmark (process-mark currproc))
2593 (block (buffer-substring (max comint-last-input-end
2594 (- procmark
2595 python-pdbtrack-track-range))
2596 procmark))
2597 target target_fname target_lineno target_buffer)
2599 (if (not (string-match (concat python-pdbtrack-input-prompt "$") block))
2600 (python-pdbtrack-overlay-arrow nil)
2602 (setq target (python-pdbtrack-get-source-buffer block))
2604 (if (stringp target)
2605 (progn
2606 (python-pdbtrack-overlay-arrow nil)
2607 (message "pdbtrack: %s" target))
2609 (setq target_lineno (car target)
2610 target_buffer (cadr target)
2611 target_fname (buffer-file-name target_buffer))
2612 (switch-to-buffer-other-window target_buffer)
2613 (goto-char (point-min))
2614 (forward-line (1- target_lineno))
2615 (message "pdbtrack: line %s, file %s" target_lineno target_fname)
2616 (python-pdbtrack-overlay-arrow t)
2617 (pop-to-buffer origbuf t)
2618 ;; in large shell buffers, above stuff may cause point to lag output
2619 (goto-char procmark)
2620 )))))
2623 (defun python-pdbtrack-get-source-buffer (block)
2624 "Return line number and buffer of code indicated by block's traceback text.
2626 We look first to visit the file indicated in the trace.
2628 Failing that, we look for the most recently visited python-mode buffer
2629 with the same name or having the named function.
2631 If we're unable find the source code we return a string describing the
2632 problem."
2634 (if (not (string-match python-pdbtrack-stack-entry-regexp block))
2636 "Traceback cue not found"
2638 (let* ((filename (match-string 1 block))
2639 (lineno (string-to-number (match-string 2 block)))
2640 (funcname (match-string 3 block))
2641 funcbuffer)
2643 (cond ((file-exists-p filename)
2644 (list lineno (find-file-noselect filename)))
2646 ((setq funcbuffer (python-pdbtrack-grub-for-buffer funcname lineno))
2647 (if (string-match "/Script (Python)$" filename)
2648 ;; Add in number of lines for leading '##' comments:
2649 (setq lineno
2650 (+ lineno
2651 (with-current-buffer funcbuffer
2652 (if (equal (point-min)(point-max))
2654 (count-lines
2655 (point-min)
2656 (max (point-min)
2657 (string-match "^\\([^#]\\|#[^#]\\|#$\\)"
2658 (buffer-substring
2659 (point-min) (point-max)))
2660 )))))))
2661 (list lineno funcbuffer))
2663 ((= (elt filename 0) ?\<)
2664 (format "(Non-file source: '%s')" filename))
2666 (t (format "Not found: %s(), %s" funcname filename)))
2671 (defun python-pdbtrack-grub-for-buffer (funcname lineno)
2672 "Find recent python-mode buffer named, or having function named funcname."
2673 (let ((buffers (buffer-list))
2675 got)
2676 (while (and buffers (not got))
2677 (setq buf (car buffers)
2678 buffers (cdr buffers))
2679 (if (and (with-current-buffer buf
2680 (string= major-mode "python-mode"))
2681 (or (string-match funcname (buffer-name buf))
2682 (string-match (concat "^\\s-*\\(def\\|class\\)\\s-+"
2683 funcname "\\s-*(")
2684 (with-current-buffer buf
2685 (buffer-substring (point-min)
2686 (point-max))))))
2687 (setq got buf)))
2688 got))
2690 (defun python-toggle-shells (arg)
2691 "Toggles between the CPython and JPython shells.
2693 With positive argument ARG (interactively \\[universal-argument]),
2694 uses the CPython shell, with negative ARG uses the JPython shell, and
2695 with a zero argument, toggles the shell.
2697 Programmatically, ARG can also be one of the symbols `cpython' or
2698 `jpython', equivalent to positive arg and negative arg respectively."
2699 (interactive "P")
2700 ;; default is to toggle
2701 (if (null arg)
2702 (setq arg 0))
2703 ;; preprocess arg
2704 (cond
2705 ((equal arg 0)
2706 ;; toggle
2707 (if (string-equal python-which-bufname "Python")
2708 (setq arg -1)
2709 (setq arg 1)))
2710 ((equal arg 'cpython) (setq arg 1))
2711 ((equal arg 'jpython) (setq arg -1)))
2712 (let (msg)
2713 (cond
2714 ((< 0 arg)
2715 ;; set to CPython
2716 (setq python-which-shell python-python-command
2717 python-which-args python-python-command-args
2718 python-which-bufname "Python"
2719 msg "CPython"
2720 mode-name "Python"))
2721 ((> 0 arg)
2722 (setq python-which-shell python-jython-command
2723 python-which-args python-jython-command-args
2724 python-which-bufname "JPython"
2725 msg "JPython"
2726 mode-name "JPython")))
2727 (message "Using the %s shell" msg)))
2729 ;; Python subprocess utilities and filters
2730 (defun python-execute-file (proc filename)
2731 "Send to Python interpreter process PROC \"execfile('FILENAME')\".
2732 Make that process's buffer visible and force display. Also make
2733 comint believe the user typed this string so that
2734 `kill-output-from-shell' does The Right Thing."
2735 (let ((curbuf (current-buffer))
2736 (procbuf (process-buffer proc))
2737 ; (comint-scroll-to-bottom-on-output t)
2738 (msg (format "## working on region in file %s...\n" filename))
2739 ;; add some comment, so that we can filter it out of history
2740 (cmd (format "execfile(r'%s') # PYTHON-MODE\n" filename)))
2741 (unwind-protect
2742 (with-current-buffer procbuf
2743 (goto-char (point-max))
2744 (move-marker (process-mark proc) (point))
2745 (funcall (process-filter proc) proc msg))
2746 (set-buffer curbuf))
2747 (process-send-string proc cmd)))
2748 ;;;###autoload
2749 (defun python-shell (&optional argprompt)
2750 "Start an interactive Python interpreter in another window.
2751 This is like Shell mode, except that Python is running in the window
2752 instead of a shell. See the `Interactive Shell' and `Shell Mode'
2753 sections of the Emacs manual for details, especially for the key
2754 bindings active in the `*Python*' buffer.
2756 With optional \\[universal-argument], the user is prompted for the
2757 flags to pass to the Python interpreter. This has no effect when this
2758 command is used to switch to an existing process, only when a new
2759 process is started. If you use this, you will probably want to ensure
2760 that the current arguments are retained (they will be included in the
2761 prompt). This argument is ignored when this function is called
2762 programmatically, or when running in Emacs 19.34 or older.
2764 Note: You can toggle between using the CPython interpreter and the
2765 JPython interpreter by hitting \\[python-toggle-shells]. This toggles
2766 buffer local variables which control whether all your subshell
2767 interactions happen to the `*JPython*' or `*Python*' buffers (the
2768 latter is the name used for the CPython buffer).
2770 Warning: Don't use an interactive Python if you change sys.ps1 or
2771 sys.ps2 from their default values, or if you're running code that
2772 prints `>>> ' or `... ' at the start of a line. `python-mode' can't
2773 distinguish your output from Python's output, and assumes that `>>> '
2774 at the start of a line is a prompt from Python. Similarly, the Emacs
2775 Shell mode code assumes that both `>>> ' and `... ' at the start of a
2776 line are Python prompts. Bad things can happen if you fool either
2777 mode.
2779 Warning: If you do any editing *in* the process buffer *while* the
2780 buffer is accepting output from Python, do NOT attempt to `undo' the
2781 changes. Some of the output (nowhere near the parts you changed!) may
2782 be lost if you do. This appears to be an Emacs bug, an unfortunate
2783 interaction between undo and process filters; the same problem exists in
2784 non-Python process buffers using the default (Emacs-supplied) process
2785 filter."
2786 (interactive "P")
2787 ;; Set the default shell if not already set
2788 (when (null python-which-shell)
2789 (python-toggle-shells python-default-interpreter))
2790 (let ((args python-which-args))
2791 (when (and argprompt
2792 (called-interactively-p 'interactive)
2793 (fboundp 'split-string))
2794 ;; TBD: Perhaps force "-i" in the final list?
2795 (setq args (split-string
2796 (read-string (concat python-which-bufname
2797 " arguments: ")
2798 (concat
2799 (mapconcat 'identity python-which-args " ") " ")
2800 ))))
2801 (switch-to-buffer-other-window
2802 (apply 'make-comint python-which-bufname python-which-shell nil args))
2803 (make-local-variable 'comint-prompt-regexp)
2804 (set-process-sentinel (get-buffer-process (current-buffer))
2805 'python-sentinel)
2806 (setq comint-prompt-regexp "^>>> \\|^[.][.][.] \\|^(pdb) ")
2807 (add-hook 'comint-output-filter-functions
2808 'python-comint-output-filter-function nil t)
2809 ;; pdbtrack
2810 (set-syntax-table python-mode-syntax-table)
2811 (use-local-map python-shell-map)))
2813 (defun python-pdbtrack-toggle-stack-tracking (arg)
2814 (interactive "P")
2815 (if (not (get-buffer-process (current-buffer)))
2816 (error "No process associated with buffer '%s'" (current-buffer)))
2817 ;; missing or 0 is toggle, >0 turn on, <0 turn off
2818 (if (or (not arg)
2819 (zerop (setq arg (prefix-numeric-value arg))))
2820 (setq python-pdbtrack-do-tracking-p (not python-pdbtrack-do-tracking-p))
2821 (setq python-pdbtrack-do-tracking-p (> arg 0)))
2822 (message "%sabled Python's pdbtrack"
2823 (if python-pdbtrack-do-tracking-p "En" "Dis")))
2825 (defun turn-on-pdbtrack ()
2826 (interactive)
2827 (python-pdbtrack-toggle-stack-tracking 1))
2829 (defun turn-off-pdbtrack ()
2830 (interactive)
2831 (python-pdbtrack-toggle-stack-tracking 0))
2833 (defun python-sentinel (proc msg)
2834 (setq overlay-arrow-position nil))
2836 (provide 'python)
2837 (provide 'python-21)
2839 ;; arch-tag: 6fce1d99-a704-4de9-ba19-c6e4912b0554
2840 ;;; python.el ends here