1 ;;; python-mode.el --- Major mode for editing Python programs
3 ;; Copyright (C) 1992,1993,1994 Tim Peters
5 ;; Author: 2003-2011 https://launchpad.net/python-mode
6 ;; 1995-2002 Barry A. Warsaw
7 ;; 1992-1994 Tim Peters
8 ;; Maintainer: python-mode@python.org
10 ;; Keywords: python languages oop
12 (defconst py-version "5.2.0"
13 "`python-mode' version number.")
15 ;; This file is part of python-mode.el.
17 ;; python-mode.el is free software: you can redistribute it and/or modify it
18 ;; under the terms of the GNU General Public License as published by the Free
19 ;; Software Foundation, either version 3 of the License, or (at your option)
22 ;; python-mode.el is distributed in the hope that it will be useful, but
23 ;; WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
24 ;; or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
27 ;; You should have received a copy of the GNU General Public License along
28 ;; with python-mode.el. If not, see <http://www.gnu.org/licenses/>.
32 ;; This is a major mode for editing Python programs. It was developed by Tim
33 ;; Peters after an original idea by Michael A. Guravage. Tim subsequently
34 ;; left the net and in 1995, Barry Warsaw inherited the mode. Tim came back
35 ;; but disavowed all responsibility for the mode. In fact, we suspect he
36 ;; doesn't even use Emacs any more <wink>. In 2003, python-mode.el was moved
37 ;; to its own SourceForge project apart from the Python project, and in 2008
38 ;; it was moved to Launchpad for all project administration. python-mode.el
39 ;; is maintained by the volunteers at the python-mode@python.org mailing
42 ;; python-mode.el is different than, and pre-dates by many years, the
43 ;; python.el that comes with FSF Emacs. We'd like to merge the two modes but
44 ;; have few cycles to do so. Volunteers are welcome.
46 ;; pdbtrack support contributed by Ken Manheimer, April 2001. Skip Montanaro
47 ;; has also contributed significantly to python-mode's development.
49 ;; Please use Launchpad to submit bugs or patches:
51 ;; https://launchpad.net/python-mode
55 ;; To install, just drop this file into a directory on your load-path and
56 ;; byte-compile it. To set up Emacs to automatically edit files ending in
57 ;; ".py" using python-mode, add to your emacs init file
59 ;; GNU Emacs: ~/.emacs, ~/.emacs.el, or ~/.emacs.d/init.el
61 ;; XEmacs: ~/.xemacs/init.el
63 ;; the following code:
65 ;; (setq auto-mode-alist (cons '("\\.py$" . python-mode) auto-mode-alist))
66 ;; (setq interpreter-mode-alist (cons '("python" . python-mode)
67 ;; interpreter-mode-alist))
68 ;; (autoload 'python-mode "python-mode" "Python editing mode." t)
70 ;; In XEmacs syntax highlighting should be enabled automatically. In GNU
71 ;; Emacs you may have to add these lines to your init file:
73 ;; (global-font-lock-mode t)
74 ;; (setq font-lock-maximum-decoration t)
78 ;; As mentioned above, please use the Launchpad python-mode project for
79 ;; submitting bug reports or patches. The old recommendation, to use C-c C-b
80 ;; will still work, but those reports have a higher chance of getting buried
81 ;; in our inboxes. Please include a complete, but concise code sample and a
82 ;; recipe for reproducing the bug. Send suggestions and other comments to
83 ;; python-mode@python.org.
85 ;; When in a Python mode buffer, do a C-h m for more help. It's doubtful that
86 ;; a texinfo manual would be very useful, but if you want to contribute one,
87 ;; we'll certainly accept it!
98 ;; user definable variables
99 ;; vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
102 "Support for the Python programming language, <http://www.python.org/>"
106 (defcustom py-tab-always-indent t
107 "*Non-nil means TAB in Python mode should always reindent the current line,
108 regardless of where in the line point is when the TAB command is used."
112 (defcustom py-python-command "python"
113 "*Shell command used to start Python interpreter."
117 (make-obsolete-variable 'py-jpython-command 'py-jython-command)
118 (defcustom py-jython-command "jython"
119 "*Shell command used to start the Jython interpreter."
122 :tag "Jython Command")
124 (defcustom py-default-interpreter 'cpython
125 "*Which Python interpreter is used by default.
126 The value for this variable can be either `cpython' or `jython'.
128 When the value is `cpython', the variables `py-python-command' and
129 `py-python-command-args' are consulted to determine the interpreter
130 and arguments to use.
132 When the value is `jython', the variables `py-jython-command' and
133 `py-jython-command-args' are consulted to determine the interpreter
134 and arguments to use.
136 Note that this variable is consulted only the first time that a Python
137 mode buffer is visited during an Emacs session. After that, use
138 \\[py-toggle-shells] to change the interpreter shell."
139 :type '(choice (const :tag "Python (a.k.a. CPython)" cpython)
140 (const :tag "Jython" jython))
143 (defcustom py-python-command-args '("-i")
144 "*List of string arguments to be used when starting a Python shell."
145 :type '(repeat string)
148 (make-obsolete-variable 'py-jpython-command-args 'py-jython-command-args)
149 (defcustom py-jython-command-args '("-i")
150 "*List of string arguments to be used when starting a Jython shell."
151 :type '(repeat string)
153 :tag "Jython Command Args")
155 (defcustom py-indent-offset 4
156 "*Amount of offset per level of indentation.
157 `\\[py-guess-indent-offset]' can usually guess a good value when
158 you're editing someone else's Python code."
162 (defcustom py-continuation-offset 4
163 "*Additional amount of offset to give for some continuation lines.
164 Continuation lines are those that immediately follow a backslash
165 terminated line. Only those continuation lines for a block opening
166 statement are given this extra offset."
170 (defcustom py-smart-indentation t
171 "*Should `python-mode' try to automagically set some indentation variables?
172 When this variable is non-nil, two things happen when a buffer is set
175 1. `py-indent-offset' is guessed from existing code in the buffer.
176 Only guessed values between 2 and 8 are considered. If a valid
177 guess can't be made (perhaps because you are visiting a new
178 file), then the value in `py-indent-offset' is used.
180 2. `indent-tabs-mode' is turned off if `py-indent-offset' does not
181 equal `tab-width' (`indent-tabs-mode' is never turned on by
182 Python mode). This means that for newly written code, tabs are
183 only inserted in indentation if one tab is one indentation
184 level, otherwise only spaces are used.
186 Note that both these settings occur *after* `python-mode-hook' is run,
187 so if you want to defeat the automagic configuration, you must also
188 set `py-smart-indentation' to nil in your `python-mode-hook'."
192 (defcustom py-align-multiline-strings-p t
193 "*Flag describing how multi-line triple quoted strings are aligned.
194 When this flag is non-nil, continuation lines are lined up under the
195 preceding line's indentation. When this flag is nil, continuation
196 lines are aligned to column zero."
197 :type '(choice (const :tag "Align under preceding line" t)
198 (const :tag "Align to column zero" nil))
201 (defcustom py-block-comment-prefix "##"
202 "*String used by \\[comment-region] to comment out a block of code.
203 This should follow the convention for non-indenting comment lines so
204 that the indentation commands won't get confused (i.e., the string
205 should be of the form `#x...' where `x' is not a blank or a tab, and
206 `...' is arbitrary). However, this string should not end in whitespace."
210 (defcustom py-honor-comment-indentation t
211 "*Controls how comment lines influence subsequent indentation.
213 When nil, all comment lines are skipped for indentation purposes, and
214 if possible, a faster algorithm is used (i.e. X/Emacs 19 and beyond).
216 When t, lines that begin with a single `#' are a hint to subsequent
217 line indentation. If the previous line is such a comment line (as
218 opposed to one that starts with `py-block-comment-prefix'), then its
219 indentation is used as a hint for this line's indentation. Lines that
220 begin with `py-block-comment-prefix' are ignored for indentation
223 When not nil or t, comment lines that begin with a single `#' are used
224 as indentation hints, unless the comment character is in column zero."
226 (const :tag "Skip all comment lines (fast)" nil)
227 (const :tag "Single # `sets' indentation for next line" t)
228 (const :tag "Single # `sets' indentation except at column zero"
233 (defcustom py-temp-directory
234 (let ((ok '(lambda (x)
236 (setq x (expand-file-name x)) ; always true
240 (or (funcall ok (getenv "TMPDIR"))
241 (funcall ok "/usr/tmp")
243 (funcall ok "/var/tmp")
246 "Couldn't find a usable temp directory -- set `py-temp-directory'")))
247 "*Directory used for temporary files created by a *Python* process.
248 By default, the first directory from this list that exists and that you
249 can write into: the value (if any) of the environment variable TMPDIR,
250 /usr/tmp, /tmp, /var/tmp, or the current directory."
254 (defcustom py-beep-if-tab-change t
255 "*Ring the bell if `tab-width' is changed.
256 If a comment of the form
258 \t# vi:set tabsize=<number>:
260 is found before the first code line when the file is entered, and the
261 current value of (the general Emacs variable) `tab-width' does not
262 equal <number>, `tab-width' is set to <number>, a message saying so is
263 displayed in the echo area, and if `py-beep-if-tab-change' is non-nil
264 the Emacs bell is also rung as a warning."
268 (defcustom py-jump-on-exception t
269 "*Jump to innermost exception frame in *Python Output* buffer.
270 When this variable is non-nil and an exception occurs when running
271 Python code synchronously in a subprocess, jump immediately to the
272 source code of the innermost traceback frame."
276 (defcustom py-ask-about-save t
277 "If not nil, ask about which buffers to save before executing some code.
278 Otherwise, all modified buffers are saved without asking."
282 (defcustom py-backspace-function 'backward-delete-char-untabify
283 "*Function called by `py-electric-backspace' when deleting backwards."
287 (defcustom py-delete-function 'delete-char
288 "*Function called by `py-electric-delete' when deleting forwards."
292 (defcustom py-imenu-show-method-args-p nil
293 "*Controls echoing of arguments of functions & methods in the Imenu buffer.
294 When non-nil, arguments are printed."
297 (make-variable-buffer-local 'py-indent-offset)
299 (defcustom py-pdbtrack-do-tracking-p t
300 "*Controls whether the pdbtrack feature is enabled or not.
301 When non-nil, pdbtrack is enabled in all comint-based buffers,
302 e.g. shell buffers and the *Python* buffer. When using pdb to debug a
303 Python program, pdbtrack notices the pdb prompt and displays the
304 source file and line that the program is stopped at, much the same way
305 as gud-mode does for debugging C programs with gdb."
308 (make-variable-buffer-local 'py-pdbtrack-do-tracking-p)
310 (defcustom py-pdbtrack-minor-mode-string " PDB"
311 "*String to use in the minor mode list when pdbtrack is enabled."
315 (defcustom py-import-check-point-max
317 "Maximum number of characters to search for a Java-ish import statement.
318 When `python-mode' tries to calculate the shell to use (either a
319 CPython or a Jython shell), it looks at the so-called `shebang' line
320 -- i.e. #! line. If that's not available, it looks at some of the
321 file heading imports to see if they look Java-like."
326 (make-obsolete-variable 'py-jpython-packages 'py-jython-packages)
327 (defcustom py-jython-packages
328 '("java" "javax" "org" "com")
329 "Imported packages that imply `jython-mode'."
330 :type '(repeat string)
334 (defvar py-master-file nil
335 "If non-nil, execute the named file instead of the buffer's file.
336 The intent is to allow you to set this variable in the file's local
337 variable section, e.g.:
340 # py-master-file: \"master.py\"
343 so that typing \\[py-execute-buffer] in that buffer executes the named
344 master file instead of the buffer's file. If the file name has a
345 relative path, the value of variable `default-directory' for the
346 buffer is prepended to come up with a file name.")
347 (make-variable-buffer-local 'py-master-file)
349 (defcustom py-pychecker-command "pychecker"
350 "*Shell command used to run Pychecker."
353 :tag "Pychecker Command")
355 (defcustom py-pychecker-command-args '("--stdlib")
356 "*List of string arguments to be passed to pychecker."
357 :type '(repeat string)
359 :tag "Pychecker Command Args")
361 (defvar py-shell-alist
362 '(("jython" . 'jython)
363 ("python" . 'cpython))
364 "*Alist of interpreters and python shells. Used by `py-choose-shell'
365 to select the appropriate python interpreter mode for a file.")
367 (defcustom py-shell-input-prompt-1-regexp "^>>> "
368 "*A regular expression to match the input prompt of the shell."
372 (defcustom py-shell-input-prompt-2-regexp "^[.][.][.] "
373 "*A regular expression to match the input prompt of the shell after the
374 first line of input."
378 (defcustom py-shell-switch-buffers-on-execute t
379 "*Controls switching to the Python buffer where commands are
380 executed. When non-nil the buffer switches to the Python buffer, if
381 not no switching occurs."
385 (defcustom py-hide-show-keywords
387 "class" "def" "elif" "else" "except"
388 "for" "if" "while" "finally" "try"
391 "*Keywords that can be hidden by hide-show"
392 :type '(repeat string)
395 (defcustom py-hide-show-hide-docstrings t
396 "*Controls if doc strings can be hidden by hide-show"
402 ;; ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
403 ;; NO USER DEFINABLE VARIABLES BEYOND THIS POINT
405 (defvar py-line-number-offset 0
406 "When an exception occurs as a result of py-execute-region, a
407 subsequent py-up-exception needs the line number where the region
408 started, in order to jump to the correct file line. This variable is
409 set in py-execute-region and used in py-jump-to-exception.")
411 ;; 2009-09-10 a.roehler@web.de changed section start
412 ;; from python.el, version "22.1"
414 (defconst python-font-lock-syntactic-keywords
415 '(("[^\\]\\\\\\(?:\\\\\\\\\\)*\\(\\s\"\\)\\1\\(\\1\\)"
418 ("\\([RUBrub]?\\)[Rr]?\\(\\s\"\\)\\2\\(\\2\\)"
420 (python-quote-syntax 1))
422 (python-quote-syntax 2))
424 (python-quote-syntax 3)))))
426 (defun python-quote-syntax (n)
427 "Put `syntax-table' property correctly on triple quote.
428 Used for syntactic keywords. N is the match number (1, 2 or 3)."
429 ;; Given a triple quote, we have to check the context to know
430 ;; whether this is an opening or closing triple or whether it's
431 ;; quoted anyhow, and should be ignored. (For that we need to do
432 ;; the same job as `syntax-ppss' to be correct and it seems to be OK
433 ;; to use it here despite initial worries.) We also have to sort
434 ;; out a possible prefix -- well, we don't _have_ to, but I think it
435 ;; should be treated as part of the string.
437 ;; ur"""ar""" x='"' # """
440 ;; x '"""' x """ \"""" x
442 (goto-char (match-beginning 0))
444 ;; Consider property for the last char if in a fenced string.
446 (let* ((font-lock-syntactic-keywords nil)
447 (syntax (syntax-ppss)))
448 (when (eq t (nth 3 syntax)) ; after unclosed fence
449 (goto-char (nth 8 syntax)) ; fence position
450 (skip-chars-forward "uUrRbB") ; skip any prefix
451 ;; Is it a matching sequence?
452 (if (eq (char-after) (char-after (match-beginning 2)))
453 (if (featurep 'xemacs)
455 (eval-when-compile (string-to-syntax "|")))
457 ;; Consider property for initial char, accounting for prefixes.
458 ((or (and (= n 2) ; leading quote (not prefix)
459 (= (match-beginning 1) (match-end 1))) ; prefix is null
460 (and (= n 1) ; prefix
461 (/= (match-beginning 1) (match-end 1)))) ; non-empty
462 (let ((font-lock-syntactic-keywords nil))
463 (unless (eq 'string (syntax-ppss-context (syntax-ppss)))
464 ;; (eval-when-compile (string-to-syntax "|"))
465 (if (featurep 'xemacs)
467 (eval-when-compile (string-to-syntax "|")))
469 ;; Otherwise (we're in a non-matching string) the property is
473 (setq py-mode-syntax-table
474 (let ((table (make-syntax-table))
475 (tablelookup (if (featurep 'xemacs)
478 ;; Give punctuation syntax to ASCII that normally has symbol
479 ;; syntax or has word syntax and isn't a letter.
480 (if (featurep 'xemacs)
481 (setq table (standard-syntax-table))
482 (let ((symbol (if (featurep 'xemacs) '(3)(string-to-syntax "_")))
483 ;; (symbol (string-to-syntax "_"))
484 (sst (standard-syntax-table)))
487 (if (equal symbol (funcall tablelookup sst i))
488 (modify-syntax-entry i "." table))))))
489 (modify-syntax-entry ?$ "." table)
490 (modify-syntax-entry ?% "." table)
492 (modify-syntax-entry ?# "<" table)
493 (modify-syntax-entry ?\n ">" table)
494 (modify-syntax-entry ?' "\"" table)
495 (modify-syntax-entry ?` "$" table)
496 (modify-syntax-entry ?\_ "w" table)
499 (defsubst python-in-string/comment ()
500 "Return non-nil if point is in a Python literal (a comment or string)."
501 ;; We don't need to save the match data.
502 (nth 8 (syntax-ppss)))
504 (defconst python-space-backslash-table
505 (let ((table (copy-syntax-table py-mode-syntax-table)))
506 (modify-syntax-entry ?\\ " " table)
508 "`python-mode-syntax-table' with backslash given whitespace syntax.")
510 ;; 2009-09-10 a.roehler@web.de changed section end
512 (defconst py-emacs-features
515 "A list of features extant in the Emacs you are using.
516 There are many flavors of Emacs out there, with different levels of
517 support for features needed by `python-mode'.")
519 ;; Face for None, True, False, self, and Ellipsis
520 (defvar py-pseudo-keyword-face 'py-pseudo-keyword-face
521 "Face for pseudo keywords in Python mode, like self, True, False, Ellipsis.")
522 (make-face 'py-pseudo-keyword-face)
524 ;; PEP 318 decorators
525 (defvar py-decorators-face 'py-decorators-face
526 "Face method decorators.")
527 (make-face 'py-decorators-face)
530 (defvar py-builtins-face 'py-builtins-face
531 "Face for builtins like TypeError, object, open, and exec.")
532 (make-face 'py-builtins-face)
534 ;; XXX, TODO, and FIXME comments and such
535 (defvar py-XXX-tag-face 'py-XXX-tag-face
536 "Face for XXX, TODO, and FIXME tags")
537 (make-face 'py-XXX-tag-face)
539 ;; Face for class names
540 (defvar py-class-name-face 'py-class-name-face
541 "Face for Python class names.")
542 (make-face 'py-class-name-face)
544 ;; Face for exception names
545 (defvar py-exception-name-face 'py-exception-name-face
546 "Face for exception names like TypeError.")
547 (make-face 'py-exception-name-face)
549 (defun py-font-lock-mode-hook ()
550 (or (face-differs-from-default-p 'py-pseudo-keyword-face)
551 (copy-face 'font-lock-keyword-face 'py-pseudo-keyword-face))
552 (or (face-differs-from-default-p 'py-builtins-face)
553 (copy-face 'font-lock-keyword-face 'py-builtins-face))
554 (or (face-differs-from-default-p 'py-decorators-face)
555 (copy-face 'py-pseudo-keyword-face 'py-decorators-face))
556 (or (face-differs-from-default-p 'py-XXX-tag-face)
557 (copy-face 'font-lock-comment-face 'py-XXX-tag-face))
558 (or (face-differs-from-default-p 'py-class-name-face)
559 (copy-face 'font-lock-type-face 'py-class-name-face))
560 (or (face-differs-from-default-p 'py-exception-name-face)
561 (copy-face 'font-lock-builtin-face 'py-exception-name-face))
564 (add-hook 'font-lock-mode-hook 'py-font-lock-mode-hook)
566 (defvar python-font-lock-keywords
567 (let ((kw1 (mapconcat 'identity
568 '("and" "assert" "break" "class"
569 "continue" "def" "del" "elif"
570 "else" "except" "for" "from"
571 "global" "if" "import" "in"
572 "is" "lambda" "not" "or"
573 "pass" "raise" "as" "return"
574 "while" "with" "yield"
577 (kw2 (mapconcat 'identity
578 '("else:" "except:" "finally:" "try:")
580 (kw3 (mapconcat 'identity
581 ;; Don't include Ellipsis in this list, since it is
582 ;; already defined as a pseudo keyword.
584 "__import__" "__name__" "abs" "all" "any" "apply"
585 "basestring" "bin" "bool" "buffer" "bytearray"
586 "callable" "chr" "classmethod" "cmp" "coerce"
587 "compile" "complex" "copyright" "credits"
588 "delattr" "dict" "dir" "divmod" "enumerate" "eval"
589 "exec" "execfile" "exit" "file" "filter" "float"
590 "format" "getattr" "globals" "hasattr" "hash" "help"
591 "hex" "id" "input" "int" "intern" "isinstance"
592 "issubclass" "iter" "len" "license" "list" "locals"
593 "long" "map" "max" "memoryview" "min" "next"
594 "object" "oct" "open" "ord" "pow" "print" "property"
595 "quit" "range" "raw_input" "reduce" "reload" "repr"
596 "round" "set" "setattr" "slice" "sorted"
597 "staticmethod" "str" "sum" "super" "tuple" "type"
598 "unichr" "unicode" "vars" "xrange" "zip")
600 (kw4 (mapconcat 'identity
601 ;; Exceptions and warnings
602 '("ArithmeticError" "AssertionError"
603 "AttributeError" "BaseException" "BufferError"
604 "BytesWarning" "DeprecationWarning" "EOFError"
605 "EnvironmentError" "Exception"
606 "FloatingPointError" "FutureWarning" "GeneratorExit"
607 "IOError" "ImportError" "ImportWarning"
608 "IndentationError" "IndexError"
609 "KeyError" "KeyboardInterrupt" "LookupError"
610 "MemoryError" "NameError" "NotImplemented"
611 "NotImplementedError" "OSError" "OverflowError"
612 "PendingDeprecationWarning" "ReferenceError"
613 "RuntimeError" "RuntimeWarning" "StandardError"
614 "StopIteration" "SyntaxError" "SyntaxWarning"
615 "SystemError" "SystemExit" "TabError" "TypeError"
616 "UnboundLocalError" "UnicodeDecodeError"
617 "UnicodeEncodeError" "UnicodeError"
618 "UnicodeTranslateError" "UnicodeWarning"
619 "UserWarning" "ValueError" "Warning"
625 '("^[ \t]*\\(@[a-zA-Z_][a-zA-Z_0-9]+\\)\\((.+)\\)?" 1 'py-decorators-face)
627 (cons (concat "\\<\\(" kw1 "\\)\\>[ \n\t(]") 1)
628 ;; builtins when they don't appear as object attributes
629 (list (concat "\\([^. \t]\\|^\\)[ \t]*\\<\\(" kw3 "\\)\\>[ \n\t(]") 2
631 ;; block introducing keywords with immediately following colons.
632 ;; Yes "except" is in both lists.
633 (cons (concat "\\<\\(" kw2 "\\)[ \n\t(]") 1)
635 (list (concat "\\<\\(" kw4 "\\)[ \n\t:,()]") 1 'py-exception-name-face)
637 '("\\<raise[ \t]+\\([a-zA-Z_]+[a-zA-Z0-9_.]*\\)" 1 py-exception-name-face)
639 '("\\<except[ \t]+\\([a-zA-Z_]+[a-zA-Z0-9_.]*\\)" 1 py-exception-name-face)
641 '("\\<class[ \t]+\\([a-zA-Z_]+[a-zA-Z0-9_]*\\)" 1 py-class-name-face)
643 '("\\<def[ \t]+\\([a-zA-Z_]+[a-zA-Z0-9_]*\\)"
644 1 font-lock-function-name-face)
646 '("\\<\\(self\\|Ellipsis\\|True\\|False\\|None\\)\\>"
647 1 py-pseudo-keyword-face)
648 ;; XXX, TODO, and FIXME tags
649 '("XXX\\|TODO\\|FIXME" 0 py-XXX-tag-face t)
650 ;; special marking for string escapes and percent substitutes;
651 ;; loops adapted from lisp-mode in font-lock.el
654 ;; (while (re-search-forward
656 ;; "\\(\\\\\\\\\\|\\\\x..\\|\\\\u....\\|\\\\U........\\|"
657 ;; "\\\\[0-9][0-9]*\\|\\\\[abfnrtv\"']\\)") bound t)
658 ;; (let ((face (get-text-property (1- (point)) 'face)))
659 ;; (when (or (and (listp face) (memq 'font-lock-string-face face))
660 ;; (eq 'font-lock-string-face face))
661 ;; (throw 'found t))))))
662 ;; (1 'font-lock-regexp-grouping-backslash prepend))
665 ;; (while (re-search-forward "\\(%[^(]\\|%([^)]*).\\)" bound t)
666 ;; (let ((face (get-text-property (1- (point)) 'face)))
667 ;; (when (or (and (listp face) (memq 'font-lock-string-face face))
668 ;; (eq 'font-lock-string-face face))
669 ;; (throw 'found t))))))
670 ;; (1 'font-lock-regexp-grouping-construct prepend))
672 "Additional expressions to highlight in Python mode.")
674 ;; have to bind py-file-queue before installing the kill-emacs-hook
675 (defvar py-file-queue nil
676 "Queue of Python temp files awaiting execution.
677 Currently-active file is at the head of the list.")
679 (defvar py-pdbtrack-is-tracking-p nil)
681 (defvar py-pychecker-history nil)
687 (defconst py-stringlit-re
689 ;; These fail if backslash-quote ends the string (not worth
690 ;; fixing?). They precede the short versions so that the first two
691 ;; quotes don't look like an empty short string.
693 ;; (maybe raw), long single quoted triple quoted strings (SQTQ),
694 ;; with potential embedded single quotes
695 "[rRuUbB]?'''[^']*\\(\\('[^']\\|''[^']\\)[^']*\\)*'''"
697 ;; (maybe raw), long double quoted triple quoted strings (DQTQ),
698 ;; with potential embedded double quotes
699 "[rRuUbB]?\"\"\"[^\"]*\\(\\(\"[^\"]\\|\"\"[^\"]\\)[^\"]*\\)*\"\"\""
701 "[rRuUbB]?'\\([^'\n\\]\\|\\\\.\\)*'" ; single-quoted
703 "[rRuUbB]?\"\\([^\"\n\\]\\|\\\\.\\)*\"" ; double-quoted
705 "Regular expression matching a Python string literal.")
707 (defconst py-continued-re
708 ;; This is tricky because a trailing backslash does not mean
709 ;; continuation if it's in a comment
711 "\\(" "[^#'\"\n\\]" "\\|" py-stringlit-re "\\)*"
713 "Regular expression matching Python backslash continuation lines.")
715 (defconst py-blank-or-comment-re "[ \t]*\\($\\|#\\)"
716 "Regular expression matching a blank or comment line.")
718 (defconst py-outdent-re
719 (concat "\\(" (mapconcat 'identity
721 "except\\(\\s +.*\\)?:"
726 "Regular expression matching statements to be dedented one level.")
728 (defconst py-block-closing-keywords-re
729 "\\(return\\|raise\\|break\\|continue\\|pass\\)"
730 "Regular expression matching keywords which typically close a block.")
732 (defconst py-no-outdent-re
737 "except\\(\\s +.*\\)?:"
742 (concat py-block-closing-keywords-re "[ \t\n]")
746 "Regular expression matching lines not to dedent after.")
748 (defvar py-traceback-line-re
749 "[ \t]+File \"\\([^\"]+\\)\", line \\([0-9]+\\)"
750 "Regular expression that describes tracebacks.")
752 ;; pdbtrack constants
753 (defconst py-pdbtrack-stack-entry-regexp
754 ; "^> \\([^(]+\\)(\\([0-9]+\\))\\([?a-zA-Z0-9_]+\\)()"
755 "^> \\(.*\\)(\\([0-9]+\\))\\([?a-zA-Z0-9_<>]+\\)()"
756 "Regular expression pdbtrack uses to find a stack trace entry.")
758 (defconst py-pdbtrack-input-prompt "\n[(<]*[Pp]db[>)]+ "
759 "Regular expression pdbtrack uses to recognize a pdb prompt.")
761 (defconst py-pdbtrack-track-range 10000
762 "Max number of characters from end of buffer to search for stack entry.")
766 ;; Major mode boilerplate
768 ;; define a mode-specific abbrev table for those who use such things
769 (defvar python-mode-abbrev-table nil
770 "Abbrev table in use in `python-mode' buffers.")
771 (define-abbrev-table 'python-mode-abbrev-table nil)
773 (defvar python-mode-hook nil
774 "*Hook called by `python-mode'.")
776 (make-obsolete-variable 'jpython-mode-hook 'jython-mode-hook)
777 (defvar jython-mode-hook nil
778 "*Hook called by `jython-mode'. `jython-mode' also calls
779 `python-mode-hook'.")
781 (defvar py-shell-hook nil
782 "*Hook called by `py-shell'.")
784 ;; In previous version of python-mode.el, the hook was incorrectly
785 ;; called py-mode-hook, and was not defvar'd. Deprecate its use.
786 (and (fboundp 'make-obsolete-variable)
787 (make-obsolete-variable 'py-mode-hook 'python-mode-hook))
789 (defvar py-mode-map ()
790 "Keymap used in `python-mode' buffers.")
793 (setq py-mode-map (make-sparse-keymap))
795 (define-key py-mode-map ":" 'py-electric-colon)
796 ;; indentation level modifiers
797 (define-key py-mode-map "\C-c\C-l" 'py-shift-region-left)
798 (define-key py-mode-map "\C-c\C-r" 'py-shift-region-right)
799 (define-key py-mode-map "\C-c<" 'py-shift-region-left)
800 (define-key py-mode-map "\C-c>" 'py-shift-region-right)
801 ;; subprocess commands
802 (define-key py-mode-map "\C-c\C-c" 'py-execute-buffer)
803 (define-key py-mode-map "\C-c\C-m" 'py-execute-import-or-reload)
804 (define-key py-mode-map "\C-c\C-s" 'py-execute-string)
805 (define-key py-mode-map "\C-c|" 'py-execute-region)
806 (define-key py-mode-map "\e\C-x" 'py-execute-def-or-class)
807 (define-key py-mode-map "\C-c!" 'py-shell)
808 (define-key py-mode-map "\C-c\C-t" 'py-toggle-shells)
809 ;; Caution! Enter here at your own risk. We are trying to support
810 ;; several behaviors and it gets disgusting. :-( This logic ripped
811 ;; largely from CC Mode.
813 ;; In XEmacs 19, Emacs 19, and Emacs 20, we use this to bind
814 ;; backwards deletion behavior to DEL, which both Delete and
815 ;; Backspace get translated to. There's no way to separate this
816 ;; behavior in a clean way, so deal with it! Besides, it's been
817 ;; this way since the dawn of time.
818 (if (not (boundp 'delete-key-deletes-forward))
819 (define-key py-mode-map "\177" 'py-electric-backspace)
820 ;; However, XEmacs 20 actually achieved enlightenment. It is
821 ;; possible to sanely define both backward and forward deletion
822 ;; behavior under X separately (TTYs are forever beyond hope, but
823 ;; who cares? XEmacs 20 does the right thing with these too).
824 (define-key py-mode-map [delete] 'py-electric-delete)
825 (define-key py-mode-map [backspace] 'py-electric-backspace))
826 ;; Separate M-BS from C-M-h. The former should remain
827 ;; backward-kill-word.
828 (define-key py-mode-map [(control meta h)] 'py-mark-def-or-class)
829 (define-key py-mode-map "\C-c\C-k" 'py-mark-block)
831 (define-key py-mode-map "\C-c:" 'py-guess-indent-offset)
832 (define-key py-mode-map "\C-c\t" 'py-indent-region)
833 (define-key py-mode-map "\C-c\C-d" 'py-pdbtrack-toggle-stack-tracking)
834 (define-key py-mode-map "\C-c\C-f" 'py-sort-imports)
835 (define-key py-mode-map "\C-c\C-n" 'py-next-statement)
836 (define-key py-mode-map "\C-c\C-p" 'py-previous-statement)
837 (define-key py-mode-map "\C-c\C-u" 'py-goto-block-up)
838 (define-key py-mode-map "\C-c#" 'py-comment-region)
839 (define-key py-mode-map "\C-c?" 'py-describe-mode)
840 (define-key py-mode-map "\C-c\C-e" 'py-help-at-point)
841 (define-key py-mode-map "\e\C-a" 'py-beginning-of-def-or-class)
842 (define-key py-mode-map "\e\C-e" 'py-end-of-def-or-class)
843 (define-key py-mode-map "\C-c-" 'py-up-exception)
844 (define-key py-mode-map "\C-c=" 'py-down-exception)
845 ;; stuff that is `standard' but doesn't interface well with
846 ;; python-mode, which forces us to rebind to special commands
847 (define-key py-mode-map "\C-xnd" 'py-narrow-to-defun)
849 (define-key py-mode-map "\C-c\C-b" 'py-submit-bug-report)
850 (define-key py-mode-map "\C-c\C-v" 'py-version)
851 (define-key py-mode-map "\C-c\C-w" 'py-pychecker-run)
852 ;; shadow global bindings for newline-and-indent w/ the py- version.
853 ;; BAW - this is extremely bad form, but I'm not going to change it
855 (mapc #'(lambda (key)
856 (define-key py-mode-map key 'py-newline-and-indent))
857 (where-is-internal 'newline-and-indent))
858 ;; Force RET to be py-newline-and-indent even if it didn't get
859 ;; mapped by the above code. motivation: Emacs' default binding for
860 ;; RET is `newline' and C-j is `newline-and-indent'. Most Pythoneers
861 ;; expect RET to do a `py-newline-and-indent' and any Emacsers who
862 ;; dislike this are probably knowledgeable enough to do a rebind.
863 ;; However, we do *not* change C-j since many Emacsers have already
864 ;; swapped RET and C-j and they don't want C-j bound to `newline' to
866 (define-key py-mode-map "\C-m" 'py-newline-and-indent)
869 (defvar py-mode-output-map nil
870 "Keymap used in *Python Output* buffers.")
871 (if py-mode-output-map
873 (setq py-mode-output-map (make-sparse-keymap))
874 (define-key py-mode-output-map [button2] 'py-mouseto-exception)
875 (define-key py-mode-output-map "\C-c\C-c" 'py-goto-exception)
876 ;; TBD: Disable all self-inserting keys. This is bogus, we should
877 ;; really implement this as *Python Output* buffer being read-only
878 (mapc #' (lambda (key)
879 (define-key py-mode-output-map key
880 #'(lambda () (interactive) (beep))))
881 (where-is-internal 'self-insert-command))
884 (defvar py-shell-map nil
885 "Keymap used in *Python* shell buffers.")
888 (setq py-shell-map (copy-keymap comint-mode-map))
889 (define-key py-shell-map [tab] 'tab-to-tab-stop)
890 (define-key py-shell-map "\C-c-" 'py-up-exception)
891 (define-key py-shell-map "\C-c=" 'py-down-exception)
894 ;; (when (featurep 'xemacs) (defvar py-mode-syntax-table nil))
895 ;; (when (featurep 'xemacs)
896 ;; (when (not py-mode-syntax-table)
897 ;; (setq py-mode-syntax-table (make-syntax-table))
898 ;; (modify-syntax-entry ?\( "()" py-mode-syntax-table)
899 ;; (modify-syntax-entry ?\) ")(" py-mode-syntax-table)
900 ;; (modify-syntax-entry ?\[ "(]" py-mode-syntax-table)
901 ;; (modify-syntax-entry ?\] ")[" py-mode-syntax-table)
902 ;; (modify-syntax-entry ?\{ "(}" py-mode-syntax-table)
903 ;; (modify-syntax-entry ?\} "){" py-mode-syntax-table)
904 ;; ;; Add operator symbols misassigned in the std table
905 ;; (modify-syntax-entry ?\$ "." py-mode-syntax-table)
906 ;; (modify-syntax-entry ?\% "." py-mode-syntax-table)
907 ;; (modify-syntax-entry ?\& "." py-mode-syntax-table)
908 ;; (modify-syntax-entry ?\* "." py-mode-syntax-table)
909 ;; (modify-syntax-entry ?\+ "." py-mode-syntax-table)
910 ;; (modify-syntax-entry ?\- "." py-mode-syntax-table)
911 ;; (modify-syntax-entry ?\/ "." py-mode-syntax-table)
912 ;; (modify-syntax-entry ?\< "." py-mode-syntax-table)
913 ;; (modify-syntax-entry ?\= "." py-mode-syntax-table)
914 ;; (modify-syntax-entry ?\> "." py-mode-syntax-table)
915 ;; (modify-syntax-entry ?\| "." py-mode-syntax-table)
916 ;; ;; For historical reasons, underscore is word class instead of
917 ;; ;; symbol class. GNU conventions say it should be symbol class, but
918 ;; ;; there's a natural conflict between what major mode authors want
919 ;; ;; and what users expect from `forward-word' and `backward-word'.
920 ;; ;; Guido and I have hashed this out and have decided to keep
921 ;; ;; underscore in word class. If you're tempted to change it, try
922 ;; ;; binding M-f and M-b to py-forward-into-nomenclature and
923 ;; ;; py-backward-into-nomenclature instead. This doesn't help in all
924 ;; ;; situations where you'd want the different behavior
925 ;; ;; (e.g. backward-kill-word).
926 ;; (modify-syntax-entry ?\_ "w" py-mode-syntax-table)
927 ;; ;; Both single quote and double quote are string delimiters
928 ;; (modify-syntax-entry ?\' "\"" py-mode-syntax-table)
929 ;; (modify-syntax-entry ?\" "|" py-mode-syntax-table)
930 ;; ;; backquote is open and close paren
931 ;; (modify-syntax-entry ?\` "$" py-mode-syntax-table)
932 ;; ;; comment delimiters
933 ;; (modify-syntax-entry ?\# "<" py-mode-syntax-table)
934 ;; (modify-syntax-entry ?\n ">" py-mode-syntax-table)))
936 ;; An auxiliary syntax table which places underscore and dot in the
937 ;; symbol class for simplicity
938 (defvar py-dotted-expression-syntax-table nil
939 "Syntax table used to identify Python dotted expressions.")
940 (when (not py-dotted-expression-syntax-table)
941 (setq py-dotted-expression-syntax-table
942 (copy-syntax-table py-mode-syntax-table))
943 (modify-syntax-entry ?_ "_" py-dotted-expression-syntax-table)
944 (modify-syntax-entry ?. "_" py-dotted-expression-syntax-table))
949 (defmacro py-safe (&rest body)
950 "Safely execute BODY, return nil if an error occurred."
955 (defsubst py-keep-region-active ()
956 "Keep the region active in XEmacs."
957 ;; Ignore byte-compiler warnings you might see. Also note that
958 ;; FSF's Emacs 19 does it differently; its policy doesn't require us
959 ;; to take explicit action.
960 (and (boundp 'zmacs-region-stays)
961 (setq zmacs-region-stays t)))
963 (defsubst py-point (position)
964 "Returns the value of point at certain commonly referenced POSITIONs.
965 POSITION can be one of the following symbols:
967 bol -- beginning of line
969 bod -- beginning of def or class
970 eod -- end of def or class
971 bob -- beginning of buffer
973 boi -- back to indentation
974 bos -- beginning of statement
976 This function does not modify point or mark."
977 (let ((here (point)))
979 ((eq position 'bol) (beginning-of-line))
980 ((eq position 'eol) (end-of-line))
981 ((eq position 'bod) (py-beginning-of-def-or-class 'either))
982 ((eq position 'eod) (py-end-of-def-or-class 'either))
983 ;; Kind of funny, I know, but useful for py-up-exception.
984 ((eq position 'bob) (goto-char (point-min)))
985 ((eq position 'eob) (goto-char (point-max)))
986 ((eq position 'boi) (back-to-indentation))
987 ((eq position 'bos) (py-goto-initial-line))
988 (t (error "Unknown buffer position requested: %s" position))
994 (defsubst py-highlight-line (from to file line)
996 ((fboundp 'make-extent)
998 (let ((e (make-extent from to)))
999 (set-extent-property e 'mouse-face 'highlight)
1000 (set-extent-property e 'py-exc-info (cons file line))
1001 (set-extent-property e 'keymap py-mode-output-map)))
1003 ;; Emacs -- Please port this!
1007 (defun py-in-literal (&optional lim)
1008 "Return non-nil if point is in a Python literal (a comment or string).
1009 Optional argument LIM indicates the beginning of the containing form,
1010 i.e. the limit on how far back to scan."
1011 ;; This is the version used for non-XEmacs, which has a nicer
1014 ;; WARNING: Watch out for infinite recursion.
1015 (let* ((lim (or lim (py-point 'bod)))
1016 (state (parse-partial-sexp lim (point))))
1018 ((nth 3 state) 'string)
1019 ((nth 4 state) 'comment)
1022 ;; XEmacs has a built-in function that should make this much quicker.
1023 ;; In this case, lim is ignored
1024 (defun py-fast-in-literal (&optional lim)
1025 "Fast version of `py-in-literal', used only by XEmacs.
1026 Optional LIM is ignored."
1027 ;; don't have to worry about context == 'block-comment
1028 (buffer-syntactic-context))
1030 (if (fboundp 'buffer-syntactic-context)
1031 (defalias 'py-in-literal 'py-fast-in-literal))
1035 ;; Menu definitions, only relevent if you have the easymenu.el package
1036 ;; (standard in the latest Emacs 19 and XEmacs 19 distributions).
1038 "Menu for Python Mode.
1039 This menu will get created automatically if you have the `easymenu'
1040 package. Note that the latest X/Emacs releases contain this package.")
1042 (and (py-safe (require 'easymenu) t)
1044 py-menu py-mode-map "Python Mode menu"
1046 ["Comment Out Region" py-comment-region (mark)]
1047 ["Uncomment Region" (py-comment-region (point) (mark) '(4)) (mark)]
1049 ["Mark current block" py-mark-block t]
1050 ["Mark current def" py-mark-def-or-class t]
1051 ["Mark current class" (py-mark-def-or-class t) t]
1053 ["Shift region left" py-shift-region-left (mark)]
1054 ["Shift region right" py-shift-region-right (mark)]
1056 ["Import/reload file" py-execute-import-or-reload t]
1057 ["Execute buffer" py-execute-buffer t]
1058 ["Execute region" py-execute-region (mark)]
1059 ["Execute def or class" py-execute-def-or-class (mark)]
1060 ["Execute string" py-execute-string t]
1061 ["Start interpreter..." py-shell t]
1063 ["Go to start of block" py-goto-block-up t]
1064 ["Go to start of class" (py-beginning-of-def-or-class t) t]
1065 ["Move to end of class" (py-end-of-def-or-class t) t]
1066 ["Move to start of def" py-beginning-of-def-or-class t]
1067 ["Move to end of def" py-end-of-def-or-class t]
1069 ["Describe mode" py-describe-mode t]
1074 ;; Imenu definitions
1075 (defvar py-imenu-class-regexp
1076 (concat ; <<classes>>
1078 "^[ \t]*" ; newline and maybe whitespace
1079 "\\(class[ \t]+[a-zA-Z0-9_]+\\)" ; class name
1080 ; possibly multiple superclasses
1081 "\\([ \t]*\\((\\([a-zA-Z0-9_,. \t\n]\\)*)\\)?\\)"
1082 "[ \t]*:" ; and the final :
1085 "Regexp for Python classes for use with the Imenu package."
1088 (defvar py-imenu-method-regexp
1089 (concat ; <<methods and functions>>
1091 "^[ \t]*" ; new line and maybe whitespace
1092 "\\(def[ \t]+" ; function definitions start with def
1093 "\\([a-zA-Z0-9_]+\\)" ; name is here
1094 ; function arguments...
1095 ;; "[ \t]*(\\([-+/a-zA-Z0-9_=,\* \t\n.()\"'#]*\\))"
1096 "[ \t]*(\\([^:#]*\\))"
1098 "[ \t]*:" ; and then the :
1099 "\\)" ; >>methods and functions<<
1101 "Regexp for Python methods/functions for use with the Imenu package."
1104 (defvar py-imenu-method-no-arg-parens '(2 8)
1105 "Indices into groups of the Python regexp for use with Imenu.
1107 Using these values will result in smaller Imenu lists, as arguments to
1108 functions are not listed.
1110 See the variable `py-imenu-show-method-args-p' for more
1113 (defvar py-imenu-method-arg-parens '(2 7)
1114 "Indices into groups of the Python regexp for use with imenu.
1115 Using these values will result in large Imenu lists, as arguments to
1116 functions are listed.
1118 See the variable `py-imenu-show-method-args-p' for more
1121 ;; Note that in this format, this variable can still be used with the
1122 ;; imenu--generic-function. Otherwise, there is no real reason to have
1124 (defvar py-imenu-generic-expression
1127 py-imenu-class-regexp
1129 py-imenu-method-regexp
1131 py-imenu-method-no-arg-parens)
1132 "Generic Python expression which may be used directly with Imenu.
1133 Used by setting the variable `imenu-generic-expression' to this value.
1134 Also, see the function \\[py-imenu-create-index] for a better
1135 alternative for finding the index.")
1137 ;; These next two variables are used when searching for the Python
1138 ;; class/definitions. Just saving some time in accessing the
1139 ;; generic-python-expression, really.
1140 (defvar py-imenu-generic-regexp nil)
1141 (defvar py-imenu-generic-parens nil)
1144 (defun py-imenu-create-index-function ()
1145 "Python interface function for the Imenu package.
1146 Finds all Python classes and functions/methods. Calls function
1147 \\[py-imenu-create-index-engine]. See that function for the details
1149 (setq py-imenu-generic-regexp (car py-imenu-generic-expression)
1150 py-imenu-generic-parens (if py-imenu-show-method-args-p
1151 py-imenu-method-arg-parens
1152 py-imenu-method-no-arg-parens))
1153 (goto-char (point-min))
1154 ;; Warning: When the buffer has no classes or functions, this will
1155 ;; return nil, which seems proper according to the Imenu API, but
1156 ;; causes an error in the XEmacs port of Imenu. Sigh.
1157 (py-imenu-create-index-engine nil))
1159 (defun py-imenu-create-index-engine (&optional start-indent)
1160 "Function for finding Imenu definitions in Python.
1162 Finds all definitions (classes, methods, or functions) in a Python
1163 file for the Imenu package.
1165 Returns a possibly nested alist of the form
1167 (INDEX-NAME . INDEX-POSITION)
1169 The second element of the alist may be an alist, producing a nested
1172 (INDEX-NAME . INDEX-ALIST)
1174 This function should not be called directly, as it calls itself
1175 recursively and requires some setup. Rather this is the engine for
1176 the function \\[py-imenu-create-index-function].
1178 It works recursively by looking for all definitions at the current
1179 indention level. When it finds one, it adds it to the alist. If it
1180 finds a definition at a greater indentation level, it removes the
1181 previous definition from the alist. In its place it adds all
1182 definitions found at the next indentation level. When it finds a
1183 definition that is less indented then the current level, it returns
1184 the alist it has created thus far.
1186 The optional argument START-INDENT indicates the starting indentation
1187 at which to continue looking for Python classes, methods, or
1188 functions. If this is not supplied, the function uses the indentation
1189 of the first definition found."
1195 (class-paren (first py-imenu-generic-parens))
1196 (def-paren (second py-imenu-generic-parens)))
1198 (re-search-forward py-imenu-generic-regexp (point-max) t))
1201 ;; used to set def-name to this value but generic-extract-name
1202 ;; is new to imenu-1.14. this way it still works with
1204 ;;(imenu--generic-extract-name py-imenu-generic-parens))
1205 (let ((cur-paren (if (match-beginning class-paren)
1206 class-paren def-paren)))
1208 (buffer-substring-no-properties (match-beginning cur-paren)
1209 (match-end cur-paren))))
1211 (py-beginning-of-def-or-class 'either))
1213 (setq cur-indent (current-indentation)))
1214 ;; HACK: want to go to the next correct definition location. We
1215 ;; explicitly list them here but it would be better to have them
1218 (or (match-beginning class-paren)
1219 (match-beginning def-paren)))
1220 ;; if we don't have a starting indent level, take this one
1222 (setq start-indent cur-indent))
1223 ;; if we don't have class name yet, take this one
1225 (setq prev-name def-name))
1226 ;; what level is the next definition on? must be same, deeper
1227 ;; or shallower indentation
1229 ;; Skip code in comments and strings
1231 ;; at the same indent level, add it to the list...
1232 ((= start-indent cur-indent)
1233 (push (cons def-name def-pos) index-alist))
1234 ;; deeper indented expression, recurse
1235 ((< start-indent cur-indent)
1236 ;; the point is currently on the expression we're supposed to
1237 ;; start on, so go back to the last expression. The recursive
1238 ;; call will find this place again and add it to the correct
1240 (re-search-backward py-imenu-generic-regexp (point-min) 'move)
1241 (setq sub-method-alist (py-imenu-create-index-engine cur-indent))
1242 (if sub-method-alist
1243 ;; we put the last element on the index-alist on the start
1244 ;; of the submethod alist so the user can still get to it.
1245 (let ((save-elmt (pop index-alist)))
1246 (push (cons prev-name
1247 (cons save-elmt sub-method-alist))
1249 ;; found less indented expression, we're done.
1251 (setq looking-p nil)
1252 (re-search-backward py-imenu-generic-regexp (point-min) t)))
1254 (setq prev-name def-name)
1257 (re-search-forward py-imenu-generic-regexp
1258 (point-max) 'move))))
1259 (nreverse index-alist)))
1263 (defun py-choose-shell-by-shebang ()
1264 "Choose CPython or Jython mode by looking at #! on the first line.
1265 Returns the appropriate mode function.
1266 Used by `py-choose-shell', and similar to but distinct from
1267 `set-auto-mode', though it uses `auto-mode-interpreter-regexp' (if available)."
1268 ;; look for an interpreter specified in the first line
1269 ;; similar to set-auto-mode (files.el)
1270 (let* ((re (if (boundp 'auto-mode-interpreter-regexp)
1271 auto-mode-interpreter-regexp
1272 ;; stolen from Emacs 21.2
1273 "#![ \t]?\\([^ \t\n]*/bin/env[ \t]\\)?\\([^ \t\n]+\\)"))
1274 (interpreter (save-excursion
1275 (goto-char (point-min))
1280 ;; Map interpreter name to a mode.
1281 (setq elt (assoc (file-name-nondirectory interpreter)
1283 (and elt (caddr elt))))
1287 (defun py-choose-shell-by-import ()
1288 "Choose CPython or Jython mode based imports.
1289 If a file imports any packages in `py-jython-packages', within
1290 `py-import-check-point-max' characters from the start of the file,
1291 return `jython', otherwise return nil."
1294 (goto-char (point-min))
1295 (while (and (not mode)
1296 (search-forward-regexp
1297 "^\\(\\(from\\)\\|\\(import\\)\\) \\([^ \t\n.]+\\)"
1298 py-import-check-point-max t))
1299 (setq mode (and (member (match-string 4) py-jython-packages)
1305 (defun py-choose-shell ()
1306 "Choose CPython or Jython mode. Returns the appropriate mode function.
1307 This does the following:
1308 - look for an interpreter with `py-choose-shell-by-shebang'
1309 - examine imports using `py-choose-shell-by-import'
1310 - default to the variable `py-default-interpreter'"
1312 (or (py-choose-shell-by-shebang)
1313 (py-choose-shell-by-import)
1314 py-default-interpreter
1315 ; 'cpython ;; don't use to py-default-interpreter, because default
1316 ; ;; is only way to choose CPython
1321 (defun python-mode ()
1322 "Major mode for editing Python files.
1323 To submit a problem report, enter `\\[py-submit-bug-report]' from a
1324 `python-mode' buffer. Do `\\[py-describe-mode]' for detailed
1325 documentation. To see what version of `python-mode' you are running,
1326 enter `\\[py-version]'.
1328 This mode knows about Python indentation, tokens, comments and
1329 continuation lines. Paragraphs are separated by blank lines only.
1335 py-indent-offset\t\tindentation increment
1336 py-block-comment-prefix\t\tcomment string used by `comment-region'
1337 py-python-command\t\tshell command to invoke Python interpreter
1338 py-temp-directory\t\tdirectory used for temp files (if needed)
1339 py-beep-if-tab-change\t\tring the bell if `tab-width' is changed"
1341 ;; set up local variables
1342 (kill-all-local-variables)
1343 (make-local-variable 'paragraph-separate)
1344 (make-local-variable 'paragraph-start)
1345 (make-local-variable 'require-final-newline)
1346 (make-local-variable 'comment-start)
1347 (make-local-variable 'comment-end)
1348 (make-local-variable 'comment-start-skip)
1349 (make-local-variable 'comment-column)
1350 (make-local-variable 'comment-indent-function)
1351 (make-local-variable 'indent-region-function)
1352 (make-local-variable 'indent-line-function)
1353 (make-local-variable 'add-log-current-defun-function)
1354 (make-local-variable 'fill-paragraph-function)
1356 (set-syntax-table py-mode-syntax-table)
1357 ;; 2009-09-10 a.roehler@web.de changed section start
1358 ;; from python.el, version "22.1"
1359 (set (make-local-variable 'font-lock-defaults)
1360 '(python-font-lock-keywords nil nil nil nil
1361 (font-lock-syntactic-keywords
1362 . python-font-lock-syntactic-keywords)))
1363 ;; 2009-09-10 a.roehler@web.de changed section end
1364 (setq major-mode 'python-mode
1366 local-abbrev-table python-mode-abbrev-table
1367 paragraph-separate "^[ \t]*$"
1368 paragraph-start "^[ \t]*$"
1369 require-final-newline t
1372 comment-start-skip "# *"
1374 comment-indent-function 'py-comment-indent-function
1375 indent-region-function 'py-indent-region
1376 indent-line-function 'py-indent-line
1377 ;; tell add-log.el how to find the current function/method/variable
1378 add-log-current-defun-function 'py-current-defun
1380 fill-paragraph-function 'py-fill-paragraph
1382 (use-local-map py-mode-map)
1385 (easy-menu-add py-menu))
1386 ;; Emacs 19 requires this
1387 (if (boundp 'comment-multi-line)
1388 (setq comment-multi-line nil))
1389 ;; Install Imenu if available
1390 (when (py-safe (require 'imenu))
1391 (setq imenu-create-index-function #'py-imenu-create-index-function)
1392 (setq imenu-generic-expression py-imenu-generic-expression)
1393 (if (fboundp 'imenu-add-to-menubar)
1394 (imenu-add-to-menubar (format "%s-%s" "IM" mode-name)))
1397 ;; Add support for HideShow
1398 (add-to-list 'hs-special-modes-alist
1402 (concat (if py-hide-show-hide-docstrings
1403 "^\\s-*\"\"\"\\|" "")
1404 (mapconcat 'identity
1405 (mapcar #'(lambda (x) (concat "^\\s-*" x "\\>"))
1406 py-hide-show-keywords)
1410 ;; comment-start regex
1412 ;; forward-sexp function
1414 (py-goto-beyond-block)
1415 (skip-chars-backward " \t\n"))
1418 ;; Run the mode hook. Note that py-mode-hook is deprecated.
1419 (if python-mode-hook
1420 (run-hooks 'python-mode-hook)
1421 (run-hooks 'py-mode-hook))
1422 ;; Now do the automagical guessing
1423 (if py-smart-indentation
1424 (let ((offset py-indent-offset))
1425 ;; It's okay if this fails to guess a good value
1426 (if (and (py-safe (py-guess-indent-offset))
1427 (<= py-indent-offset 8)
1428 (>= py-indent-offset 2))
1429 (setq offset py-indent-offset))
1430 (setq py-indent-offset offset)
1431 ;; Only turn indent-tabs-mode off if tab-width !=
1432 ;; py-indent-offset. Never turn it on, because the user must
1433 ;; have explicitly turned it off.
1434 (if (/= tab-width py-indent-offset)
1435 (setq indent-tabs-mode nil))))
1436 ;; Set the default shell if not already set
1437 (when (null py-which-shell)
1438 (py-toggle-shells (py-choose-shell))))
1440 (make-obsolete 'jpython-mode 'jython-mode)
1441 (defun jython-mode ()
1442 "Major mode for editing Jython/Jython files.
1443 This is a simple wrapper around `python-mode'.
1444 It runs `jython-mode-hook' then calls `python-mode.'
1445 It is added to `interpreter-mode-alist' and `py-choose-shell'.
1449 (py-toggle-shells 'jython)
1450 (when jython-mode-hook
1451 (run-hooks 'jython-mode-hook)))
1454 ;; It's handy to add recognition of Python files to the
1455 ;; interpreter-mode-alist and to auto-mode-alist. With the former, we
1456 ;; can specify different `derived-modes' based on the #! line, but
1457 ;; with the latter, we can't. So we just won't add them if they're
1460 (let ((modes '(("jython" . jython-mode)
1461 ("python" . python-mode))))
1463 (when (not (assoc (car modes) interpreter-mode-alist))
1464 (push (car modes) interpreter-mode-alist))
1465 (setq modes (cdr modes))))
1467 (when (not (or (rassq 'python-mode auto-mode-alist)
1468 (rassq 'jython-mode auto-mode-alist)))
1469 (push '("\\.py$" . python-mode) auto-mode-alist))
1473 ;; electric characters
1474 (defun py-outdent-p ()
1475 "Returns non-nil if the current line should dedent one level."
1477 (and (progn (back-to-indentation)
1478 (looking-at py-outdent-re))
1479 ;; short circuit infloop on illegal construct
1481 (progn (forward-line -1)
1482 (py-goto-initial-line)
1483 (back-to-indentation)
1484 (while (or (looking-at py-blank-or-comment-re)
1486 (backward-to-indentation 1))
1487 (not (looking-at py-no-outdent-re)))
1490 (defun py-electric-colon (arg)
1492 In certain cases the line is dedented appropriately. If a numeric
1493 argument ARG is provided, that many colons are inserted
1494 non-electrically. Electric behavior is inhibited inside a string or
1497 (self-insert-command (prefix-numeric-value arg))
1498 ;; are we in a string or comment?
1500 (let ((pps (parse-partial-sexp (save-excursion
1501 (py-beginning-of-def-or-class)
1504 (not (or (nth 3 pps) (nth 4 pps)))))
1506 (let ((here (point))
1508 (indent (py-compute-indentation t)))
1511 (= indent (save-excursion
1512 (py-next-statement -1)
1513 (py-compute-indentation t)))
1515 (setq outdent py-indent-offset))
1516 ;; Don't indent, only dedent. This assumes that any lines
1517 ;; that are already dedented relative to
1518 ;; py-compute-indentation were put there on purpose. It's
1519 ;; highly annoying to have `:' indent for you. Use TAB, C-c
1520 ;; C-l or C-c C-r to adjust. TBD: Is there a better way to
1521 ;; determine this???
1522 (if (< (current-indentation) indent) nil
1525 (delete-horizontal-space)
1526 (indent-to (- indent outdent))
1530 ;; Python subprocess utilities and filters
1531 (defun py-execute-file (proc filename)
1532 "Send to Python interpreter process PROC \"execfile('FILENAME')\".
1533 Make that process's buffer visible and force display. Also make
1534 comint believe the user typed this string so that
1535 `kill-output-from-shell' does The Right Thing."
1536 (let ((curbuf (current-buffer))
1537 (procbuf (process-buffer proc))
1538 ; (comint-scroll-to-bottom-on-output t)
1539 (msg (format "## working on region in file %s...\n" filename))
1540 ;; add some comment, so that we can filter it out of history
1541 (cmd (format "execfile(r'%s') # PYTHON-MODE\n" filename)))
1544 (set-buffer procbuf)
1545 (goto-char (point-max))
1546 (move-marker (process-mark proc) (point))
1547 (funcall (process-filter proc) proc msg))
1548 (set-buffer curbuf))
1549 (process-send-string proc cmd)))
1551 (defun py-comint-output-filter-function (string)
1552 "Watch output for Python prompt and exec next file waiting in queue.
1553 This function is appropriate for `comint-output-filter-functions'."
1554 ;;remove ansi terminal escape sequences from string, not sure why they are
1556 (setq string (ansi-color-filter-apply string))
1557 (when (and (string-match py-shell-input-prompt-1-regexp string)
1559 (if py-shell-switch-buffers-on-execute
1560 (pop-to-buffer (current-buffer)))
1561 (py-safe (delete-file (car py-file-queue)))
1562 (setq py-file-queue (cdr py-file-queue))
1564 (let ((pyproc (get-buffer-process (current-buffer))))
1565 (py-execute-file pyproc (car py-file-queue))))
1568 (defun py-pdbtrack-overlay-arrow (activation)
1569 "Activate or de arrow at beginning-of-line in current buffer."
1570 ;; This was derived/simplified from edebug-overlay-arrow
1572 (setq overlay-arrow-position (make-marker))
1573 (setq overlay-arrow-string "=>")
1574 (set-marker overlay-arrow-position (py-point 'bol) (current-buffer))
1575 (setq py-pdbtrack-is-tracking-p t))
1576 (overlay-arrow-position
1577 (setq overlay-arrow-position nil)
1578 (setq py-pdbtrack-is-tracking-p nil))
1581 (defun py-pdbtrack-track-stack-file (text)
1582 "Show the file indicated by the pdb stack entry line, in a separate window.
1584 Activity is disabled if the buffer-local variable
1585 `py-pdbtrack-do-tracking-p' is nil.
1587 We depend on the pdb input prompt matching `py-pdbtrack-input-prompt'
1588 at the beginning of the line.
1590 If the traceback target file path is invalid, we look for the most
1591 recently visited python-mode buffer which either has the name of the
1592 current function \(or class) or which defines the function \(or
1593 class). This is to provide for remote scripts, eg, Zope's 'Script
1594 \(Python)' - put a _copy_ of the script in a buffer named for the
1595 script, and set to python-mode, and pdbtrack will find it.)"
1596 ;; Instead of trying to piece things together from partial text
1597 ;; (which can be almost useless depending on Emacs version), we
1598 ;; monitor to the point where we have the next pdb prompt, and then
1599 ;; check all text from comint-last-input-end to process-mark.
1601 ;; Also, we're very conservative about clearing the overlay arrow,
1602 ;; to minimize residue. This means, for instance, that executing
1603 ;; other pdb commands wipe out the highlight. You can always do a
1604 ;; 'where' (aka 'w') command to reveal the overlay arrow.
1605 (let* ((origbuf (current-buffer))
1606 (currproc (get-buffer-process origbuf)))
1608 (if (not (and currproc py-pdbtrack-do-tracking-p))
1609 (py-pdbtrack-overlay-arrow nil)
1611 (let* ((procmark (process-mark currproc))
1612 (block (buffer-substring (max comint-last-input-end
1614 py-pdbtrack-track-range))
1616 target target_fname target_lineno target_buffer)
1618 (if (not (string-match (concat py-pdbtrack-input-prompt "$") block))
1619 (py-pdbtrack-overlay-arrow nil)
1621 (setq target (py-pdbtrack-get-source-buffer block))
1623 (if (stringp target)
1624 (message "pdbtrack: %s" target)
1626 (setq target_lineno (car target))
1627 (setq target_buffer (cadr target))
1628 (setq target_fname (buffer-file-name target_buffer))
1629 (switch-to-buffer-other-window target_buffer)
1630 (goto-line target_lineno)
1631 (message "pdbtrack: line %s, file %s" target_lineno target_fname)
1632 (py-pdbtrack-overlay-arrow t)
1633 (pop-to-buffer origbuf t)
1638 (defun py-pdbtrack-get-source-buffer (block)
1639 "Return line number and buffer of code indicated by block's traceback text.
1641 We look first to visit the file indicated in the trace.
1643 Failing that, we look for the most recently visited python-mode buffer
1644 with the same name or having the named function.
1646 If we're unable find the source code we return a string describing the
1647 problem as best as we can determine."
1649 (if (not (string-match py-pdbtrack-stack-entry-regexp block))
1651 "Traceback cue not found"
1653 (let* ((filename (match-string 1 block))
1654 (lineno (string-to-number (match-string 2 block)))
1655 (funcname (match-string 3 block))
1658 (cond ((file-exists-p filename)
1659 (list lineno (find-file-noselect filename)))
1661 ((setq funcbuffer (py-pdbtrack-grub-for-buffer funcname lineno))
1662 (if (string-match "/Script (Python)$" filename)
1663 ;; Add in number of lines for leading '##' comments:
1667 (set-buffer funcbuffer)
1671 (string-match "^\\([^#]\\|#[^#]\\|#$\\)"
1672 (buffer-substring (point-min)
1675 (list lineno funcbuffer))
1677 ((= (elt filename 0) ?\<)
1678 (format "(Non-file source: '%s')" filename))
1680 (t (format "Not found: %s(), %s" funcname filename)))
1685 (defun py-pdbtrack-grub-for-buffer (funcname lineno)
1686 "Find most recent buffer itself named or having function funcname.
1688 We walk the buffer-list history for python-mode buffers that are
1689 named for funcname or define a function funcname."
1690 (let ((buffers (buffer-list))
1693 (while (and buffers (not got))
1694 (setq buf (car buffers)
1695 buffers (cdr buffers))
1696 (if (and (save-excursion (set-buffer buf)
1697 (string= major-mode "python-mode"))
1698 (or (string-match funcname (buffer-name buf))
1699 (string-match (concat "^\\s-*\\(def\\|class\\)\\s-+"
1703 (buffer-substring (point-min)
1708 (defun py-postprocess-output-buffer (buf)
1709 "Highlight exceptions found in BUF.
1710 If an exception occurred return t, otherwise return nil. BUF must exist."
1711 (let (line file bol err-p)
1714 (goto-char (point-min))
1715 (while (re-search-forward py-traceback-line-re nil t)
1716 (setq file (match-string 1)
1717 line (string-to-number (match-string 2))
1718 bol (py-point 'bol))
1719 (py-highlight-line bol (py-point 'eol) file line)))
1720 (when (and py-jump-on-exception line)
1722 (py-jump-to-exception file line)
1728 ;;; Subprocess commands
1730 ;; only used when (memq 'broken-temp-names py-emacs-features)
1731 (defvar py-serial-number 0)
1732 (defvar py-exception-buffer nil)
1733 (defvar py-output-buffer "*Python Output*")
1734 (make-variable-buffer-local 'py-output-buffer)
1736 ;; for toggling between CPython and Jython
1737 (defvar py-which-shell nil)
1738 (defvar py-which-args py-python-command-args)
1739 (defvar py-which-bufname "Python")
1740 (make-variable-buffer-local 'py-which-shell)
1741 (make-variable-buffer-local 'py-which-args)
1742 (make-variable-buffer-local 'py-which-bufname)
1744 (defun py-toggle-shells (arg)
1745 "Toggles between the CPython and Jython shells.
1747 With positive argument ARG (interactively \\[universal-argument]),
1748 uses the CPython shell, with negative ARG uses the Jython shell, and
1749 with a zero argument, toggles the shell.
1751 Programmatically, ARG can also be one of the symbols `cpython' or
1752 `jython', equivalent to positive arg and negative arg respectively."
1754 ;; default is to toggle
1761 (if (string-equal py-which-bufname "Python")
1764 ((equal arg 'cpython) (setq arg 1))
1765 ((equal arg 'jython) (setq arg -1)))
1770 (setq py-which-shell py-python-command
1771 py-which-args py-python-command-args
1772 py-which-bufname "Python"
1774 (if (string-equal py-which-bufname "Jython")
1775 (setq mode-name "Python")))
1777 (setq py-which-shell py-jython-command
1778 py-which-args py-jython-command-args
1779 py-which-bufname "Jython"
1781 (if (string-equal py-which-bufname "Python")
1782 (setq mode-name "Jython")))
1784 (message "Using the %s shell" msg)
1785 (setq py-output-buffer (format "*%s Output*" py-which-bufname))))
1788 (defun py-shell (&optional argprompt)
1789 "Start an interactive Python interpreter in another window.
1790 This is like Shell mode, except that Python is running in the window
1791 instead of a shell. See the `Interactive Shell' and `Shell Mode'
1792 sections of the Emacs manual for details, especially for the key
1793 bindings active in the `*Python*' buffer.
1795 With optional \\[universal-argument], the user is prompted for the
1796 flags to pass to the Python interpreter. This has no effect when this
1797 command is used to switch to an existing process, only when a new
1798 process is started. If you use this, you will probably want to ensure
1799 that the current arguments are retained (they will be included in the
1800 prompt). This argument is ignored when this function is called
1801 programmatically, or when running in Emacs 19.34 or older.
1803 Note: You can toggle between using the CPython interpreter and the
1804 Jython interpreter by hitting \\[py-toggle-shells]. This toggles
1805 buffer local variables which control whether all your subshell
1806 interactions happen to the `*Jython*' or `*Python*' buffers (the
1807 latter is the name used for the CPython buffer).
1809 Warning: Don't use an interactive Python if you change sys.ps1 or
1810 sys.ps2 from their default values, or if you're running code that
1811 prints `>>> ' or `... ' at the start of a line. `python-mode' can't
1812 distinguish your output from Python's output, and assumes that `>>> '
1813 at the start of a line is a prompt from Python. Similarly, the Emacs
1814 Shell mode code assumes that both `>>> ' and `... ' at the start of a
1815 line are Python prompts. Bad things can happen if you fool either
1818 Warning: If you do any editing *in* the process buffer *while* the
1819 buffer is accepting output from Python, do NOT attempt to `undo' the
1820 changes. Some of the output (nowhere near the parts you changed!) may
1821 be lost if you do. This appears to be an Emacs bug, an unfortunate
1822 interaction between undo and process filters; the same problem exists in
1823 non-Python process buffers using the default (Emacs-supplied) process
1826 ;; Set the default shell if not already set
1827 (when (null py-which-shell)
1828 (py-toggle-shells py-default-interpreter))
1829 (let ((args py-which-args))
1830 (when (and argprompt
1832 (fboundp 'split-string))
1833 ;; TBD: Perhaps force "-i" in the final list?
1834 (setq args (split-string
1835 (read-string (concat py-which-bufname
1838 (mapconcat 'identity py-which-args " ") " ")
1840 (if (not (equal (buffer-name) "*Python*"))
1841 (switch-to-buffer-other-window
1842 (apply 'make-comint py-which-bufname py-which-shell nil args))
1843 (apply 'make-comint py-which-bufname py-which-shell nil args))
1844 (make-local-variable 'comint-prompt-regexp)
1845 (setq comint-prompt-regexp (concat py-shell-input-prompt-1-regexp "\\|"
1846 py-shell-input-prompt-2-regexp "\\|"
1848 (add-hook 'comint-output-filter-functions
1849 'py-comint-output-filter-function)
1851 (add-hook 'comint-output-filter-functions 'py-pdbtrack-track-stack-file)
1852 (setq py-pdbtrack-do-tracking-p t)
1853 (set-syntax-table py-mode-syntax-table)
1854 (use-local-map py-shell-map)
1855 (run-hooks 'py-shell-hook)
1858 (defun py-clear-queue ()
1859 "Clear the queue of temporary files waiting to execute."
1861 (let ((n (length py-file-queue)))
1862 (mapc 'delete-file py-file-queue)
1863 (setq py-file-queue nil)
1864 (message "%d pending files de-queued." n)))
1867 (defun py-execute-region (start end &optional async)
1868 "Execute the region in a Python interpreter.
1870 The region is first copied into a temporary file (in the directory
1871 `py-temp-directory'). If there is no Python interpreter shell
1872 running, this file is executed synchronously using
1873 `shell-command-on-region'. If the program is long running, use
1874 \\[universal-argument] to run the command asynchronously in its own
1877 When this function is used programmatically, arguments START and END
1878 specify the region to execute, and optional third argument ASYNC, if
1879 non-nil, specifies to run the command asynchronously in its own
1882 If the Python interpreter shell is running, the region is execfile()'d
1883 in that shell. If you try to execute regions too quickly,
1884 `python-mode' will queue them up and execute them one at a time when
1885 it sees a `>>> ' prompt from Python. Each time this happens, the
1886 process buffer is popped into a window (if it's not already in some
1887 window) so you can see it, and a comment of the form
1889 \t## working on region in file <name>...
1891 is inserted at the end. See also the command `py-clear-queue'."
1892 (interactive "r\nP")
1893 ;; Skip ahead to the first non-blank line
1894 (let* ((proc (get-process py-which-bufname))
1895 (temp (if (memq 'broken-temp-names py-emacs-features)
1897 ((sn py-serial-number)
1898 (pid (and (fboundp 'emacs-pid) (emacs-pid))))
1899 (setq py-serial-number (1+ py-serial-number))
1901 (format "python-%d-%d" sn pid)
1902 (format "python-%d" sn)))
1903 (make-temp-name "python-")))
1904 (file (concat (expand-file-name temp py-temp-directory) ".py"))
1905 (cur (current-buffer))
1906 (buf (get-buffer-create file))
1908 ;; Write the contents of the buffer, watching out for indented regions.
1912 (while (and (looking-at "\\s *$")
1915 (setq start (point))
1917 (error "Region is empty"))
1918 (setq py-line-number-offset (count-lines 1 start))
1919 (let ((needs-if (/= (py-point 'bol) (py-point 'boi))))
1924 (setq py-line-number-offset (- py-line-number-offset 1)))
1925 (insert-buffer-substring cur start end)
1926 ;; Set the shell either to the #! line command, or to the
1927 ;; py-which-shell buffer local variable.
1928 (setq shell (or (py-choose-shell-by-shebang)
1929 (py-choose-shell-by-import)
1932 ;; always run the code in its own asynchronous subprocess
1934 ;; User explicitly wants this to run in its own async subprocess
1937 (write-region (point-min) (point-max) file nil 'nomsg))
1938 (let* ((buf (generate-new-buffer-name py-output-buffer))
1939 ;; TBD: a horrible hack, but why create new Custom variables?
1940 (arg (if (string-equal py-which-bufname "Python")
1942 (start-process py-which-bufname buf shell arg file)
1944 (py-postprocess-output-buffer buf)
1945 ;; TBD: clean up the temporary file!
1947 ;; if the Python interpreter shell is running, queue it up for
1950 ;; use the existing python shell
1953 (write-region (point-min) (point-max) file nil 'nomsg))
1954 (if (not py-file-queue)
1955 (py-execute-file proc file)
1956 (message "File %s queued for execution" file))
1957 (setq py-file-queue (append py-file-queue (list file)))
1958 (setq py-exception-buffer (cons file (current-buffer))))
1960 ;; TBD: a horrible hack, but why create new Custom variables?
1961 (let ((cmd (concat py-which-shell (if (string-equal py-which-bufname
1964 ;; otherwise either run it synchronously in a subprocess
1967 (shell-command-on-region (point-min) (point-max)
1968 cmd py-output-buffer))
1969 ;; shell-command-on-region kills the output buffer if it never
1970 ;; existed and there's no output from the command
1971 (if (not (get-buffer py-output-buffer))
1972 (message "No output.")
1973 (setq py-exception-buffer (current-buffer))
1974 (let ((err-p (py-postprocess-output-buffer py-output-buffer)))
1975 (pop-to-buffer py-output-buffer)
1977 (pop-to-buffer py-exception-buffer)))
1980 ;; Clean up after ourselves.
1984 ;; Code execution commands
1985 (defun py-execute-buffer (&optional async)
1986 "Send the contents of the buffer to a Python interpreter.
1987 If the file local variable `py-master-file' is non-nil, execute the
1988 named file instead of the buffer's file.
1990 If there is a *Python* process buffer it is used. If a clipping
1991 restriction is in effect, only the accessible portion of the buffer is
1992 sent. A trailing newline will be supplied if needed.
1994 See the `\\[py-execute-region]' docs for an account of some
1995 subtleties, including the use of the optional ASYNC argument."
1997 (let ((old-buffer (current-buffer)))
1999 (let* ((filename (expand-file-name py-master-file))
2000 (buffer (or (get-file-buffer filename)
2001 (find-file-noselect filename))))
2002 (set-buffer buffer)))
2003 (py-execute-region (point-min) (point-max) async)
2004 (pop-to-buffer old-buffer)))
2006 (defun py-execute-import-or-reload (&optional async)
2007 "Import the current buffer's file in a Python interpreter.
2009 If the file has already been imported, then do reload instead to get
2012 If the file's name does not end in \".py\", then do execfile instead.
2014 If the current buffer is not visiting a file, do `py-execute-buffer'
2017 If the file local variable `py-master-file' is non-nil, import or
2018 reload the named file instead of the buffer's file. The file may be
2019 saved based on the value of `py-execute-import-or-reload-save-p'.
2021 See the `\\[py-execute-region]' docs for an account of some
2022 subtleties, including the use of the optional ASYNC argument.
2024 This may be preferable to `\\[py-execute-buffer]' because:
2026 - Definitions stay in their module rather than appearing at top
2027 level, where they would clutter the global namespace and not affect
2028 uses of qualified names (MODULE.NAME).
2030 - The Python debugger gets line number information about the functions."
2032 ;; Check file local variable py-master-file
2034 (let* ((filename (expand-file-name py-master-file))
2035 (buffer (or (get-file-buffer filename)
2036 (find-file-noselect filename))))
2037 (set-buffer buffer)))
2038 (let ((file (buffer-file-name (current-buffer))))
2041 ;; Maybe save some buffers
2042 (save-some-buffers (not py-ask-about-save) nil)
2044 (if (string-match "\\.py$" file)
2045 (let ((f (file-name-sans-extension
2046 (file-name-nondirectory file))))
2047 (format "if globals().has_key('%s'):\n reload(%s)\nelse:\n import %s\n"
2049 (format "execfile(r'%s')\n" file))
2052 (py-execute-buffer async))))
2055 (defun py-execute-def-or-class (&optional async)
2056 "Send the current function or class definition to a Python interpreter.
2058 If there is a *Python* process buffer it is used.
2060 See the `\\[py-execute-region]' docs for an account of some
2061 subtleties, including the use of the optional ASYNC argument."
2064 (py-mark-def-or-class)
2065 ;; mark is before point
2066 (py-execute-region (mark) (point) async)))
2069 (defun py-execute-string (string &optional async)
2070 "Send the argument STRING to a Python interpreter.
2072 If there is a *Python* process buffer it is used.
2074 See the `\\[py-execute-region]' docs for an account of some
2075 subtleties, including the use of the optional ASYNC argument."
2076 (interactive "sExecute Python command: ")
2078 (set-buffer (get-buffer-create
2079 (generate-new-buffer-name " *Python Command*")))
2081 (py-execute-region (point-min) (point-max) async)))
2085 (defun py-jump-to-exception (file line)
2086 "Jump to the Python code in FILE at LINE."
2087 (let ((buffer (cond ((string-equal file "<stdin>")
2088 (if (consp py-exception-buffer)
2089 (cdr py-exception-buffer)
2090 py-exception-buffer))
2091 ((and (consp py-exception-buffer)
2092 (string-equal file (car py-exception-buffer)))
2093 (cdr py-exception-buffer))
2094 ((py-safe (find-file-noselect file)))
2095 ;; could not figure out what file the exception
2096 ;; is pointing to, so prompt for it
2097 (t (find-file (read-file-name "Exception file: "
2100 ;; Fiddle about with line number
2101 (setq line (+ py-line-number-offset line))
2103 (pop-to-buffer buffer)
2104 ;; Force Python mode
2105 (if (not (eq major-mode 'python-mode))
2108 (message "Jumping to exception in file %s on line %d" file line)))
2110 (defun py-mouseto-exception (event)
2111 "Jump to the code which caused the Python exception at EVENT.
2112 EVENT is usually a mouse click."
2115 ((fboundp 'event-point)
2117 (let* ((point (event-point event))
2118 (buffer (event-buffer event))
2119 (e (and point buffer (extent-at point buffer 'py-exc-info)))
2120 (info (and e (extent-property e 'py-exc-info))))
2121 (message "Event point: %d, info: %s" point info)
2123 (py-jump-to-exception (car info) (cdr info)))
2125 ;; Emacs -- Please port this!
2128 (defun py-goto-exception ()
2129 "Go to the line indicated by the traceback."
2134 (if (looking-at py-traceback-line-re)
2135 (setq file (match-string 1)
2136 line (string-to-number (match-string 2)))))
2138 (error "Not on a traceback line"))
2139 (py-jump-to-exception file line)))
2141 (defun py-find-next-exception (start buffer searchdir errwhere)
2142 "Find the next Python exception and jump to the code that caused it.
2143 START is the buffer position in BUFFER from which to begin searching
2144 for an exception. SEARCHDIR is a function, either
2145 `re-search-backward' or `re-search-forward' indicating the direction
2146 to search. ERRWHERE is used in an error message if the limit (top or
2147 bottom) of the trackback stack is encountered."
2151 (goto-char (py-point start))
2152 (if (funcall searchdir py-traceback-line-re nil t)
2153 (setq file (match-string 1)
2154 line (string-to-number (match-string 2)))))
2156 (py-jump-to-exception file line)
2157 (error "%s of traceback" errwhere))))
2159 (defun py-down-exception (&optional bottom)
2160 "Go to the next line down in the traceback.
2161 With \\[univeral-argument] (programmatically, optional argument
2162 BOTTOM), jump to the bottom (innermost) exception in the exception
2165 (let* ((proc (get-process "Python"))
2166 (buffer (if proc "*Python*" py-output-buffer)))
2168 (py-find-next-exception 'eob buffer 're-search-backward "Bottom")
2169 (py-find-next-exception 'eol buffer 're-search-forward "Bottom"))))
2171 (defun py-up-exception (&optional top)
2172 "Go to the previous line up in the traceback.
2173 With \\[universal-argument] (programmatically, optional argument TOP)
2174 jump to the top (outermost) exception in the exception stack."
2176 (let* ((proc (get-process "Python"))
2177 (buffer (if proc "*Python*" py-output-buffer)))
2179 (py-find-next-exception 'bob buffer 're-search-forward "Top")
2180 (py-find-next-exception 'bol buffer 're-search-backward "Top"))))
2183 ;; Electric deletion
2184 (defun py-electric-backspace (arg)
2185 "Delete preceding character or levels of indentation.
2186 Deletion is performed by calling the function in `py-backspace-function'
2187 with a single argument (the number of characters to delete).
2189 If point is at the leftmost column, delete the preceding newline.
2191 Otherwise, if point is at the leftmost non-whitespace character of a
2192 line that is neither a continuation line nor a non-indenting comment
2193 line, or if point is at the end of a blank line, this command reduces
2194 the indentation to match that of the line that opened the current
2195 block of code. The line that opened the block is displayed in the
2196 echo area to help you keep track of where you are. With
2197 \\[universal-argument] dedents that many blocks (but not past column
2200 Otherwise the preceding character is deleted, converting a tab to
2201 spaces if needed so that only a single column position is deleted.
2202 \\[universal-argument] specifies how many characters to delete;
2205 When used programmatically, argument ARG specifies the number of
2206 blocks to dedent, or the number of characters to delete, as indicated
2209 (if (or (/= (current-indentation) (current-column))
2211 (py-continuation-line-p)
2212 ; (not py-honor-comment-indentation)
2213 ; (looking-at "#[^ \t\n]") ; non-indenting #
2215 (funcall py-backspace-function arg)
2216 ;; else indent the same as the colon line that opened the block
2217 ;; force non-blank so py-goto-block-up doesn't ignore it
2220 (let ((base-indent 0) ; indentation of base line
2221 (base-text "") ; and text of base line
2225 (condition-case nil ; in case no enclosing block
2227 (py-goto-block-up 'no-mark)
2228 (setq base-indent (current-indentation)
2229 base-text (py-suck-up-leading-text)
2232 (setq arg (1- arg))))
2233 (delete-char 1) ; toss the dummy character
2234 (delete-horizontal-space)
2235 (indent-to base-indent)
2237 (message "Closes block: %s" base-text)))))
2240 (defun py-electric-delete (arg)
2241 "Delete preceding or following character or levels of whitespace.
2243 The behavior of this function depends on the variable
2244 `delete-key-deletes-forward'. If this variable is nil (or does not
2245 exist, as in older Emacsen and non-XEmacs versions), then this
2246 function behaves identically to \\[c-electric-backspace].
2248 If `delete-key-deletes-forward' is non-nil and is supported in your
2249 Emacs, then deletion occurs in the forward direction, by calling the
2250 function in `py-delete-function'.
2252 \\[universal-argument] (programmatically, argument ARG) specifies the
2253 number of characters to delete (default is 1)."
2255 (if (or (and (fboundp 'delete-forward-p) ;XEmacs 21
2257 (and (boundp 'delete-key-deletes-forward) ;XEmacs 20
2258 delete-key-deletes-forward))
2259 (funcall py-delete-function arg)
2260 (py-electric-backspace arg)))
2262 ;; required for pending-del and delsel modes
2263 (put 'py-electric-colon 'delete-selection t) ;delsel
2264 (put 'py-electric-colon 'pending-delete t) ;pending-del
2265 (put 'py-electric-backspace 'delete-selection 'supersede) ;delsel
2266 (put 'py-electric-backspace 'pending-delete 'supersede) ;pending-del
2267 (put 'py-electric-delete 'delete-selection 'supersede) ;delsel
2268 (put 'py-electric-delete 'pending-delete 'supersede) ;pending-del
2272 (defun py-indent-line (&optional arg)
2273 "Fix the indentation of the current line according to Python rules.
2274 With \\[universal-argument] (programmatically, the optional argument
2275 ARG non-nil), ignore dedenting rules for block closing statements
2276 \(e.g. return, raise, break, continue, pass)
2278 This function is normally bound to `indent-line-function' so
2279 \\[indent-for-tab-command] will call it."
2281 (let* ((ci (current-indentation))
2282 (move-to-indentation-p (<= (current-column) ci))
2283 (need (py-compute-indentation (not arg)))
2284 (cc (current-column)))
2285 ;; dedent out a level if previous command was the same unless we're in
2287 (if (and (equal last-command this-command)
2291 (delete-horizontal-space)
2292 (indent-to (* (/ (- cc 1) py-indent-offset) py-indent-offset)))
2294 ;; see if we need to dedent
2296 (setq need (- need py-indent-offset)))
2297 (if (or py-tab-always-indent
2298 move-to-indentation-p)
2299 (progn (if (/= ci need)
2302 (delete-horizontal-space)
2304 (if move-to-indentation-p (back-to-indentation)))
2307 (defun py-newline-and-indent ()
2308 "Strives to act like the Emacs `newline-and-indent'.
2309 This is just `strives to' because correct indentation can't be computed
2310 from scratch for Python code. In general, deletes the whitespace before
2311 point, inserts a newline, and takes an educated guess as to how you want
2312 the new line indented."
2314 (let ((ci (current-indentation)))
2315 (if (< ci (current-column)) ; if point beyond indentation
2316 (newline-and-indent)
2317 ;; else try to act like newline-and-indent "normally" acts
2320 (move-to-column ci))))
2322 (defun py-compute-indentation (honor-block-close-p)
2323 "Compute Python indentation.
2324 When HONOR-BLOCK-CLOSE-P is non-nil, statements such as `return',
2325 `raise', `break', `continue', and `pass' force one level of
2329 (let* ((bod (py-point 'bod))
2330 (pps (parse-partial-sexp bod (point)))
2331 (boipps (parse-partial-sexp bod (py-point 'boi)))
2334 ;; are we inside a multi-line string or comment?
2335 ((or (and (nth 3 pps) (nth 3 boipps))
2336 (and (nth 4 pps) (nth 4 boipps)))
2338 (if (not py-align-multiline-strings-p) 0
2339 ;; skip back over blank & non-indenting comment lines
2340 ;; note: will skip a blank or non-indenting comment line
2341 ;; that happens to be a continuation line too
2342 (re-search-backward "^[ \t]*\\([^ \t\n#]\\|#[ \t\n]\\)" nil 'move)
2343 (back-to-indentation)
2345 ;; are we on a continuation line?
2346 ((py-continuation-line-p)
2347 (let ((startpos (point))
2348 (open-bracket-pos (py-nesting-level))
2349 endpos searching found state cind cline)
2350 (if open-bracket-pos
2352 (setq endpos (py-point 'bol))
2353 (py-goto-initial-line)
2354 (setq cind (current-indentation))
2357 (nth 9 (save-excursion
2358 (parse-partial-sexp (point) endpos)))
2360 (if (search-forward "\n" bp t) (setq cline cind))
2362 (skip-chars-forward " \t")
2363 (setq cind (if (memq (following-char) '(?\n ?# ?\\))
2364 (+ cline py-indent-offset)
2365 (current-column)))))
2366 ;; else on backslash continuation line
2368 (if (py-continuation-line-p) ; on at least 3rd line in block
2369 (current-indentation) ; so just continue the pattern
2370 ;; else started on 2nd line in block, so indent more.
2371 ;; if base line is an assignment with a start on a RHS,
2372 ;; indent to 2 beyond the leftmost "="; else skip first
2373 ;; chunk of non-whitespace characters on base line, + 1 more
2376 (setq endpos (point)
2378 (back-to-indentation)
2379 (setq startpos (point))
2380 ;; look at all "=" from left to right, stopping at first
2381 ;; one not nested in a list or string
2383 (skip-chars-forward "^=" endpos)
2384 (if (= (point) endpos)
2385 (setq searching nil)
2387 (setq state (parse-partial-sexp startpos (point)))
2388 (if (and (zerop (car state)) ; not in a bracket
2389 (null (nth 3 state))) ; & not in a string
2391 (setq searching nil) ; done searching in any case
2394 (eq (following-char) ?=)
2395 (memq (char-after (- (point) 2))
2397 (if (or (not found) ; not an assignment
2398 (looking-at "[ \t]*\\\\")) ; <=><spaces><backslash>
2400 (goto-char startpos)
2401 (skip-chars-forward "^ \t\n")))
2402 ;; if this is a continuation for a block opening
2403 ;; statement, add some extra offset.
2404 (+ (current-column) (if (py-statement-opens-block-p)
2405 py-continuation-offset 0)
2409 ;; not on a continuation line
2410 ((bobp) (current-indentation))
2412 ;; Dfn: "Indenting comment line". A line containing only a
2413 ;; comment, but which is treated like a statement for
2414 ;; indentation calculation purposes. Such lines are only
2415 ;; treated specially by the mode; they are not treated
2416 ;; specially by the Python interpreter.
2418 ;; The rules for indenting comment lines are a line where:
2419 ;; - the first non-whitespace character is `#', and
2420 ;; - the character following the `#' is whitespace, and
2421 ;; - the line is dedented with respect to (i.e. to the left
2422 ;; of) the indentation of the preceding non-blank line.
2424 ;; The first non-blank line following an indenting comment
2425 ;; line is given the same amount of indentation as the
2426 ;; indenting comment line.
2428 ;; All other comment-only lines are ignored for indentation
2431 ;; Are we looking at a comment-only line which is *not* an
2432 ;; indenting comment line? If so, we assume that it's been
2433 ;; placed at the desired indentation, so leave it alone.
2434 ;; Indenting comment lines are aligned as statements down
2436 ((and (looking-at "[ \t]*#[^ \t\n]")
2437 ;; NOTE: this test will not be performed in older Emacsen
2438 (fboundp 'forward-comment)
2439 (<= (current-indentation)
2441 (forward-comment (- (point-max)))
2442 (current-indentation))))
2443 (current-indentation))
2445 ;; else indentation based on that of the statement that
2446 ;; precedes us; use the first line of that statement to
2447 ;; establish the base, in case the user forced a non-std
2448 ;; indentation for the continuation lines (if any)
2450 ;; skip back over blank & non-indenting comment lines note:
2451 ;; will skip a blank or non-indenting comment line that
2452 ;; happens to be a continuation line too. use fast Emacs 19
2453 ;; function if it's there.
2454 (if (and (eq py-honor-comment-indentation nil)
2455 (fboundp 'forward-comment))
2456 (forward-comment (- (point-max)))
2457 (let ((prefix-re (concat py-block-comment-prefix "[ \t]*"))
2460 (re-search-backward "^[ \t]*\\([^ \t\n#]\\|#\\)" nil 'move)
2461 (setq done (or (bobp)
2462 (and (eq py-honor-comment-indentation t)
2464 (back-to-indentation)
2465 (not (looking-at prefix-re))
2467 (and (not (eq py-honor-comment-indentation t))
2469 (back-to-indentation)
2470 (and (not (looking-at prefix-re))
2471 (or (looking-at "[^#]")
2472 (not (zerop (current-column)))
2477 ;; if we landed inside a string, go to the beginning of that
2478 ;; string. this handles triple quoted, multi-line spanning
2480 (py-goto-beginning-of-tqs (nth 3 (parse-partial-sexp bod (point))))
2481 ;; now skip backward over continued lines
2482 (setq placeholder (point))
2483 (py-goto-initial-line)
2484 ;; we may *now* have landed in a TQS, so find the beginning of
2486 (py-goto-beginning-of-tqs
2487 (save-excursion (nth 3 (parse-partial-sexp
2488 placeholder (point)))))
2489 (+ (current-indentation)
2490 (if (py-statement-opens-block-p)
2492 (if (and honor-block-close-p (py-statement-closes-block-p))
2493 (- py-indent-offset)
2497 (defun py-guess-indent-offset (&optional global)
2498 "Guess a good value for, and change, `py-indent-offset'.
2500 By default, make a buffer-local copy of `py-indent-offset' with the
2501 new value, so that other Python buffers are not affected. With
2502 \\[universal-argument] (programmatically, optional argument GLOBAL),
2503 change the global value of `py-indent-offset'. This affects all
2504 Python buffers (that don't have their own buffer-local copy), both
2505 those currently existing and those created later in the Emacs session.
2507 Some people use a different value for `py-indent-offset' than you use.
2508 There's no excuse for such foolishness, but sometimes you have to deal
2509 with their ugly code anyway. This function examines the file and sets
2510 `py-indent-offset' to what it thinks it was when they created the
2513 Specifically, it searches forward from the statement containing point,
2514 looking for a line that opens a block of code. `py-indent-offset' is
2515 set to the difference in indentation between that line and the Python
2516 statement following it. If the search doesn't succeed going forward,
2517 it's tried again going backward."
2518 (interactive "P") ; raw prefix arg
2524 (py-goto-initial-line)
2525 (while (not (or found (eobp)))
2526 (when (and (re-search-forward ":[ \t]*\\($\\|[#\\]\\)" nil 'move)
2527 (not (py-in-literal restart)))
2528 (setq restart (point))
2529 (py-goto-initial-line)
2530 (if (py-statement-opens-block-p)
2532 (goto-char restart))))
2535 (py-goto-initial-line)
2536 (while (not (or found (bobp)))
2538 (re-search-backward ":[ \t]*\\($\\|[#\\]\\)" nil 'move)
2539 (or (py-goto-initial-line) t) ; always true -- side effect
2540 (py-statement-opens-block-p)))))
2541 (setq colon-indent (current-indentation)
2542 found (and found (zerop (py-next-statement 1)))
2543 new-value (- (current-indentation) colon-indent))
2546 (error "Sorry, couldn't guess a value for py-indent-offset")
2547 (funcall (if global 'kill-local-variable 'make-local-variable)
2549 (setq py-indent-offset new-value)
2551 (message "%s value of py-indent-offset set to %d"
2552 (if global "Global" "Local")
2556 (defun py-comment-indent-function ()
2557 "Python version of `comment-indent-function'."
2558 ;; This is required when filladapt is turned off. Without it, when
2559 ;; filladapt is not used, comments which start in column zero
2560 ;; cascade one character to the right
2563 (let ((eol (py-point 'eol)))
2564 (and comment-start-skip
2565 (re-search-forward comment-start-skip eol t)
2566 (setq eol (match-beginning 0)))
2568 (skip-chars-backward " \t")
2569 (max comment-column (+ (current-column) (if (bolp) 0 1)))
2572 (defun py-narrow-to-defun (&optional class)
2573 "Make text outside current defun invisible.
2574 The defun visible is the one that contains point or follows point.
2575 Optional CLASS is passed directly to `py-beginning-of-def-or-class'."
2579 (py-end-of-def-or-class class)
2580 (let ((end (point)))
2581 (py-beginning-of-def-or-class class)
2582 (narrow-to-region (point) end))))
2585 (defun py-shift-region (start end count)
2586 "Indent lines from START to END by COUNT spaces."
2593 (setq start (point))
2594 (let (deactivate-mark)
2595 (indent-rigidly start end count))))
2597 (defun py-shift-region-left (start end &optional count)
2598 "Shift region of Python code to the left.
2599 The lines from the line containing the start of the current region up
2600 to (but not including) the line containing the end of the region are
2601 shifted to the left, by `py-indent-offset' columns.
2603 If a prefix argument is given, the region is instead shifted by that
2604 many columns. With no active region, dedent only the current line.
2605 You cannot dedent the region if any line is already at column zero."
2608 (m (condition-case nil (mark) (mark-inactive nil)))
2609 (arg current-prefix-arg))
2611 (list (min p m) (max p m) arg)
2612 (list p (save-excursion (forward-line 1) (point)) arg))))
2613 ;; if any line is at column zero, don't shift the region
2616 (while (< (point) end)
2617 (back-to-indentation)
2618 (if (and (zerop (current-column))
2619 (not (looking-at "\\s *$")))
2620 (error "Region is at left edge"))
2622 (py-shift-region start end (- (prefix-numeric-value
2623 (or count py-indent-offset))))
2624 (py-keep-region-active))
2626 (defun py-shift-region-right (start end &optional count)
2627 "Shift region of Python code to the right.
2628 The lines from the line containing the start of the current region up
2629 to (but not including) the line containing the end of the region are
2630 shifted to the right, by `py-indent-offset' columns.
2632 If a prefix argument is given, the region is instead shifted by that
2633 many columns. With no active region, indent only the current line."
2636 (m (condition-case nil (mark) (mark-inactive nil)))
2637 (arg current-prefix-arg))
2639 (list (min p m) (max p m) arg)
2640 (list p (save-excursion (forward-line 1) (point)) arg))))
2641 (py-shift-region start end (prefix-numeric-value
2642 (or count py-indent-offset)))
2643 (py-keep-region-active))
2645 (defun py-indent-region (start end &optional indent-offset)
2646 "Reindent a region of Python code.
2648 The lines from the line containing the start of the current region up
2649 to (but not including) the line containing the end of the region are
2650 reindented. If the first line of the region has a non-whitespace
2651 character in the first column, the first line is left alone and the
2652 rest of the region is reindented with respect to it. Else the entire
2653 region is reindented with respect to the (closest code or indenting
2654 comment) statement immediately preceding the region.
2656 This is useful when code blocks are moved or yanked, when enclosing
2657 control structures are introduced or removed, or to reformat code
2658 using a new value for the indentation offset.
2660 If a numeric prefix argument is given, it will be used as the value of
2661 the indentation offset. Else the value of `py-indent-offset' will be
2664 Warning: The region must be consistently indented before this function
2665 is called! This function does not compute proper indentation from
2666 scratch (that's impossible in Python), it merely adjusts the existing
2667 indentation to be correct in context.
2669 Warning: This function really has no idea what to do with
2670 non-indenting comment lines, and shifts them as if they were indenting
2671 comment lines. Fixing this appears to require telepathy.
2673 Special cases: whitespace is deleted from blank lines; continuation
2674 lines are shifted by the same amount their initial line was shifted,
2675 in order to preserve their relative indentation with respect to their
2676 initial line; and comment lines beginning in column 1 are ignored."
2677 (interactive "*r\nP") ; region; raw prefix arg
2679 (goto-char end) (beginning-of-line) (setq end (point-marker))
2680 (goto-char start) (beginning-of-line)
2681 (let ((py-indent-offset (prefix-numeric-value
2682 (or indent-offset py-indent-offset)))
2683 (indents '(-1)) ; stack of active indent levels
2684 (target-column 0) ; column to which to indent
2685 (base-shifted-by 0) ; amount last base line was shifted
2686 (indent-base (if (looking-at "[ \t\n]")
2687 (py-compute-indentation t)
2690 (while (< (point) end)
2691 (setq ci (current-indentation))
2692 ;; figure out appropriate target column
2694 ((or (eq (following-char) ?#) ; comment in column 1
2695 (looking-at "[ \t]*$")) ; entirely blank
2696 (setq target-column 0))
2697 ((py-continuation-line-p) ; shift relative to base line
2698 (setq target-column (+ ci base-shifted-by)))
2700 (if (> ci (car indents)) ; going deeper; push it
2701 (setq indents (cons ci indents))
2702 ;; else we should have seen this indent before
2703 (setq indents (memq ci indents)) ; pop deeper indents
2705 (error "Bad indentation in region, at line %d"
2708 (1+ (count-lines 1 (point)))))))
2709 (setq target-column (+ indent-base
2711 (- (length indents) 2))))
2712 (setq base-shifted-by (- target-column ci))))
2714 (if (/= ci target-column)
2716 (delete-horizontal-space)
2717 (indent-to target-column)))
2719 (set-marker end nil))
2721 (defun py-comment-region (beg end &optional arg)
2722 "Like `comment-region' but uses double hash (`#') comment starter."
2723 (interactive "r\nP")
2724 (let ((comment-start py-block-comment-prefix))
2725 (comment-region beg end arg)))
2727 (defun py-join-words-wrapping (words separator line-prefix line-length)
2729 (current-line line-prefix))
2731 (let* ((word (car words))
2732 (maybe-line (concat current-line word separator)))
2733 (if (> (length maybe-line) line-length)
2734 (setq lines (cons (substring current-line 0 -1) lines)
2735 current-line (concat line-prefix word separator " "))
2736 (setq current-line (concat maybe-line " "))))
2737 (setq words (cdr words)))
2738 (setq lines (cons (substring
2739 current-line 0 (- 0 (length separator) 1)) lines))
2740 (mapconcat 'identity (nreverse lines) "\n")))
2742 (defun py-sort-imports ()
2743 "Sort multiline imports.
2744 Put point inside the parentheses of a multiline import and hit
2745 \\[py-sort-imports] to sort the imports lexicographically"
2748 (let ((open-paren (save-excursion (progn (up-list -1) (point))))
2749 (close-paren (save-excursion (progn (up-list 1) (point))))
2751 (goto-char (1+ open-paren))
2752 (skip-chars-forward " \n\t")
2753 (setq sorted-imports
2756 (split-string (buffer-substring
2758 (save-excursion (goto-char (1- close-paren))
2759 (skip-chars-backward " \n\t")
2762 ;; XXX Should this sort case insensitively?
2764 ;; Remove empty strings.
2765 (delete-region open-paren close-paren)
2766 (goto-char open-paren)
2768 (insert (py-join-words-wrapping (remove "" sorted-imports) "," " " 78))
2774 ;; Functions for moving point
2775 (defun py-previous-statement (count)
2776 "Go to the start of the COUNTth preceding Python statement.
2777 By default, goes to the previous statement. If there is no such
2778 statement, goes to the first statement. Return count of statements
2779 left to move. `Statements' do not include blank, comment, or
2780 continuation lines."
2781 (interactive "p") ; numeric prefix arg
2782 (if (< count 0) (py-next-statement (- count))
2783 (py-goto-initial-line)
2786 (setq start (point)) ; always true -- side effect
2788 (zerop (forward-line -1))
2789 (py-goto-statement-at-or-above))
2790 (setq count (1- count)))
2791 (if (> count 0) (goto-char start)))
2794 (defun py-next-statement (count)
2795 "Go to the start of next Python statement.
2796 If the statement at point is the i'th Python statement, goes to the
2797 start of statement i+COUNT. If there is no such statement, goes to the
2798 last statement. Returns count of statements left to move. `Statements'
2799 do not include blank, comment, or continuation lines."
2800 (interactive "p") ; numeric prefix arg
2801 (if (< count 0) (py-previous-statement (- count))
2805 (setq start (point)) ; always true -- side effect
2807 (py-goto-statement-below))
2808 (setq count (1- count)))
2809 (if (> count 0) (goto-char start)))
2812 (defalias 'py-goto-block-up 'py-beginning-of-block)
2813 (defun py-beginning-of-block (&optional nomark)
2814 "Move to start of current block.
2815 Go to the statement that starts the smallest enclosing block; roughly
2816 speaking, this will be the closest preceding statement that ends with a
2817 colon and is indented less than the statement you started on. If
2818 successful, also sets the mark to the starting point.
2820 `\\[py-mark-block]' can be used afterward to mark the whole code
2823 If called from a program, the mark will not be set if optional argument
2826 (let ((start (point))
2829 (py-goto-initial-line)
2830 ;; if on blank or non-indenting comment line, use the preceding stmt
2831 (if (looking-at "[ \t]*\\($\\|#[^ \t\n]\\)")
2833 (py-goto-statement-at-or-above)
2834 (setq found (py-statement-opens-block-p))))
2835 ;; search back for colon line indented less
2836 (setq initial-indent (current-indentation))
2837 (if (zerop initial-indent)
2839 (goto-char (point-min)))
2840 (while (not (or found (bobp)))
2843 (re-search-backward ":[ \t]*\\($\\|[#\\]\\)" nil 'move)
2844 (or (py-goto-initial-line) t) ; always true -- side effect
2845 (< (current-indentation) initial-indent)
2846 (py-statement-opens-block-p))))
2849 (or nomark (push-mark start))
2850 (back-to-indentation))
2852 (error "Enclosing block not found"))))
2854 (defun py-beginning-of-def-or-class (&optional class count)
2855 "Move point to start of `def' or `class'.
2857 Searches back for the closest preceding `def'. If you supply a prefix
2858 arg, looks for a `class' instead. The docs below assume the `def'
2859 case; just substitute `class' for `def' for the other case.
2860 Programmatically, if CLASS is `either', then moves to either `class'
2863 When second optional argument is given programmatically, move to the
2864 COUNTth start of `def'.
2866 If point is in a `def' statement already, and after the `d', simply
2867 moves point to the start of the statement.
2869 Otherwise (i.e. when point is not in a `def' statement, or at or
2870 before the `d' of a `def' statement), searches for the closest
2871 preceding `def' statement, and leaves point at its start. If no such
2872 statement can be found, leaves point at the start of the buffer.
2874 Returns t iff a `def' statement is found by these rules.
2876 Note that doing this command repeatedly will take you closer to the
2877 start of the buffer each time.
2879 To mark the current `def', see `\\[py-mark-def-or-class]'."
2880 (interactive "P") ; raw prefix arg
2881 (lexical-let* ((count (or count 1))
2882 (step (if (< 0 count) -1 1))
2883 (start-re (cond ((eq class 'either) "^[ \t]*\\(class\\|def\\)\\>")
2884 (class "^[ \t]*class\\>")
2885 (t "^[ \t]*def\\>"))))
2888 (unless (looking-at start-re) (end-of-line))
2891 (re-search-backward start-re nil 'move (- step))
2893 ;; if inside a string
2894 (nth 3 (parse-partial-sexp (point-min) (point)))
2895 (goto-char (match-beginning 0))
2896 (setq count (+ count step)))
2899 ;; Backwards compatibility
2900 (defalias 'beginning-of-python-def-or-class 'py-beginning-of-def-or-class)
2902 (defun py-end-of-def-or-class (&optional class count)
2903 "Move point beyond end of `def' or `class' body.
2905 By default, looks for an appropriate `def'. If you supply a prefix
2906 arg, looks for a `class' instead. The docs below assume the `def'
2907 case; just substitute `class' for `def' for the other case.
2908 Programmatically, if CLASS is `either', then moves to either `class'
2911 When second optional argument is given programmatically, move to the
2912 COUNTth end of `def'.
2914 If point is in a `def' statement already, this is the `def' we use.
2916 Else, if the `def' found by `\\[py-beginning-of-def-or-class]'
2917 contains the statement you started on, that's the `def' we use.
2919 Otherwise, we search forward for the closest following `def', and use that.
2921 If a `def' can be found by these rules, point is moved to the start of
2922 the line immediately following the `def' block, and the position of the
2923 start of the `def' is returned.
2925 Else point is moved to the end of the buffer, and nil is returned.
2927 Note that doing this command repeatedly will take you closer to the
2928 end of the buffer each time.
2930 To mark the current `def', see `\\[py-mark-def-or-class]'."
2931 (interactive "P") ; raw prefix arg
2932 (if (and count (/= count 1))
2933 (py-beginning-of-def-or-class (- 1 count)))
2934 (let ((start (progn (py-goto-initial-line) (point)))
2935 (which (cond ((eq class 'either) "\\(class\\|def\\)")
2939 ;; move point to start of appropriate def/class
2940 (if (looking-at (concat "[ \t]*" which "\\>")) ; already on one
2941 (setq state 'at-beginning)
2942 ;; else see if py-beginning-of-def-or-class hits container
2943 (if (and (py-beginning-of-def-or-class class)
2944 (progn (py-goto-beyond-block)
2946 (setq state 'at-end)
2947 ;; else search forward
2949 (if (re-search-forward (concat "^[ \t]*" which "\\>") nil 'move)
2950 (progn (setq state 'at-beginning)
2951 (beginning-of-line)))))
2953 ((eq state 'at-beginning) (py-goto-beyond-block) t)
2954 ((eq state 'at-end) t)
2955 ((eq state 'not-found) nil)
2956 (t (error "Internal error in `py-end-of-def-or-class'")))))
2958 ;; Backwards compabitility
2959 (defalias 'end-of-python-def-or-class 'py-end-of-def-or-class)
2962 ;; Functions for marking regions
2963 (defun py-mark-block (&optional extend just-move)
2964 "Mark following block of lines. With prefix arg, mark structure.
2965 Easier to use than explain. It sets the region to an `interesting'
2966 block of succeeding lines. If point is on a blank line, it goes down to
2967 the next non-blank line. That will be the start of the region. The end
2968 of the region depends on the kind of line at the start:
2970 - If a comment, the region will include all succeeding comment lines up
2971 to (but not including) the next non-comment line (if any).
2973 - Else if a prefix arg is given, and the line begins one of these
2976 if elif else try except finally for while def class
2978 the region will be set to the body of the structure, including
2979 following blocks that `belong' to it, but excluding trailing blank
2980 and comment lines. E.g., if on a `try' statement, the `try' block
2981 and all (if any) of the following `except' and `finally' blocks
2982 that belong to the `try' structure will be in the region. Ditto
2983 for if/elif/else, for/else and while/else structures, and (a bit
2984 degenerate, since they're always one-block structures) def and
2987 - Else if no prefix argument is given, and the line begins a Python
2988 block (see list above), and the block is not a `one-liner' (i.e.,
2989 the statement ends with a colon, not with code), the region will
2990 include all succeeding lines up to (but not including) the next
2991 code statement (if any) that's indented no more than the starting
2992 line, except that trailing blank and comment lines are excluded.
2993 E.g., if the starting line begins a multi-statement `def'
2994 structure, the region will be set to the full function definition,
2995 but without any trailing `noise' lines.
2997 - Else the region will include all succeeding lines up to (but not
2998 including) the next blank line, or code or indenting-comment line
2999 indented strictly less than the starting line. Trailing indenting
3000 comment lines are included in this case, but not trailing blank
3003 A msg identifying the location of the mark is displayed in the echo
3004 area; or do `\\[exchange-point-and-mark]' to flip down to the end.
3006 If called from a program, optional argument EXTEND plays the role of
3007 the prefix arg, and if optional argument JUST-MOVE is not nil, just
3008 moves to the end of the block (& does not set mark or display a msg)."
3009 (interactive "P") ; raw prefix arg
3010 (py-goto-initial-line)
3011 ;; skip over blank lines
3013 (looking-at "[ \t]*$") ; while blank line
3014 (not (eobp))) ; & somewhere to go
3017 (error "Hit end of buffer without finding a non-blank stmt"))
3018 (let ((initial-pos (point))
3019 (initial-indent (current-indentation))
3020 last-pos ; position of last stmt in region
3022 '((if elif else) (elif elif else) (else)
3023 (try except finally) (except except) (finally)
3024 (for else) (while else)
3026 first-symbol next-symbol)
3029 ;; if comment line, suck up the following comment lines
3030 ((looking-at "[ \t]*#")
3031 (re-search-forward "^[ \t]*[^ \t#]" nil 'move) ; look for non-comment
3032 (re-search-backward "^[ \t]*#") ; and back to last comment in block
3033 (setq last-pos (point)))
3035 ;; else if line is a block line and EXTEND given, suck up
3036 ;; the whole structure
3038 (setq first-symbol (py-suck-up-first-keyword) )
3039 (assq first-symbol followers))
3041 (or (py-goto-beyond-block) t) ; side effect
3042 (forward-line -1) ; side effect
3043 (setq last-pos (point)) ; side effect
3044 (py-goto-statement-below)
3045 (= (current-indentation) initial-indent)
3046 (setq next-symbol (py-suck-up-first-keyword))
3047 (memq next-symbol (cdr (assq first-symbol followers))))
3048 (setq first-symbol next-symbol)))
3050 ;; else if line *opens* a block, search for next stmt indented <=
3051 ((py-statement-opens-block-p)
3053 (setq last-pos (point)) ; always true -- side effect
3054 (py-goto-statement-below)
3055 (> (current-indentation) initial-indent)
3058 ;; else plain code line; stop at next blank line, or stmt or
3059 ;; indenting comment line indented <
3062 (setq last-pos (point)) ; always true -- side effect
3063 (or (py-goto-beyond-final-line) t)
3064 (not (looking-at "[ \t]*$")) ; stop at blank line
3066 (>= (current-indentation) initial-indent)
3067 (looking-at "[ \t]*#[^ \t\n]"))) ; ignore non-indenting #
3070 ;; skip to end of last stmt
3071 (goto-char last-pos)
3072 (py-goto-beyond-final-line)
3074 ;; set mark & display
3077 (push-mark (point) 'no-msg)
3079 (message "Mark set after: %s" (py-suck-up-leading-text))
3080 (goto-char initial-pos)
3081 (exchange-point-and-mark)
3082 (py-keep-region-active)
3085 (defun py-mark-def-or-class (&optional class)
3086 "Set region to body of def (or class, with prefix arg) enclosing point.
3087 Pushes the current mark, then point, on the mark ring (all language
3088 modes do this, but although it's handy it's never documented ...).
3090 In most Emacs language modes, this function bears at least a
3091 hallucinogenic resemblance to `\\[py-end-of-def-or-class]' and
3092 `\\[py-beginning-of-def-or-class]'.
3094 And in earlier versions of Python mode, all 3 were tightly connected.
3095 Turned out that was more confusing than useful: the `goto start' and
3096 `goto end' commands are usually used to search through a file, and
3097 people expect them to act a lot like `search backward' and `search
3098 forward' string-search commands. But because Python `def' and `class'
3099 can nest to arbitrary levels, finding the smallest def containing
3100 point cannot be done via a simple backward search: the def containing
3101 point may not be the closest preceding def, or even the closest
3102 preceding def that's indented less. The fancy algorithm required is
3103 appropriate for the usual uses of this `mark' command, but not for the
3106 So the def marked by this command may not be the one either of the
3107 `goto' commands find: If point is on a blank or non-indenting comment
3108 line, moves back to start of the closest preceding code statement or
3109 indenting comment line. If this is a `def' statement, that's the def
3110 we use. Else searches for the smallest enclosing `def' block and uses
3111 that. Else signals an error.
3113 When an enclosing def is found: The mark is left immediately beyond
3114 the last line of the def block. Point is left at the start of the
3115 def, except that: if the def is preceded by a number of comment lines
3116 followed by (at most) one optional blank line, point is left at the
3117 start of the comments; else if the def is preceded by a blank line,
3118 point is left at its start.
3120 The intent is to mark the containing def/class and its associated
3121 documentation, to make moving and duplicating functions and classes
3123 (interactive "P") ; raw prefix arg
3124 (let ((start (point))
3125 (which (cond ((eq class 'either) "\\(class\\|def\\)")
3129 (if (not (py-go-up-tree-to-keyword which))
3130 (progn (goto-char start)
3131 (error "Enclosing %s not found"
3132 (if (eq class 'either)
3135 ;; else enclosing def/class found
3136 (setq start (point))
3137 (py-goto-beyond-block)
3140 (if (zerop (forward-line -1)) ; if there is a preceding line
3142 (if (looking-at "[ \t]*$") ; it's blank
3143 (setq start (point)) ; so reset start point
3144 (goto-char start)) ; else try again
3145 (if (zerop (forward-line -1))
3146 (if (looking-at "[ \t]*#") ; a comment
3147 ;; look back for non-comment line
3148 ;; tricky: note that the regexp matches a blank
3149 ;; line, cuz \n is in the 2nd character class
3151 (re-search-backward "^[ \t]*[^ \t#]" nil 'move)
3153 ;; no comment, so go back
3154 (goto-char start)))))))
3155 (exchange-point-and-mark)
3156 (py-keep-region-active))
3158 ;; ripped from cc-mode
3159 (defun py-forward-into-nomenclature (&optional arg)
3160 "Move forward to end of a nomenclature section or word.
3161 With \\[universal-argument] (programmatically, optional argument ARG),
3162 do it that many times.
3164 A `nomenclature' is a fancy way of saying AWordWithMixedCaseNotUnderscores."
3166 (let ((case-fold-search nil))
3169 "\\(\\W\\|[_]\\)*\\([A-Z]*[a-z0-9]*\\)"
3171 (while (and (< arg 0)
3173 "\\(\\W\\|[a-z0-9]\\)[A-Z]+\\|\\(\\W\\|[_]\\)\\w+"
3176 (setq arg (1+ arg)))))
3177 (py-keep-region-active))
3179 (defun py-backward-into-nomenclature (&optional arg)
3180 "Move backward to beginning of a nomenclature section or word.
3181 With optional ARG, move that many times. If ARG is negative, move
3184 A `nomenclature' is a fancy way of saying AWordWithMixedCaseNotUnderscores."
3186 (py-forward-into-nomenclature (- arg))
3187 (py-keep-region-active))
3191 ;; pdbtrack functions
3192 (defun py-pdbtrack-toggle-stack-tracking (arg)
3194 (if (not (get-buffer-process (current-buffer)))
3195 (error "No process associated with buffer '%s'" (current-buffer)))
3196 ;; missing or 0 is toggle, >0 turn on, <0 turn off
3198 (zerop (setq arg (prefix-numeric-value arg))))
3199 (setq py-pdbtrack-do-tracking-p (not py-pdbtrack-do-tracking-p))
3200 (setq py-pdbtrack-do-tracking-p (> arg 0)))
3201 (message "%sabled Python's pdbtrack"
3202 (if py-pdbtrack-do-tracking-p "En" "Dis")))
3204 (defun turn-on-pdbtrack ()
3206 (py-pdbtrack-toggle-stack-tracking 1))
3208 (defun turn-off-pdbtrack ()
3210 (py-pdbtrack-toggle-stack-tracking 0))
3216 ;; hack for FSF Emacs
3217 (unless (fboundp 'read-shell-command)
3218 (defalias 'read-shell-command 'read-string))
3220 (defun py-pychecker-run (command)
3221 "*Run pychecker (default on the file currently visited)."
3224 (format "%s %s %s" py-pychecker-command
3225 (mapconcat 'identity py-pychecker-command-args " ")
3226 (buffer-file-name)))
3227 (last (when py-pychecker-history
3228 (let* ((lastcmd (car py-pychecker-history))
3229 (cmd (cdr (reverse (split-string lastcmd))))
3230 (newcmd (reverse (cons (buffer-file-name) cmd))))
3231 (mapconcat 'identity newcmd " ")))))
3234 (if (fboundp 'read-shell-command)
3235 (read-shell-command "Run pychecker like this: "
3239 'py-pychecker-history)
3240 (read-string "Run pychecker like this: "
3244 'py-pychecker-history))
3246 (save-some-buffers (not py-ask-about-save) nil)
3247 (if (fboundp 'compilation-start)
3249 (compilation-start command)
3251 (compile-internal command "No more errors")))
3255 ;; pydoc commands. The guts of this function is stolen from XEmacs's
3256 ;; symbol-near-point, but without the useless regexp-quote call on the
3257 ;; results, nor the interactive bit. Also, we've added the temporary
3258 ;; syntax table setting, which Skip originally had broken out into a
3259 ;; separate function. Note that Emacs doesn't have the original
3261 (defun py-symbol-near-point ()
3262 "Return the first textual item to the nearest point."
3263 ;; alg stolen from etag.el
3265 (with-syntax-table py-dotted-expression-syntax-table
3266 (if (or (bobp) (not (memq (char-syntax (char-before)) '(?w ?_))))
3267 (while (not (looking-at "\\sw\\|\\s_\\|\\'"))
3269 (while (looking-at "\\sw\\|\\s_")
3271 (if (re-search-backward "\\sw\\|\\s_" nil t)
3272 (progn (forward-char 1)
3273 (buffer-substring (point)
3274 (progn (forward-sexp -1)
3275 (while (looking-at "\\s'")
3280 (defun py-help-at-point ()
3281 "Get help from Python based on the symbol nearest point."
3283 (let* ((sym (py-symbol-near-point))
3284 (base (substring sym 0 (or (search "." sym :from-end t) 0)))
3286 (if (not (equal base ""))
3287 (setq cmd (concat "import " base "\n")))
3288 (setq cmd (concat "import pydoc\n"
3290 "try: pydoc.help('" sym "')\n"
3291 "except: print 'No help available on:', \"" sym "\""))
3293 (py-execute-string cmd)
3294 (set-buffer "*Python Output*")
3295 ;; BAW: Should we really be leaving the output buffer in help-mode?
3300 ;; Documentation functions
3302 ;; dump the long form of the mode blurb; does the usual doc escapes,
3303 ;; plus lines of the form ^[vc]:name$ to suck variable & command docs
3304 ;; out of the right places, along with the keys they're on & current
3306 (defun py-dump-help-string (str)
3307 (with-output-to-temp-buffer "*Help*"
3308 (let ((locals (buffer-local-variables))
3309 funckind funcname func funcdoc
3310 (start 0) mstart end
3312 (while (string-match "^%\\([vc]\\):\\(.+\\)\n" str start)
3313 (setq mstart (match-beginning 0) end (match-end 0)
3314 funckind (substring str (match-beginning 1) (match-end 1))
3315 funcname (substring str (match-beginning 2) (match-end 2))
3316 func (intern funcname))
3317 (princ (substitute-command-keys (substring str start mstart)))
3319 ((equal funckind "c") ; command
3320 (setq funcdoc (documentation func)
3323 (mapconcat 'key-description
3324 (where-is-internal func py-mode-map)
3326 ((equal funckind "v") ; variable
3327 (setq funcdoc (documentation-property func 'variable-documentation)
3328 keys (if (assq func locals)
3330 "Local/Global values: "
3331 (prin1-to-string (symbol-value func))
3333 (prin1-to-string (default-value func)))
3336 (prin1-to-string (symbol-value func))))))
3338 (error "Error in py-dump-help-string, tag `%s'" funckind)))
3339 (princ (format "\n-> %s:\t%s\t%s\n\n"
3340 (if (equal funckind "c") "Command" "Variable")
3345 (princ (substitute-command-keys (substring str start))))
3346 (print-help-return-message)))
3348 (defun py-describe-mode ()
3349 "Dump long form of Python-mode docs."
3351 (py-dump-help-string "Major mode for editing Python files.
3352 Knows about Python indentation, tokens, comments and continuation lines.
3353 Paragraphs are separated by blank lines only.
3355 Major sections below begin with the string `@'; specific function and
3356 variable docs begin with `->'.
3358 @EXECUTING PYTHON CODE
3360 \\[py-execute-import-or-reload]\timports or reloads the file in the Python interpreter
3361 \\[py-execute-buffer]\tsends the entire buffer to the Python interpreter
3362 \\[py-execute-region]\tsends the current region
3363 \\[py-execute-def-or-class]\tsends the current function or class definition
3364 \\[py-execute-string]\tsends an arbitrary string
3365 \\[py-shell]\tstarts a Python interpreter window; this will be used by
3366 \tsubsequent Python execution commands
3367 %c:py-execute-import-or-reload
3368 %c:py-execute-buffer
3369 %c:py-execute-region
3370 %c:py-execute-def-or-class
3371 %c:py-execute-string
3376 py-indent-offset\tindentation increment
3377 py-block-comment-prefix\tcomment string used by comment-region
3379 py-python-command\tshell command to invoke Python interpreter
3380 py-temp-directory\tdirectory used for temp files (if needed)
3382 py-beep-if-tab-change\tring the bell if tab-width is changed
3384 %v:py-block-comment-prefix
3385 %v:py-python-command
3386 %v:py-temp-directory
3387 %v:py-beep-if-tab-change
3391 Each physical line in the file is either a `continuation line' (the
3392 preceding line ends with a backslash that's not part of a comment, or
3393 the paren/bracket/brace nesting level at the start of the line is
3394 non-zero, or both) or an `initial line' (everything else).
3396 An initial line is in turn a `blank line' (contains nothing except
3397 possibly blanks or tabs), a `comment line' (leftmost non-blank
3398 character is `#'), or a `code line' (everything else).
3402 Although all comment lines are treated alike by Python, Python mode
3403 recognizes two kinds that act differently with respect to indentation.
3405 An `indenting comment line' is a comment line with a blank, tab or
3406 nothing after the initial `#'. The indentation commands (see below)
3407 treat these exactly as if they were code lines: a line following an
3408 indenting comment line will be indented like the comment line. All
3409 other comment lines (those with a non-whitespace character immediately
3410 following the initial `#') are `non-indenting comment lines', and
3411 their indentation is ignored by the indentation commands.
3413 Indenting comment lines are by far the usual case, and should be used
3414 whenever possible. Non-indenting comment lines are useful in cases
3417 \ta = b # a very wordy single-line comment that ends up being
3418 \t #... continued onto another line
3421 ##\t\tprint 'panic!' # old code we've `commented out'
3424 Since the `#...' and `##' comment lines have a non-whitespace
3425 character following the initial `#', Python mode ignores them when
3426 computing the proper indentation for the next line.
3428 Continuation Lines and Statements
3430 The Python-mode commands generally work on statements instead of on
3431 individual lines, where a `statement' is a comment or blank line, or a
3432 code line and all of its following continuation lines (if any)
3433 considered as a single logical unit. The commands in this mode
3434 generally (when it makes sense) automatically move to the start of the
3435 statement containing point, even if point happens to be in the middle
3436 of some continuation line.
3441 Primarily for entering new code:
3442 \t\\[indent-for-tab-command]\t indent line appropriately
3443 \t\\[py-newline-and-indent]\t insert newline, then indent
3444 \t\\[py-electric-backspace]\t reduce indentation, or delete single character
3446 Primarily for reindenting existing code:
3447 \t\\[py-guess-indent-offset]\t guess py-indent-offset from file content; change locally
3448 \t\\[universal-argument] \\[py-guess-indent-offset]\t ditto, but change globally
3450 \t\\[py-indent-region]\t reindent region to match its context
3451 \t\\[py-shift-region-left]\t shift region left by py-indent-offset
3452 \t\\[py-shift-region-right]\t shift region right by py-indent-offset
3454 Unlike most programming languages, Python uses indentation, and only
3455 indentation, to specify block structure. Hence the indentation supplied
3456 automatically by Python-mode is just an educated guess: only you know
3457 the block structure you intend, so only you can supply correct
3460 The \\[indent-for-tab-command] and \\[py-newline-and-indent] keys try to suggest plausible indentation, based on
3461 the indentation of preceding statements. E.g., assuming
3462 py-indent-offset is 4, after you enter
3463 \tif a > 0: \\[py-newline-and-indent]
3464 the cursor will be moved to the position of the `_' (_ is not a
3465 character in the file, it's just used here to indicate the location of
3469 If you then enter `c = d' \\[py-newline-and-indent], the cursor will move
3474 Python-mode cannot know whether that's what you intended, or whether
3478 was your intent. In general, Python-mode either reproduces the
3479 indentation of the (closest code or indenting-comment) preceding
3480 statement, or adds an extra py-indent-offset blanks if the preceding
3481 statement has `:' as its last significant (non-whitespace and non-
3482 comment) character. If the suggested indentation is too much, use
3483 \\[py-electric-backspace] to reduce it.
3485 Continuation lines are given extra indentation. If you don't like the
3486 suggested indentation, change it to something you do like, and Python-
3487 mode will strive to indent later lines of the statement in the same way.
3489 If a line is a continuation line by virtue of being in an unclosed
3490 paren/bracket/brace structure (`list', for short), the suggested
3491 indentation depends on whether the current line contains the first item
3492 in the list. If it does, it's indented py-indent-offset columns beyond
3493 the indentation of the line containing the open bracket. If you don't
3494 like that, change it by hand. The remaining items in the list will mimic
3495 whatever indentation you give to the first item.
3497 If a line is a continuation line because the line preceding it ends with
3498 a backslash, the third and following lines of the statement inherit their
3499 indentation from the line preceding them. The indentation of the second
3500 line in the statement depends on the form of the first (base) line: if
3501 the base line is an assignment statement with anything more interesting
3502 than the backslash following the leftmost assigning `=', the second line
3503 is indented two columns beyond that `='. Else it's indented to two
3504 columns beyond the leftmost solid chunk of non-whitespace characters on
3507 Warning: indent-region should not normally be used! It calls \\[indent-for-tab-command]
3508 repeatedly, and as explained above, \\[indent-for-tab-command] can't guess the block
3509 structure you intend.
3510 %c:indent-for-tab-command
3511 %c:py-newline-and-indent
3512 %c:py-electric-backspace
3515 The next function may be handy when editing code you didn't write:
3516 %c:py-guess-indent-offset
3519 The remaining `indent' functions apply to a region of Python code. They
3520 assume the block structure (equals indentation, in Python) of the region
3521 is correct, and alter the indentation in various ways while preserving
3522 the block structure:
3524 %c:py-shift-region-left
3525 %c:py-shift-region-right
3527 @MARKING & MANIPULATING REGIONS OF CODE
3529 \\[py-mark-block]\t mark block of lines
3530 \\[py-mark-def-or-class]\t mark smallest enclosing def
3531 \\[universal-argument] \\[py-mark-def-or-class]\t mark smallest enclosing class
3532 \\[comment-region]\t comment out region of code
3533 \\[universal-argument] \\[comment-region]\t uncomment region of code
3535 %c:py-mark-def-or-class
3540 \\[py-previous-statement]\t move to statement preceding point
3541 \\[py-next-statement]\t move to statement following point
3542 \\[py-goto-block-up]\t move up to start of current block
3543 \\[py-beginning-of-def-or-class]\t move to start of def
3544 \\[universal-argument] \\[py-beginning-of-def-or-class]\t move to start of class
3545 \\[py-end-of-def-or-class]\t move to end of def
3546 \\[universal-argument] \\[py-end-of-def-or-class]\t move to end of class
3548 The first two move to one statement beyond the statement that contains
3549 point. A numeric prefix argument tells them to move that many
3550 statements instead. Blank lines, comment lines, and continuation lines
3551 do not count as `statements' for these commands. So, e.g., you can go
3552 to the first code statement in a file by entering
3553 \t\\[beginning-of-buffer]\t to move to the top of the file
3554 \t\\[py-next-statement]\t to skip over initial comments and blank lines
3555 Or do `\\[py-previous-statement]' with a huge prefix argument.
3556 %c:py-previous-statement
3557 %c:py-next-statement
3559 %c:py-beginning-of-def-or-class
3560 %c:py-end-of-def-or-class
3562 @LITTLE-KNOWN EMACS COMMANDS PARTICULARLY USEFUL IN PYTHON MODE
3564 `\\[indent-new-comment-line]' is handy for entering a multi-line comment.
3566 `\\[set-selective-display]' with a `small' prefix arg is ideally suited for viewing the
3567 overall class and def structure of a module.
3569 `\\[back-to-indentation]' moves point to a line's first non-blank character.
3571 `\\[indent-relative]' is handy for creating odd indentation.
3575 If you don't like the default value of a variable, change its value to
3576 whatever you do like by putting a `setq' line in your .emacs file.
3577 E.g., to set the indentation increment to 4, put this line in your
3579 \t(setq py-indent-offset 4)
3580 To see the value of a variable, do `\\[describe-variable]' and enter the variable
3583 When entering a key sequence like `C-c C-n', it is not necessary to
3584 release the CONTROL key after doing the `C-c' part -- it suffices to
3585 press the CONTROL key, press and release `c' (while still holding down
3586 CONTROL), press and release `n' (while still holding down CONTROL), &
3587 then release CONTROL.
3589 Entering Python mode calls with no arguments the value of the variable
3590 `python-mode-hook', if that value exists and is not nil; for backward
3591 compatibility it also tries `py-mode-hook'; see the `Hooks' section of
3592 the Elisp manual for details.
3594 Obscure: When python-mode is first loaded, it looks for all bindings
3595 to newline-and-indent in the global keymap, and shadows them with
3596 local bindings to py-newline-and-indent."))
3598 (require 'info-look)
3599 ;; The info-look package does not always provide this function (it
3600 ;; appears this is the case with XEmacs 21.1)
3601 (when (fboundp 'info-lookup-maybe-add-help)
3602 (info-lookup-maybe-add-help
3604 :regexp "[a-zA-Z0-9_]+"
3605 :doc-spec '(("(python-lib)Module Index")
3606 ("(python-lib)Class-Exception-Object Index")
3607 ("(python-lib)Function-Method-Variable Index")
3608 ("(python-lib)Miscellaneous Index")))
3613 (defvar py-parse-state-re
3615 "^[ \t]*\\(elif\\|else\\|while\\|def\\|class\\)\\>"
3619 (defun py-parse-state ()
3620 "Return the parse state at point (see `parse-partial-sexp' docs)."
3622 (let ((here (point))
3625 ;; back up to the first preceding line (if any; else start of
3626 ;; buffer) that begins with a popular Python keyword, or a
3627 ;; non- whitespace and non-comment character. These are good
3628 ;; places to start parsing to see whether where we started is
3629 ;; at a non-zero nesting level. It may be slow for people who
3630 ;; write huge code blocks or huge lists ... tough beans.
3631 (re-search-backward py-parse-state-re nil 'move)
3633 ;; In XEmacs, we have a much better way to test for whether
3634 ;; we're in a triple-quoted string or not. Emacs does not
3635 ;; have this built-in function, which is its loss because
3636 ;; without scanning from the beginning of the buffer, there's
3637 ;; no accurate way to determine this otherwise.
3638 (save-excursion (setq pps (parse-partial-sexp (point) here)))
3639 ;; make sure we don't land inside a triple-quoted string
3640 (setq done (or (not (nth 3 pps))
3642 ;; Just go ahead and short circuit the test back to the
3643 ;; beginning of the buffer. This will be slow, but not
3644 ;; nearly as slow as looping through many
3645 ;; re-search-backwards.
3647 (goto-char (point-min))))
3650 (defun py-nesting-level ()
3651 "Return the buffer position of the last unclosed enclosing list.
3652 If nesting level is zero, return nil."
3653 (let ((status (py-parse-state)))
3654 (if (zerop (car status))
3656 (car (cdr status))))) ; char# of open bracket
3658 (defun py-backslash-continuation-preceding-line-p ()
3659 "Return t if preceding line ends with backslash. "
3663 ;; use a cheap test first to avoid the regexp if possible
3664 ;; use 'eq' because char-after may return nil
3665 (eq (char-after (- (point) 2)) ?\\ )
3666 ;; make sure; since eq test passed, there is a preceding line
3667 (forward-line -1) ; always true -- side effect
3668 (looking-at py-continued-re))))
3670 (defun py-continuation-line-p ()
3671 "Return t iff current line is a continuation line."
3674 (or (py-backslash-continuation-preceding-line-p)
3675 (py-nesting-level))))
3677 (defun py-goto-beginning-of-tqs (delim)
3678 "Go to the beginning of the triple quoted string we find ourselves in.
3679 DELIM is the TQS string delimiter character we're searching backwards
3681 (let ((skip (and delim (make-string 1 delim)))
3686 (py-safe (search-backward skip))
3687 (setq continue (and (not (bobp))
3688 (= (char-before) ?\\))))
3689 (if (and (= (char-before) delim)
3690 (= (char-before (1- (point))) delim))
3691 (setq skip (make-string 3 delim))))
3692 ;; we're looking at a triple-quoted string
3693 (py-safe (search-backward skip)))))
3695 (defun py-goto-initial-line ()
3696 "Go to the initial line of a simple or compound statement.
3697 If inside a compound statement, go to the line that introduces
3698 the suite, i.e. the clause header.
3700 The Python language reference:
3702 \"Compound statements consist of one or more ‘clauses.’ A clause consists
3703 of a header and a ‘suite.’ The clause headers of a particular compound
3704 statement are all at the same indentation level. Each clause header begins
3705 with a uniquely identifying keyword and ends with a colon. A suite is a
3706 group of statements controlled by a clause. A suite can be one or more
3707 semicolon-separated simple statements on the same line as the header,
3708 following the header’s colon, or it can be one or more indented statements
3709 on subsequent lines. [...]\"
3711 See: http://docs.python.org/reference/compound_stmts.html
3713 ;; Tricky: We want to avoid quadratic-time behavior for long
3714 ;; continued blocks, whether of the backslash or open-bracket
3715 ;; varieties, or a mix of the two. The following manages to do that
3716 ;; in the usual cases.
3718 ;; Also, if we're sitting inside a triple quoted string, this will
3719 ;; drop us at the line that begins the string.
3720 (let (open-bracket-pos pos)
3721 (while (py-continuation-line-p)
3723 (if (py-backslash-continuation-preceding-line-p)
3724 (while (py-backslash-continuation-preceding-line-p)
3726 ;; else zip out of nested brackets/braces/parens
3727 (while (setq open-bracket-pos (py-nesting-level))
3728 (goto-char open-bracket-pos))))
3729 (if (and (setq pos (python-in-string/comment))
3733 (py-goto-initial-line))
3736 (and (setq pos (python-in-string/comment))
3739 (py-goto-initial-line)))))
3741 (defun py-goto-beyond-final-line ()
3742 "Go to the point just beyond the final line of the current statement. "
3744 ;; Tricky: Again we need to be clever to avoid quadratic time
3747 ;; XXX: Not quite the right solution, but deals with multi-line doc
3749 (if (looking-at (concat "[ \t]*\\(" py-stringlit-re "\\)"))
3750 (goto-char (match-end 0)))
3754 (while (and (py-continuation-line-p)
3756 ;; skip over the backslash flavor
3757 (while (and (py-backslash-continuation-preceding-line-p)
3760 ;; if in nest, zip to the end of the nest
3761 (setq state (py-parse-state))
3762 (if (and (not (zerop (car state)))
3765 (parse-partial-sexp (point) (point-max) 0 nil state)
3766 (forward-line 1))))))
3768 (defun py-statement-opens-block-p ()
3769 "Return t iff the current statement opens a block.
3770 I.e., iff it ends with a colon that is not in a comment. Point should
3771 be at the start of a statement."
3773 (let ((start (point))
3774 (finish (progn (py-goto-beyond-final-line) (1- (point))))
3780 ;; look for a colon with nothing after it except whitespace, and
3782 (if (re-search-forward ":\\([ \t]\\|\\\\\n\\)*\\(#.*\\)?$"
3784 (if (eq (point) finish) ; note: no `else' clause; just
3785 ; keep searching if we're not at
3787 ;; sure looks like it opens a block -- but it might
3790 (setq searching nil) ; search is done either way
3791 (setq state (parse-partial-sexp start
3792 (match-beginning 0)))
3793 (setq answer (not (nth 4 state)))))
3794 ;; search failed: couldn't find another interesting colon
3795 (setq searching nil)))
3798 (defun py-statement-closes-block-p ()
3799 "Return t iff the current statement closes a block.
3800 I.e., if the line starts with `return', `raise', `break', `continue',
3801 and `pass'. This doesn't catch embedded statements."
3802 (let ((here (point)))
3803 (py-goto-initial-line)
3804 (back-to-indentation)
3806 (looking-at (concat py-block-closing-keywords-re "\\>"))
3809 (defun py-goto-beyond-block ()
3810 "Go to point just beyond the final line of block begun by the current line.
3811 This is the same as where `py-goto-beyond-final-line' goes unless
3812 we're on colon line, in which case we go to the end of the block.
3813 Assumes point is at the beginning of the line."
3814 (if (py-statement-opens-block-p)
3815 (py-mark-block nil 'just-move)
3816 (py-goto-beyond-final-line)))
3818 (defun py-goto-statement-at-or-above ()
3819 "Go to the start of the first statement at or preceding point.
3820 Return t if there is such a statement, otherwise nil. `Statement'
3821 does not include blank lines, comments, or continuation lines."
3822 (py-goto-initial-line)
3823 (if (looking-at py-blank-or-comment-re)
3824 ;; skip back over blank & comment lines
3825 ;; note: will skip a blank or comment line that happens to be
3826 ;; a continuation line too
3827 (if (re-search-backward "^[ \t]*[^ \t#\n]" nil t)
3828 (progn (py-goto-initial-line) t)
3832 (defun py-goto-statement-below ()
3833 "Go to start of the first statement following the statement containing point.
3834 Return t if there is such a statement, otherwise nil. "
3836 (let ((start (point)))
3837 (py-goto-beyond-final-line)
3839 (or (looking-at py-blank-or-comment-re)
3844 (progn (goto-char start) nil)
3847 (defun py-go-up-tree-to-keyword (key)
3848 "Go to begining of statement starting with KEY, at or preceding point.
3850 KEY is a regular expression describing a Python keyword. Skip blank
3851 lines and non-indenting comments. If the statement found starts with
3852 KEY, then stop, otherwise go back to first enclosing block starting
3853 with KEY. If successful, leave point at the start of the KEY line and
3854 return t. Otherwise, leave point at an undefined place and return nil."
3855 ;; skip blanks and non-indenting #
3856 (py-goto-initial-line)
3858 (looking-at "[ \t]*\\($\\|#[^ \t\n]\\)")
3859 (zerop (forward-line -1))) ; go back
3861 (py-goto-initial-line)
3862 (let* ((re (concat "[ \t]*" key "\\>"))
3863 (case-fold-search nil) ; let* so looking-at sees this
3864 (found (looking-at re))
3866 (while (not (or found dead))
3867 (condition-case nil ; in case no enclosing block
3868 (py-goto-block-up 'no-mark)
3869 (error (setq dead t)))
3870 (or dead (setq found (looking-at re))))
3874 (defun py-suck-up-leading-text ()
3875 "Return string in buffer from start of indentation to end of line.
3876 Prefix with \"...\" if leading whitespace was skipped."
3878 (back-to-indentation)
3880 (if (bolp) "" "...")
3881 (buffer-substring (point) (progn (end-of-line) (point))))))
3883 (defun py-suck-up-first-keyword ()
3884 "Return first keyword on the line as a Lisp symbol.
3885 `Keyword' is defined (essentially) as the regular expression
3886 ([a-z]+). Returns nil if none was found."
3887 (let ((case-fold-search nil))
3888 (if (looking-at "[ \t]*\\([a-z]+\\)\\>")
3889 (intern (buffer-substring (match-beginning 1) (match-end 1)))
3892 (defun py-current-defun ()
3893 "Python value for `add-log-current-defun-function'.
3894 This tells add-log.el how to find the current function/method/variable."
3897 ;; Move back to start of the current statement.
3899 (py-goto-initial-line)
3900 (back-to-indentation)
3901 (while (and (or (looking-at py-blank-or-comment-re)
3904 (backward-to-indentation 1))
3905 (py-goto-initial-line)
3911 ;; Check for an assignment. If this assignment exists inside a
3912 ;; def, it will be overwritten inside the while loop. If it
3913 ;; exists at top lever or inside a class, it will be preserved.
3915 (when (looking-at "[ \t]*\\([a-zA-Z0-9_]+\\)[ \t]*=")
3916 (setq scopes (buffer-substring (match-beginning 1) (match-end 1)))
3920 ;; Prepend the name of each outer socpe (def or class).
3923 (if (and (py-go-up-tree-to-keyword "\\(class\\|def\\)")
3925 "[ \t]*\\(class\\|def\\)[ \t]*\\([a-zA-Z0-9_]+\\)[ \t]*"))
3926 (let ((name (buffer-substring (match-beginning 2) (match-end 2))))
3927 (if (and assignment (looking-at "[ \t]*def"))
3929 (setq scopes (concat name sep scopes))
3931 (setq assignment nil)
3932 (condition-case nil ; Terminate nicely at top level.
3933 (py-goto-block-up 'no-mark)
3934 (error (setq dead t))))
3935 (if (string= scopes "")
3941 (defconst py-help-address "python-mode@python.org"
3942 "Address accepting submission of bug reports.")
3944 (defun py-version ()
3945 "Echo the current version of `python-mode' in the minibuffer."
3947 (message "Using `python-mode' version %s" py-version)
3948 (py-keep-region-active))
3950 ;; only works under Emacs 19
3952 ; (require 'reporter))
3954 (defun py-submit-bug-report (enhancement-p)
3955 "Submit via mail a bug report on `python-mode'.
3956 With \\[universal-argument] (programmatically, argument ENHANCEMENT-P
3957 non-nil) just submit an enhancement request."
3959 (list (not (y-or-n-p
3960 "Is this a bug report (hit `n' to send other comments)? "))))
3961 (let ((reporter-prompt-for-summary-p (if enhancement-p
3962 "(Very) brief summary: "
3965 (reporter-submit-bug-report
3966 py-help-address ;address
3967 (concat "python-mode " py-version) ;pkgname
3969 (if enhancement-p nil
3972 py-block-comment-prefix
3974 py-beep-if-tab-change))
3977 "Dear Barry,") ;salutation
3978 (if enhancement-p nil
3981 "Please replace this text with a sufficiently large code sample\n\
3982 and an exact recipe so that I can reproduce your problem. Failure\n\
3983 to do so may mean a greater delay in fixing your bug.\n\n")
3984 (exchange-point-and-mark)
3985 (py-keep-region-active))))
3988 (defun py-kill-emacs-hook ()
3989 "Delete files in `py-file-queue'.
3990 These are Python temporary files awaiting execution."
3991 (mapc #'(lambda (filename)
3992 (py-safe (delete-file filename)))
3995 ;; arrange to kill temp files when Emacs exists
3996 (add-hook 'kill-emacs-hook 'py-kill-emacs-hook)
3997 (add-hook 'comint-output-filter-functions 'py-pdbtrack-track-stack-file)
3999 ;; Add a designator to the minor mode strings
4000 (or (assq 'py-pdbtrack-is-tracking-p minor-mode-alist)
4001 (push '(py-pdbtrack-is-tracking-p py-pdbtrack-minor-mode-string)
4006 ;;; paragraph and string filling code from Bernhard Herzog
4007 ;;; see http://mail.python.org/pipermail/python-list/2002-May/103189.html
4009 (defun py-fill-comment (&optional justify)
4010 "Fill the comment paragraph around point"
4011 (let (;; Non-nil if the current line contains a comment.
4014 ;; If has-comment, the appropriate fill-prefix for the comment.
4015 comment-fill-prefix)
4017 ;; Figure out what kind of comment we are looking at.
4021 ;; A line with nothing but a comment on it?
4022 ((looking-at "[ \t]*#[# \t]*")
4024 comment-fill-prefix (buffer-substring (match-beginning 0)
4027 ;; A line with some code, followed by a comment? Remember that the hash
4028 ;; which starts the comment shouldn't be part of a string or character.
4030 (while (not (looking-at "#\\|$"))
4031 (skip-chars-forward "^#\n\"'\\")
4033 ((eq (char-after (point)) ?\\) (forward-char 2))
4034 ((memq (char-after (point)) '(?\" ?')) (forward-sexp 1))))
4035 (looking-at "#+[\t ]*"))
4036 (setq has-comment t)
4037 (setq comment-fill-prefix
4038 (concat (make-string (current-column) ? )
4039 (buffer-substring (match-beginning 0) (match-end 0)))))))
4041 (if (not has-comment)
4042 (fill-paragraph justify)
4044 ;; Narrow to include only the comment, and then fill the region.
4048 ;; Find the first line we should include in the region to fill.
4050 (while (and (zerop (forward-line -1))
4051 (looking-at "^[ \t]*#")))
4053 ;; We may have gone to far. Go forward again.
4054 (or (looking-at "^[ \t]*#")
4058 ;; Find the beginning of the first line past the region to fill.
4060 (while (progn (forward-line 1)
4061 (looking-at "^[ \t]*#")))
4064 ;; Lines with only hashes on them can be paragraph boundaries.
4065 (let ((paragraph-start (concat paragraph-start "\\|[ \t#]*$"))
4066 (paragraph-separate (concat paragraph-separate "\\|[ \t#]*$"))
4067 (fill-prefix comment-fill-prefix))
4068 ;;(message "paragraph-start %S paragraph-separate %S"
4069 ;;paragraph-start paragraph-separate)
4070 (fill-paragraph justify))))
4074 (defun py-fill-string (start &optional justify)
4075 "Fill the paragraph around (point) in the string starting at start"
4076 ;; basic strategy: narrow to the string and call the default
4078 (let (;; the start of the string's contents
4080 ;; the end of the string's contents
4082 ;; length of the string's delimiter
4084 ;; The string delimiter
4090 (if (looking-at "\\([urbURB]*\\(?:'''\\|\"\"\"\\|'\\|\"\\)\\)\\\\?\n?")
4091 (setq string-start (match-end 0)
4092 delim-length (- (match-end 1) (match-beginning 1))
4093 delim (buffer-substring-no-properties (match-beginning 1)
4095 (error "The parameter start is not the beginning of a python string"))
4097 ;; if the string is the first token on a line and doesn't start with
4098 ;; a newline, fill as if the string starts at the beginning of the
4099 ;; line. this helps with one line docstrings
4102 (and (/= (char-before string-start) ?\n)
4103 (looking-at (concat "[ \t]*" delim))
4104 (setq string-start (point))))
4106 ;; move until after end of string, then the end of the string's contents
4107 ;; is delim-length characters before that
4109 (setq string-end (- (point) delim-length)))
4111 ;; Narrow to the string's contents and fill the current paragraph
4113 (narrow-to-region string-start string-end)
4114 (let ((ends-with-newline (= (char-before (point-max)) ?\n)))
4115 (fill-paragraph justify)
4116 (if (and (not ends-with-newline)
4117 (= (char-before (point-max)) ?\n))
4118 ;; the default fill-paragraph implementation has inserted a
4119 ;; newline at the end. Remove it again.
4121 (goto-char (point-max))
4122 (delete-char -1)))))
4124 ;; return t to indicate that we've done our work
4127 (defun py-fill-paragraph (&optional justify)
4128 "Like \\[fill-paragraph], but handle Python comments and strings.
4129 If any of the current line is a comment, fill the comment or the
4130 paragraph of it that point is in, preserving the comment's indentation
4132 If point is inside a string, narrow to that string and fill.
4135 ;; fill-paragraph will narrow incorrectly
4138 (let* ((bod (py-point 'bod))
4139 (pps (parse-partial-sexp bod (point))))
4141 ;; are we inside a comment or on a line with only whitespace before
4142 ;; the comment start?
4144 (save-excursion (beginning-of-line) (looking-at "[ \t]*#")))
4145 (py-fill-comment justify))
4146 ;; are we inside a string?
4148 (py-fill-string (nth 8 pps)))
4149 ;; are we at the opening quote of a string, or in the indentation?
4152 (eq (py-in-literal) 'string))
4154 (py-fill-string (py-point 'boi))))
4155 ;; are we at or after the closing quote of a string?
4158 (eq (py-in-literal) 'string))
4160 (py-fill-string (py-point 'boi))))
4161 ;; otherwise: do not ever fill code
4166 (provide 'python-mode)
4167 ;;; python-mode.el ends here