1 ;;; python.el --- Python's flying circus support for Emacs
3 ;; Copyright (C) 2010, 2011 Free Software Foundation, Inc.
5 ;; Author: Fabián E. Gallina <fabian@anue.biz>
6 ;; URL: https://github.com/fgallina/python.el
10 ;; Keywords: languages
12 ;; This file is NOT part of GNU Emacs.
14 ;; python.el is free software: you can redistribute it and/or modify
15 ;; it under the terms of the GNU General Public License as published by
16 ;; the Free Software Foundation, either version 3 of the License, or
17 ;; (at your option) any later version.
19 ;; python.el is distributed in the hope that it will be useful,
20 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
21 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 ;; GNU General Public License for more details.
24 ;; You should have received a copy of the GNU General Public License
25 ;; along with python.el. If not, see <http://www.gnu.org/licenses/>.
29 ;; Major mode for editing Python files with some fontification and
30 ;; indentation bits extracted from original Dave Love's python.el
31 ;; found in GNU/Emacs.
33 ;; While it probably has less features than Dave Love's python.el and
34 ;; PSF's python-mode.el it provides the main stuff you'll need while
35 ;; keeping it simple :)
37 ;; Implements Syntax highlighting, Indentation, Movement, Shell
38 ;; interaction, Shell completion, Shell virtualenv support, Pdb
39 ;; tracking, Symbol completion, Skeletons, FFAP, Code Check, Eldoc,
42 ;; Syntax highlighting: Fontification of code is provided and supports
43 ;; python's triple quoted strings properly.
45 ;; Indentation: Automatic indentation with indentation cycling is
46 ;; provided, it allows you to navigate different available levels of
47 ;; indentation by hitting <tab> several times. Also when inserting a
48 ;; colon the `python-indent-electric-colon' command is invoked and
49 ;; causes the current line to be dedented automatically if needed.
51 ;; Movement: `beginning-of-defun' and `end-of-defun' functions are
52 ;; properly implemented. Also there are specialized
53 ;; `forward-sentence' and `backward-sentence' replacements
54 ;; (`python-nav-forward-sentence', `python-nav-backward-sentence'
55 ;; respectively). Extra functions `python-nav-sentence-start' and
56 ;; `python-nav-sentence-end' are included to move to the beginning and
57 ;; to the end of a setence while taking care of multiline definitions.
59 ;; Shell interaction: is provided and allows you easily execute any
60 ;; block of code of your current buffer in an inferior Python process.
62 ;; Shell completion: hitting tab will try to complete the current
63 ;; word. Shell completion is implemented in a manner that if you
64 ;; change the `python-shell-interpreter' to any other (for example
65 ;; IPython) it should be easy to integrate another way to calculate
66 ;; completions. You just need to specify your custom
67 ;; `python-shell-completion-setup-code' and
68 ;; `python-shell-completion-string-code'.
70 ;; Here is a complete example of the settings you would use for
74 ;; python-shell-interpreter "ipython"
75 ;; python-shell-interpreter-args ""
76 ;; python-shell-prompt-regexp "In \\[[0-9]+\\]: "
77 ;; python-shell-prompt-output-regexp "Out\\[[0-9]+\\]: "
78 ;; python-shell-completion-setup-code ""
79 ;; python-shell-completion-string-code
80 ;; "';'.join(__IP.complete('''%s'''))\n")
82 ;; Please note that the default completion system depends on the
83 ;; readline module, so if you are using some Operating System that
84 ;; bundles Python without it (like Windows) just install the
85 ;; pyreadline from http://ipython.scipy.org/moin/PyReadline/Intro and
86 ;; you should be good to go.
88 ;; Shell virtualenv support: The shell also contains support for
89 ;; virtualenvs and other special environment modifications thanks to
90 ;; `python-shell-process-environment' and `python-shell-exec-path'.
91 ;; These two variables allows you to modify execution paths and
92 ;; environment variables to make easy for you to setup virtualenv rules
93 ;; or behavior modifications when running shells. Here is an example
94 ;; of how to make shell processes to be run using the /path/to/env/
97 ;; (setq python-shell-process-environment
99 ;; (format "PATH=%s" (mapconcat
102 ;; (cons (getenv "PATH")
103 ;; '("/path/to/env/bin/")))
105 ;; "VIRTUAL_ENV=/path/to/env/"))
106 ;; (python-shell-exec-path . ("/path/to/env/bin/"))
108 ;; Since the above is cumbersome and can be programatically
109 ;; calculated, the variable `python-shell-virtualenv-path' is
110 ;; provided. When this variable is set with the path of the
111 ;; virtualenv to use, `process-environment' and `exec-path' get proper
112 ;; values in order to run shells inside the specified virtualenv. So
113 ;; the following will achieve the same as the previous example:
115 ;; (setq python-shell-virtualenv-path "/path/to/env/")
117 ;; Pdb tracking: when you execute a block of code that contains some
118 ;; call to pdb (or ipdb) it will prompt the block of code and will
119 ;; follow the execution of pdb marking the current line with an arrow.
121 ;; Symbol completion: you can complete the symbol at point. It uses
122 ;; the shell completion in background so you should run
123 ;; `python-shell-send-buffer' from time to time to get better results.
125 ;; Skeletons: 6 skeletons are provided for simple inserting of class,
126 ;; def, for, if, try and while. These skeletons are integrated with
127 ;; dabbrev. If you have `dabbrev-mode' activated and
128 ;; `python-skeleton-autoinsert' is set to t, then whenever you type
129 ;; the name of any of those defined and hit SPC, they will be
130 ;; automatically expanded.
132 ;; FFAP: You can find the filename for a given module when using ffap
133 ;; out of the box. This feature needs an inferior python shell
136 ;; Code check: Check the current file for errors with `python-check'
137 ;; using the program defined in `python-check-command'.
139 ;; Eldoc: returns documentation for object at point by using the
140 ;; inferior python subprocess to inspect its documentation. As you
141 ;; might guessed you should run `python-shell-send-buffer' from time
142 ;; to time to get better results too.
144 ;; imenu: This mode supports imenu. It builds a plain or tree menu
145 ;; depending on the value of `python-imenu-make-tree'. Also you can
146 ;; customize if menu items should include its type using
147 ;; `python-imenu-include-defun-type'.
149 ;; If you used python-mode.el you probably will miss auto-indentation
150 ;; when inserting newlines. To achieve the same behavior you have
153 ;; 1) Use GNU/Emacs' standard binding for `newline-and-indent': C-j.
155 ;; 2) Add the following hook in your .emacs:
157 ;; (add-hook 'python-mode-hook
159 ;; (define-key python-mode-map "\C-m" 'newline-and-indent)))
161 ;; I'd recommend the first one since you'll get the same behavior for
162 ;; all modes out-of-the-box.
166 ;; Add this to your .emacs:
168 ;; (add-to-list 'load-path "/folder/containing/file")
175 (require 'ansi-color)
180 ;; Avoid compiler warnings
181 (defvar view-return-to-alist)
182 (defvar compilation-error-regexp-alist)
183 (defvar outline-heading-end-regexp))
185 (autoload 'comint-mode "comint")
188 (add-to-list 'auto-mode-alist (cons (purecopy "\\.py\\'") 'python-mode))
190 (add-to-list 'interpreter-mode-alist (cons (purecopy "python") 'python-mode))
193 "Python Language's flying circus support for Emacs."
196 :link '(emacs-commentary-link "python"))
201 (defvar python-mode-map
202 (let ((map (make-sparse-keymap)))
204 (substitute-key-definition 'backward-sentence
205 'python-nav-backward-sentence
207 (substitute-key-definition 'forward-sentence
208 'python-nav-forward-sentence
211 (define-key map "\177" 'python-indent-dedent-line-backspace)
212 (define-key map (kbd "<backtab>") 'python-indent-dedent-line)
213 (define-key map "\C-c<" 'python-indent-shift-left)
214 (define-key map "\C-c>" 'python-indent-shift-right)
215 (define-key map ":" 'python-indent-electric-colon)
217 (define-key map "\C-c\C-tc" 'python-skeleton-class)
218 (define-key map "\C-c\C-td" 'python-skeleton-def)
219 (define-key map "\C-c\C-tf" 'python-skeleton-for)
220 (define-key map "\C-c\C-ti" 'python-skeleton-if)
221 (define-key map "\C-c\C-tt" 'python-skeleton-try)
222 (define-key map "\C-c\C-tw" 'python-skeleton-while)
224 (define-key map "\C-c\C-s" 'python-shell-send-string)
225 (define-key map "\C-c\C-r" 'python-shell-send-region)
226 (define-key map "\C-\M-x" 'python-shell-send-defun)
227 (define-key map "\C-c\C-c" 'python-shell-send-buffer)
228 (define-key map "\C-c\C-l" 'python-shell-send-file)
229 (define-key map "\C-c\C-z" 'python-shell-switch-to-shell)
230 ;; Some util commands
231 (define-key map "\C-c\C-v" 'python-check)
232 (define-key map "\C-c\C-f" 'python-eldoc-at-point)
234 (substitute-key-definition 'complete-symbol 'completion-at-point
236 (easy-menu-define python-menu map "Python Mode menu"
238 :help "Python-specific Features"
239 ["Shift region left" python-indent-shift-left :active mark-active
240 :help "Shift region left by a single indentation step"]
241 ["Shift region right" python-indent-shift-right :active mark-active
242 :help "Shift region right by a single indentation step"]
244 ["Mark def/class" mark-defun
245 :help "Mark outermost definition around point"]
247 ["Start of def/class" beginning-of-defun
248 :help "Go to start of outermost definition around point"]
249 ["End of def/class" end-of-defun
250 :help "Go to end of definition around point"]
254 ["Start interpreter" run-python
255 :help "Run inferior Python process in a separate buffer"]
256 ["Switch to shell" python-shell-switch-to-shell
257 :help "Switch to running inferior Python process"]
258 ["Eval string" python-shell-send-string
259 :help "Eval string in inferior Python session"]
260 ["Eval buffer" python-shell-send-buffer
261 :help "Eval buffer in inferior Python session"]
262 ["Eval region" python-shell-send-region
263 :help "Eval region in inferior Python session"]
264 ["Eval defun" python-shell-send-defun
265 :help "Eval defun in inferior Python session"]
266 ["Eval file" python-shell-send-file
267 :help "Eval file in inferior Python session"]
268 ["Debugger" pdb :help "Run pdb under GUD"]
270 ["Check file" python-check
271 :help "Check file for errors"]
272 ["Help on symbol" python-eldoc-at-point
273 :help "Get help on symbol at point"]
274 ["Complete symbol" completion-at-point
275 :help "Complete symbol before point"]))
277 "Keymap for `python-mode'.")
280 ;;; Python specialized rx
283 (defconst python-rx-constituents
285 `(block-start . ,(rx symbol-start
286 (or "def" "class" "if" "elif" "else" "try"
287 "except" "finally" "for" "while" "with")
289 `(decorator . ,(rx line-start (* space) ?@ (any letter ?_)
291 `(defun . ,(rx symbol-start (or "def" "class") symbol-end))
292 `(symbol-name . ,(rx (any letter ?_) (* (any word ?_))))
293 `(open-paren . ,(rx (or "{" "[" "(")))
294 `(close-paren . ,(rx (or "}" "]" ")")))
295 `(simple-operator . ,(rx (any ?+ ?- ?/ ?& ?^ ?~ ?| ?* ?< ?> ?= ?%)))
296 `(not-simple-operator . ,(rx (not (any ?+ ?- ?/ ?& ?^ ?~ ?| ?* ?< ?> ?= ?%))))
297 `(operator . ,(rx (or "+" "-" "/" "&" "^" "~" "|" "*" "<" ">"
298 "=" "%" "**" "//" "<<" ">>" "<=" "!="
299 "==" ">=" "is" "not")))
300 `(assignment-operator . ,(rx (or "=" "+=" "-=" "*=" "/=" "//=" "%=" "**="
301 ">>=" "<<=" "&=" "^=" "|="))))
302 "Additional Python specific sexps for `python-rx'"))
304 (defmacro python-rx (&rest regexps)
305 "Python mode specialized rx macro which supports common python named REGEXPS."
306 (let ((rx-constituents (append python-rx-constituents rx-constituents)))
307 (cond ((null regexps)
310 (rx-to-string `(and ,@regexps) t))
312 (rx-to-string (car regexps) t)))))
315 ;;; Font-lock and syntax
317 (defvar python-font-lock-keywords
320 (or "and" "del" "from" "not" "while" "as" "elif" "global" "or" "with"
321 "assert" "else" "if" "pass" "yield" "break" "except" "import"
322 "print" "class" "exec" "in" "raise" "continue" "finally" "is"
323 "return" "def" "for" "lambda" "try" "self")
326 (,(rx symbol-start "def" (1+ space) (group (1+ (or word ?_))))
327 (1 font-lock-function-name-face))
329 (,(rx symbol-start "class" (1+ space) (group (1+ (or word ?_))))
330 (1 font-lock-type-face))
333 ;; copyright, license, credits, quit, exit are added by the
334 ;; site module and since they are not intended to be used in
335 ;; programs they are not added here either.
336 (or "None" "True" "False" "Ellipsis" "__debug__" "NotImplemented")
337 symbol-end) . font-lock-constant-face)
339 (,(rx line-start (* (any " \t")) (group "@" (1+ (or word ?_))
340 (0+ "." (1+ (or word ?_)))))
341 (1 font-lock-type-face))
342 ;; Builtin Exceptions
344 (or "ArithmeticError" "AssertionError" "AttributeError"
345 "BaseException" "BufferError" "BytesWarning" "DeprecationWarning"
346 "EOFError" "EnvironmentError" "Exception" "FloatingPointError"
347 "FutureWarning" "GeneratorExit" "IOError" "ImportError"
348 "ImportWarning" "IndentationError" "IndexError" "KeyError"
349 "KeyboardInterrupt" "LookupError" "MemoryError" "NameError"
350 "NotImplementedError" "OSError" "OverflowError"
351 "PendingDeprecationWarning" "ReferenceError" "RuntimeError"
352 "RuntimeWarning" "StandardError" "StopIteration" "SyntaxError"
353 "SyntaxWarning" "SystemError" "SystemExit" "TabError" "TypeError"
354 "UnboundLocalError" "UnicodeDecodeError" "UnicodeEncodeError"
355 "UnicodeError" "UnicodeTranslateError" "UnicodeWarning"
356 "UserWarning" "ValueError" "Warning" "ZeroDivisionError")
357 symbol-end) . font-lock-type-face)
360 (or "_" "__doc__" "__import__" "__name__" "__package__" "abs" "all"
361 "any" "apply" "basestring" "bin" "bool" "buffer" "bytearray"
362 "bytes" "callable" "chr" "classmethod" "cmp" "coerce" "compile"
363 "complex" "delattr" "dict" "dir" "divmod" "enumerate" "eval"
364 "execfile" "file" "filter" "float" "format" "frozenset"
365 "getattr" "globals" "hasattr" "hash" "help" "hex" "id" "input"
366 "int" "intern" "isinstance" "issubclass" "iter" "len" "list"
367 "locals" "long" "map" "max" "min" "next" "object" "oct" "open"
368 "ord" "pow" "print" "property" "range" "raw_input" "reduce"
369 "reload" "repr" "reversed" "round" "set" "setattr" "slice"
370 "sorted" "staticmethod" "str" "sum" "super" "tuple" "type"
371 "unichr" "unicode" "vars" "xrange" "zip")
372 symbol-end) . font-lock-builtin-face)
374 ;; support for a = b = c = 5
376 (let ((re (python-rx (group (+ (any word ?. ?_)))
377 (? ?\[ (+ (not (any ?\]))) ?\]) (* space)
378 assignment-operator)))
379 (when (re-search-forward re limit t)
380 (while (and (python-info-ppss-context 'paren)
381 (re-search-forward re limit t)))
382 (if (and (not (python-info-ppss-context 'paren))
383 (not (equal (char-after (point-marker)) ?=)))
385 (set-match-data nil)))))
386 (1 font-lock-variable-name-face nil nil))
387 ;; support for a, b, c = (1, 2, 3)
389 (let ((re (python-rx (group (+ (any word ?. ?_))) (* space)
390 (* ?, (* space) (+ (any word ?. ?_)) (* space))
391 ?, (* space) (+ (any word ?. ?_)) (* space)
392 assignment-operator)))
393 (when (and (re-search-forward re limit t)
394 (goto-char (nth 3 (match-data))))
395 (while (and (python-info-ppss-context 'paren)
396 (re-search-forward re limit t))
397 (goto-char (nth 3 (match-data))))
398 (if (not (python-info-ppss-context 'paren))
400 (set-match-data nil)))))
401 (1 font-lock-variable-name-face nil nil))))
403 (defconst python-font-lock-syntactic-keywords
404 ;; Make outer chars of matching triple-quote sequences into generic
405 ;; string delimiters. Fixme: Is there a better way?
406 ;; First avoid a sequence preceded by an odd number of backslashes.
407 `((,(concat "\\(?:\\([RUru]\\)[Rr]?\\|^\\|[^\\]\\(?:\\\\.\\)*\\)" ;Prefix.
408 "\\(?:\\('\\)'\\('\\)\\|\\(?2:\"\\)\"\\(?3:\"\\)\\)")
409 (3 (python-quote-syntax)))))
411 (defun python-quote-syntax ()
412 "Put `syntax-table' property correctly on triple quote.
413 Used for syntactic keywords. N is the match number (1, 2 or 3)."
414 ;; Given a triple quote, we have to check the context to know
415 ;; whether this is an opening or closing triple or whether it's
416 ;; quoted anyhow, and should be ignored. (For that we need to do
417 ;; the same job as `syntax-ppss' to be correct and it seems to be OK
418 ;; to use it here despite initial worries.) We also have to sort
419 ;; out a possible prefix -- well, we don't _have_ to, but I think it
420 ;; should be treated as part of the string.
423 ;; ur"""ar""" x='"' # """
426 ;; x '"""' x """ \"""" x
428 (goto-char (match-beginning 0))
429 (let ((syntax (save-match-data (syntax-ppss))))
431 ((eq t (nth 3 syntax)) ; after unclosed fence
432 ;; Consider property for the last char if in a fenced string.
433 (goto-char (nth 8 syntax)) ; fence position
434 (skip-chars-forward "uUrR") ; skip any prefix
435 ;; Is it a matching sequence?
436 (if (eq (char-after) (char-after (match-beginning 2)))
437 (put-text-property (match-beginning 3) (match-end 3)
438 'syntax-table (string-to-syntax "|"))))
440 ;; Consider property for initial char, accounting for prefixes.
441 (put-text-property (match-beginning 1) (match-end 1)
442 'syntax-table (string-to-syntax "|")))
444 ;; Consider property for initial char, accounting for prefixes.
445 (put-text-property (match-beginning 2) (match-end 2)
446 'syntax-table (string-to-syntax "|"))))
449 (defvar python-mode-syntax-table
450 (let ((table (make-syntax-table)))
451 ;; Give punctuation syntax to ASCII that normally has symbol
452 ;; syntax or has word syntax and isn't a letter.
453 (let ((symbol (string-to-syntax "_"))
454 (sst (standard-syntax-table)))
457 (if (equal symbol (aref sst i))
458 (modify-syntax-entry i "." table)))))
459 (modify-syntax-entry ?$ "." table)
460 (modify-syntax-entry ?% "." table)
462 (modify-syntax-entry ?# "<" table)
463 (modify-syntax-entry ?\n ">" table)
464 (modify-syntax-entry ?' "\"" table)
465 (modify-syntax-entry ?` "$" table)
467 "Syntax table for Python files.")
469 (defvar python-dotty-syntax-table
470 (let ((table (make-syntax-table python-mode-syntax-table)))
471 (modify-syntax-entry ?. "w" table)
472 (modify-syntax-entry ?_ "w" table)
474 "Dotty syntax table for Python files.
475 It makes underscores and dots word constituent chars.")
480 (defcustom python-indent-offset 4
481 "Default indentation offset for Python."
486 (defcustom python-indent-guess-indent-offset t
487 "Non-nil tells Python mode to guess `python-indent-offset' value."
492 (defvar python-indent-current-level 0
493 "Current indentation level `python-indent-line-function' is using.")
495 (defvar python-indent-levels '(0)
496 "Levels of indentation available for `python-indent-line-function'.")
498 (defvar python-indent-dedenters '("else" "elif" "except" "finally")
499 "List of words that should be dedented.
500 These make `python-indent-calculate-indentation' subtract the value of
501 `python-indent-offset'.")
503 (defun python-indent-guess-indent-offset ()
504 "Guess and set `python-indent-offset' for the current buffer."
508 (goto-char (point-min))
510 (while (and (not found-block)
512 (python-rx line-start block-start) nil t))
513 (when (and (not (python-info-ppss-context 'string))
514 (not (python-info-ppss-context 'comment))
516 (goto-char (line-end-position))
517 (forward-comment -9999)
518 (eq ?: (char-before))))
519 (setq found-block t)))
520 (if (not found-block)
521 (message "Can't guess python-indent-offset, using defaults: %s"
522 python-indent-offset)
524 (goto-char (line-end-position))
525 (python-info-continuation-line-p))
529 (forward-comment 9999)
530 (let ((indent-offset (current-indentation)))
531 (when (> indent-offset 0)
532 (setq python-indent-offset indent-offset))))))))
534 (defun python-indent-context ()
535 "Get information on indentation context.
536 Context information is returned with a cons with the form:
539 Where status can be any of the following symbols:
540 * inside-paren: If point in between (), {} or []
541 * inside-string: If point is inside a string
542 * after-backslash: Previous line ends in a backslash
543 * after-beginning-of-block: Point is after beginning of block
544 * after-line: Point is after normal line
545 * no-indent: Point is at beginning of buffer or other special case
546 START is the buffer position where the sexp starts."
549 (let ((ppss (save-excursion (beginning-of-line) (syntax-ppss)))
553 ;; Beginning of buffer
555 (goto-char (line-beginning-position))
559 ((setq start (python-info-ppss-context 'paren ppss))
562 ((setq start (python-info-ppss-context 'string ppss))
565 ((setq start (when (not (or (python-info-ppss-context 'string ppss)
566 (python-info-ppss-context 'comment ppss)))
567 (let ((line-beg-pos (line-beginning-position)))
568 (when (eq ?\\ (char-before (1- line-beg-pos)))
569 (- line-beg-pos 2)))))
571 ;; After beginning of block
572 ((setq start (save-excursion
573 (let ((block-regexp (python-rx block-start))
574 (block-start-line-end ":[[:space:]]*$"))
575 (back-to-indentation)
576 (forward-comment -9999)
577 (back-to-indentation)
578 (when (or (python-info-continuation-line-p)
579 (and (not (looking-at block-regexp))
583 (line-end-position) t))))
584 (while (and (forward-line -1)
585 (python-info-continuation-line-p)
587 (back-to-indentation)
588 (when (not (looking-at block-regexp))
590 (back-to-indentation)
591 (when (and (looking-at block-regexp)
592 (or (re-search-forward
594 (line-end-position) t)
596 (goto-char (line-end-position))
597 (python-info-continuation-line-p))))
599 'after-beginning-of-block)
601 ((setq start (save-excursion
602 (back-to-indentation)
603 (forward-comment -9999)
604 (python-nav-sentence-start)
611 (defun python-indent-calculate-indentation ()
612 "Calculate correct indentation offset for the current line."
613 (let* ((indentation-context (python-indent-context))
614 (context-status (car indentation-context))
615 (context-start (cdr indentation-context)))
621 ('after-beginning-of-block
622 (goto-char context-start)
623 (+ (current-indentation) python-indent-offset))
627 (goto-char context-start)
628 (current-indentation))
630 (back-to-indentation)
631 (looking-at (regexp-opt python-indent-dedenters)))
635 (goto-char context-start)
636 (current-indentation))
638 (let* ((block-continuation
641 (python-info-block-continuation-line-p)))
642 (assignment-continuation
645 (python-info-assignment-continuation-line-p)))
648 (back-to-indentation)
649 (when (looking-at "\\.")
651 (goto-char (line-end-position))
652 (while (and (re-search-backward "\\." (line-beginning-position) t)
653 (or (python-info-ppss-context 'comment)
654 (python-info-ppss-context 'string)
655 (python-info-ppss-context 'paren))))
656 (if (and (looking-at "\\.")
657 (not (or (python-info-ppss-context 'comment)
658 (python-info-ppss-context 'string)
659 (python-info-ppss-context 'paren))))
661 (+ (current-indentation) python-indent-offset)))))
666 (goto-char block-continuation)
668 (python-rx block-start (* space))
669 (line-end-position) t)
671 (assignment-continuation
672 (goto-char assignment-continuation)
674 (python-rx simple-operator)
675 (line-end-position) t)
678 (python-rx (* space))
679 (line-end-position) t)
682 (goto-char context-start)
685 (back-to-indentation)
687 "\\(?:return\\|from\\|import\\)\s+")))
688 (current-indentation)
689 (+ (current-indentation)
691 (match-string-no-properties 0))))))))
695 (skip-syntax-forward "\s" (line-end-position))
696 (when (and (looking-at (regexp-opt '(")" "]" "}")))
697 (not (forward-char 1))
698 (not (python-info-ppss-context 'paren)))
699 (goto-char context-start)
700 (back-to-indentation)
704 (goto-char context-start)
708 (line-beginning-position)
710 (forward-comment 9999))
712 (+ (current-indentation) python-indent-offset)
713 (forward-comment 9999)
716 (back-to-indentation)
717 (looking-at (regexp-opt '(")" "]" "}"))))
721 (defun python-indent-calculate-levels ()
722 "Calculate `python-indent-levels' and reset `python-indent-current-level'."
723 (let* ((indentation (python-indent-calculate-indentation))
724 (remainder (% indentation python-indent-offset))
725 (steps (/ (- indentation remainder) python-indent-offset)))
726 (setq python-indent-levels (list 0))
727 (dotimes (step steps)
728 (push (* python-indent-offset (1+ step)) python-indent-levels))
729 (when (not (eq 0 remainder))
730 (push (+ (* python-indent-offset steps) remainder) python-indent-levels))
731 (setq python-indent-levels (nreverse python-indent-levels))
732 (setq python-indent-current-level (1- (length python-indent-levels)))))
734 (defun python-indent-toggle-levels ()
735 "Toggle `python-indent-current-level' over `python-indent-levels'."
736 (setq python-indent-current-level (1- python-indent-current-level))
737 (when (< python-indent-current-level 0)
738 (setq python-indent-current-level (1- (length python-indent-levels)))))
740 (defun python-indent-line (&optional force-toggle)
741 "Internal implementation of `python-indent-line-function'.
742 Uses the offset calculated in
743 `python-indent-calculate-indentation' and available levels
744 indicated by the variable `python-indent-levels' to set the
747 When the variable `last-command' is equal to
748 `indent-for-tab-command' or FORCE-TOGGLE is non-nil it cycles
749 levels indicated in the variable `python-indent-levels' by
750 setting the current level in the variable
751 `python-indent-current-level'.
753 When the variable `last-command' is not equal to
754 `indent-for-tab-command' and FORCE-TOGGLE is nil it calculates
755 possible indentation levels and saves it in the variable
756 `python-indent-levels'. Afterwards it sets the variable
757 `python-indent-current-level' correctly so offset is equal
758 to (`nth' `python-indent-current-level' `python-indent-levels')"
759 (if (or (and (eq this-command 'indent-for-tab-command)
760 (eq last-command this-command))
762 (if (not (equal python-indent-levels '(0)))
763 (python-indent-toggle-levels)
764 (python-indent-calculate-levels))
765 (python-indent-calculate-levels))
767 (delete-horizontal-space)
768 (indent-to (nth python-indent-current-level python-indent-levels))
771 (let ((closing-block-point (python-info-closing-block)))
772 (when closing-block-point
773 (message "Closes %s" (buffer-substring
776 (goto-char closing-block-point)
777 (line-end-position))))))))
779 (defun python-indent-line-function ()
780 "`indent-line-function' for Python mode.
781 See `python-indent-line' for details."
782 (python-indent-line))
784 (defun python-indent-dedent-line ()
785 "De-indent current line."
787 (when (and (not (or (python-info-ppss-context 'string)
788 (python-info-ppss-context 'comment)))
789 (<= (point-marker) (save-excursion
790 (back-to-indentation)
792 (> (current-column) 0))
793 (python-indent-line t)
796 (defun python-indent-dedent-line-backspace (arg)
797 "De-indent current line.
798 Argument ARG is passed to `backward-delete-char-untabify' when
799 point is not in between the indentation."
801 (when (not (python-indent-dedent-line))
802 (backward-delete-char-untabify arg)))
803 (put 'python-indent-dedent-line-backspace 'delete-selection 'supersede)
805 (defun python-indent-region (start end)
806 "Indent a python region automagically.
808 Called from a program, START and END specify the region to indent."
809 (let ((deactivate-mark nil))
812 (setq end (point-marker))
814 (or (bolp) (forward-line 1))
815 (while (< (point) end)
816 (or (and (bolp) (eolp))
819 (back-to-indentation)
820 (setq word (current-word))
824 (delete-horizontal-space)
825 (indent-to (python-indent-calculate-indentation)))))
827 (move-marker end nil))))
829 (defun python-indent-shift-left (start end &optional count)
830 "Shift lines contained in region START END by COUNT columns to the left.
831 COUNT defaults to `python-indent-offset'. If region isn't
832 active, the current line is shifted. The shifted region includes
833 the lines in which START and END lie. An error is signaled if
834 any lines in the region are indented less than COUNT columns."
837 (list (region-beginning) (region-end) current-prefix-arg)
838 (list (line-beginning-position) (line-end-position) current-prefix-arg)))
840 (setq count (prefix-numeric-value count))
841 (setq count python-indent-offset))
843 (let ((deactivate-mark nil))
846 (while (< (point) end)
847 (if (and (< (current-indentation) count)
848 (not (looking-at "[ \t]*$")))
849 (error "Can't shift all lines enough"))
851 (indent-rigidly start end (- count))))))
853 (add-to-list 'debug-ignored-errors "^Can't shift all lines enough")
855 (defun python-indent-shift-right (start end &optional count)
856 "Shift lines contained in region START END by COUNT columns to the left.
857 COUNT defaults to `python-indent-offset'. If region isn't
858 active, the current line is shifted. The shifted region includes
859 the lines in which START and END lie."
862 (list (region-beginning) (region-end) current-prefix-arg)
863 (list (line-beginning-position) (line-end-position) current-prefix-arg)))
864 (let ((deactivate-mark nil))
866 (setq count (prefix-numeric-value count))
867 (setq count python-indent-offset))
868 (indent-rigidly start end count)))
870 (defun python-indent-electric-colon (arg)
871 "Insert a colon and maybe de-indent the current line.
872 With numeric ARG, just insert that many colons. With
873 \\[universal-argument], just insert a single colon."
875 (self-insert-command (if (not (integerp arg)) 1 arg))
878 (not (equal ?: (char-after (- (point-marker) 2))))
879 (not (or (python-info-ppss-context 'string)
880 (python-info-ppss-context 'comment))))
881 (let ((indentation (current-indentation))
882 (calculated-indentation (python-indent-calculate-indentation)))
883 (when (> indentation calculated-indentation)
885 (indent-line-to calculated-indentation)
886 (when (not (python-info-closing-block))
887 (indent-line-to indentation)))))))
888 (put 'python-indent-electric-colon 'delete-selection t)
893 (defvar python-nav-beginning-of-defun-regexp
894 (python-rx line-start (* space) defun (+ space) (group symbol-name))
895 "Regular expresion matching beginning of class or function.
896 The name of the defun should be grouped so it can be retrieved
897 via `match-string'.")
899 (defun python-nav-beginning-of-defun (&optional nodecorators)
900 "Move point to `beginning-of-defun'.
901 When NODECORATORS is non-nil decorators are not included. This
902 is the main part of`python-beginning-of-defun-function'
903 implementation. Return non-nil if point is moved to the
904 `beginning-of-defun'."
905 (let ((indent-pos (save-excursion
906 (back-to-indentation)
911 (when (not nodecorators)
912 (when (save-excursion
914 (looking-at (python-rx decorator)))
915 (while (and (not (bobp))
917 (looking-at (python-rx decorator))))
918 (when (not (bobp)) (forward-line 1)))))))
919 (if (and (> (point) indent-pos)
921 (goto-char (line-beginning-position))
922 (looking-at python-nav-beginning-of-defun-regexp)))
924 (goto-char (line-beginning-position))
925 (funcall include-decorators)
927 (goto-char (line-beginning-position))
928 (when (re-search-backward python-nav-beginning-of-defun-regexp nil t)
930 (goto-char (or (python-info-ppss-context 'string) (point)))
931 (funcall include-decorators))
934 (defun python-beginning-of-defun-function (&optional arg nodecorators)
935 "Move point to the beginning of def or class.
936 With positive ARG move that number of functions forward. With
937 negative do the same but backwards. When NODECORATORS is non-nil
938 decorators are not included. Return non-nil if point is moved to the
939 `beginning-of-defun'."
940 (when (or (null arg) (= arg 0)) (setq arg 1))
942 (dotimes (i arg (python-nav-beginning-of-defun nodecorators)))
944 (dotimes (i (- arg) found)
945 (python-end-of-defun-function)
946 (forward-comment 9999)
947 (goto-char (line-end-position))
950 (python-nav-beginning-of-defun nodecorators)))))))
952 (defun python-end-of-defun-function ()
953 "Move point to the end of def or class.
954 Returns nil if point is not in a def or class."
956 (let ((beg-defun-indent)
957 (decorator-regexp "[[:space:]]*@"))
958 (when (looking-at decorator-regexp)
959 (while (and (not (eobp))
961 (looking-at decorator-regexp))))
962 (when (not (looking-at python-nav-beginning-of-defun-regexp))
963 (python-beginning-of-defun-function))
964 (setq beg-defun-indent (current-indentation))
966 (while (and (forward-line 1)
968 (or (not (current-word))
969 (> (current-indentation) beg-defun-indent))))
970 (forward-comment 9999)
971 (goto-char (line-beginning-position))))
973 (defun python-nav-sentence-start ()
974 "Move to start of current sentence."
976 (while (and (not (back-to-indentation))
981 (python-info-line-ends-backslash-p))
982 (python-info-ppss-context 'string)
983 (python-info-ppss-context 'paren))
984 (forward-line -1)))))
986 (defun python-nav-sentence-end ()
987 "Move to end of current sentence."
989 (while (and (goto-char (line-end-position))
992 (python-info-line-ends-backslash-p)
993 (python-info-ppss-context 'string)
994 (python-info-ppss-context 'paren))
997 (defun python-nav-backward-sentence (&optional arg)
998 "Move backward to start of sentence. With ARG, do it arg times.
999 See `python-nav-forward-sentence' for more information."
1001 (or arg (setq arg 1))
1002 (python-nav-forward-sentence (- arg)))
1004 (defun python-nav-forward-sentence (&optional arg)
1005 "Move forward to next end of sentence. With ARG, repeat.
1006 With negative argument, move backward repeatedly to start of sentence."
1008 (or arg (setq arg 1))
1010 (forward-comment 9999)
1011 (python-nav-sentence-end)
1013 (setq arg (1- arg)))
1015 (python-nav-sentence-end)
1016 (forward-comment -9999)
1017 (python-nav-sentence-start)
1019 (setq arg (1+ arg))))
1022 ;;; Shell integration
1024 (defcustom python-shell-buffer-name "Python"
1025 "Default buffer name for Python interpreter."
1030 (defcustom python-shell-interpreter "python"
1031 "Default Python interpreter for shell."
1036 (defcustom python-shell-internal-buffer-name "Python Internal"
1037 "Default buffer name for the Internal Python interpreter."
1042 (defcustom python-shell-interpreter-args "-i"
1043 "Default arguments for the Python interpreter."
1048 (defcustom python-shell-prompt-regexp ">>> "
1049 "Regular Expression matching top\-level input prompt of python shell.
1050 It should not contain a caret (^) at the beginning."
1055 (defcustom python-shell-prompt-block-regexp "[.][.][.] "
1056 "Regular Expression matching block input prompt of python shell.
1057 It should not contain a caret (^) at the beginning."
1062 (defcustom python-shell-prompt-output-regexp ""
1063 "Regular Expression matching output prompt of python shell.
1064 It should not contain a caret (^) at the beginning."
1069 (defcustom python-shell-prompt-pdb-regexp "[(<]*[Ii]?[Pp]db[>)]+ "
1070 "Regular Expression matching pdb input prompt of python shell.
1071 It should not contain a caret (^) at the beginning."
1076 (defcustom python-shell-send-setup-max-wait 5
1077 "Seconds to wait for process output before code setup.
1078 If output is received before the especified time then control is
1079 returned in that moment and not after waiting."
1084 (defcustom python-shell-process-environment nil
1085 "List of environment variables for Python shell.
1086 This variable follows the same rules as `process-environment'
1087 since it merges with it before the process creation routines are
1088 called. When this variable is nil, the Python shell is run with
1089 the default `process-environment'."
1090 :type '(repeat string)
1094 (defcustom python-shell-exec-path nil
1095 "List of path to search for binaries.
1096 This variable follows the same rules as `exec-path' since it
1097 merges with it before the process creation routines are called.
1098 When this variable is nil, the Python shell is run with the
1099 default `exec-path'."
1100 :type '(repeat string)
1104 (defcustom python-shell-virtualenv-path nil
1105 "Path to virtualenv root.
1106 This variable, when set to a string, makes the values stored in
1107 `python-shell-process-environment' and `python-shell-exec-path'
1108 to be modified properly so shells are started with the specified
1114 (defcustom python-shell-setup-codes '(python-shell-completion-setup-code
1115 python-ffap-setup-code
1116 python-eldoc-setup-code)
1117 "List of code run by `python-shell-send-setup-codes'.
1118 Each variable can contain either a simple string with the code to
1119 execute or a cons with the form (CODE . DESCRIPTION), where CODE
1120 is a string with the code to execute and DESCRIPTION is the
1122 :type '(repeat symbol)
1126 (defcustom python-shell-compilation-regexp-alist
1127 `((,(rx line-start (1+ (any " \t")) "File \""
1128 (group (1+ (not (any "\"<")))) ; avoid `<stdin>' &c
1129 "\", line " (group (1+ digit)))
1131 (,(rx " in file " (group (1+ not-newline)) " on line "
1134 (,(rx line-start "> " (group (1+ (not (any "(\"<"))))
1135 "(" (group (1+ digit)) ")" (1+ (not (any "("))) "()")
1137 "`compilation-error-regexp-alist' for inferior Python."
1138 :type '(alist string)
1141 (defun python-shell-get-process-name (dedicated)
1142 "Calculate the appropiate process name for inferior Python process.
1143 If DEDICATED is t and the variable `buffer-file-name' is non-nil
1144 returns a string with the form
1145 `python-shell-buffer-name'[variable `buffer-file-name'] else
1146 returns the value of `python-shell-buffer-name'. After
1147 calculating the process name adds the buffer name for the process
1148 in the `same-window-buffer-names' list."
1152 (format "%s[%s]" python-shell-buffer-name buffer-file-name)
1153 (format "%s" python-shell-buffer-name))))
1154 (add-to-list 'same-window-buffer-names (purecopy
1155 (format "*%s*" process-name)))
1158 (defun python-shell-internal-get-process-name ()
1159 "Calculate the appropiate process name for Internal Python process.
1160 The name is calculated from `python-shell-global-buffer-name' and
1161 a hash of all relevant global shell settings in order to ensure
1162 uniqueness for different types of configurations."
1164 python-shell-internal-buffer-name
1167 (python-shell-parse-command)
1168 (mapconcat #'symbol-value python-shell-setup-codes "")
1169 (mapconcat #'indentity python-shell-process-environment "")
1170 (or python-shell-virtualenv-path "")
1171 (mapconcat #'indentity python-shell-exec-path "")))))
1173 (defun python-shell-parse-command ()
1174 "Calculate the string used to execute the inferior Python process."
1175 (format "%s %s" python-shell-interpreter python-shell-interpreter-args))
1177 (defun python-shell-calculate-process-environment ()
1178 "Calculate process environment given `python-shell-virtualenv-path'."
1179 (let ((env (python-util-merge 'list python-shell-process-environment
1180 process-environment 'string=))
1181 (virtualenv (if python-shell-virtualenv-path
1182 (directory-file-name python-shell-virtualenv-path)
1184 (if (not virtualenv)
1186 (dolist (envvar env)
1187 (let* ((split (split-string envvar "=" t))
1188 (name (nth 0 split))
1189 (value (nth 1 split)))
1190 (when (not (string= name "PYTHONHOME"))
1191 (when (string= name "PATH")
1192 (setq value (format "%s/bin:%s" virtualenv value)))
1193 (setq env (cons (format "%s=%s" name value) env)))))
1194 (cons (format "VIRTUAL_ENV=%s" virtualenv) env))))
1196 (defun python-shell-calculate-exec-path ()
1197 "Calculate exec path given `python-shell-virtualenv-path'."
1198 (let ((path (python-util-merge 'list python-shell-exec-path
1199 exec-path 'string=)))
1200 (if (not python-shell-virtualenv-path)
1202 (cons (format "%s/bin"
1203 (directory-file-name python-shell-virtualenv-path))
1206 (defun python-comint-output-filter-function (output)
1207 "Hook run after content is put into comint buffer.
1208 OUTPUT is a string with the contents of the buffer."
1209 (ansi-color-filter-apply output))
1211 (defvar inferior-python-mode-current-file nil
1212 "Current file from which a region was sent.")
1213 (make-variable-buffer-local 'inferior-python-mode-current-file)
1215 (define-derived-mode inferior-python-mode comint-mode "Inferior Python"
1216 "Major mode for Python inferior process.
1217 Runs a Python interpreter as a subprocess of Emacs, with Python
1218 I/O through an Emacs buffer. Variables
1219 `python-shell-interpreter' and `python-shell-interpreter-args'
1220 controls which Python interpreter is run. Variables
1221 `python-shell-prompt-regexp',
1222 `python-shell-prompt-output-regexp',
1223 `python-shell-prompt-block-regexp',
1224 `python-shell-completion-setup-code',
1225 `python-shell-completion-string-code', `python-eldoc-setup-code',
1226 `python-eldoc-string-code', `python-ffap-setup-code' and
1227 `python-ffap-string-code' can customize this mode for different
1228 Python interpreters.
1230 You can also add additional setup code to be run at
1231 initialization of the interpreter via `python-shell-setup-codes'
1234 \(Type \\[describe-mode] in the process buffer for a list of commands.)"
1235 (set-syntax-table python-mode-syntax-table)
1236 (setq mode-line-process '(":%s"))
1237 (setq comint-prompt-regexp (format "^\\(?:%s\\|%s\\|%s\\)"
1238 python-shell-prompt-regexp
1239 python-shell-prompt-block-regexp
1240 python-shell-prompt-pdb-regexp))
1241 (make-local-variable 'comint-output-filter-functions)
1242 (add-hook 'comint-output-filter-functions
1243 'python-comint-output-filter-function)
1244 (add-hook 'comint-output-filter-functions
1245 'python-pdbtrack-comint-output-filter-function)
1246 (set (make-local-variable 'compilation-error-regexp-alist)
1247 python-shell-compilation-regexp-alist)
1248 (define-key inferior-python-mode-map [remap complete-symbol]
1249 'completion-at-point)
1250 (add-hook 'completion-at-point-functions
1251 'python-shell-completion-complete-at-point nil 'local)
1252 (add-to-list (make-local-variable 'comint-dynamic-complete-functions)
1253 'python-shell-completion-complete-at-point)
1254 (define-key inferior-python-mode-map (kbd "<tab>")
1255 'python-shell-completion-complete-or-indent)
1256 (compilation-shell-minor-mode 1))
1258 (defun python-shell-make-comint (cmd proc-name &optional pop)
1259 "Create a python shell comint buffer.
1260 CMD is the python command to be executed and PROC-NAME is the
1261 process name the comint buffer will get. After the comint buffer
1262 is created the `inferior-python-mode' is activated. If POP is
1263 non-nil the buffer is shown."
1265 (let* ((proc-buffer-name (format "*%s*" proc-name))
1266 (process-environment (python-shell-calculate-process-environment))
1267 (exec-path (python-shell-calculate-exec-path)))
1268 (when (not (comint-check-proc proc-buffer-name))
1269 (let* ((cmdlist (split-string-and-unquote cmd))
1270 (buffer (apply 'make-comint proc-name (car cmdlist) nil
1272 (current-buffer (current-buffer)))
1273 (with-current-buffer buffer
1274 (inferior-python-mode)
1275 (python-util-clone-local-variables current-buffer))))
1277 (pop-to-buffer proc-buffer-name))
1280 (defun run-python (dedicated cmd)
1281 "Run an inferior Python process.
1282 Input and output via buffer named after
1283 `python-shell-buffer-name'. If there is a process already
1284 running in that buffer, just switch to it.
1285 With argument, allows you to define DEDICATED, so a dedicated
1286 process for the current buffer is open, and define CMD so you can
1287 edit the command used to call the interpreter (default is value
1288 of `python-shell-interpreter' and arguments defined in
1289 `python-shell-interpreter-args'). Runs the hook
1290 `inferior-python-mode-hook' (after the `comint-mode-hook' is
1292 \(Type \\[describe-mode] in the process buffer for a list of commands.)"
1294 (if current-prefix-arg
1296 (y-or-n-p "Make dedicated process? ")
1297 (read-string "Run Python: " (python-shell-parse-command)))
1298 (list nil (python-shell-parse-command))))
1299 (python-shell-make-comint cmd (python-shell-get-process-name dedicated) t)
1302 (defun run-python-internal ()
1303 "Run an inferior Internal Python process.
1304 Input and output via buffer named after
1305 `python-shell-internal-buffer-name' and what
1306 `python-shell-internal-get-process-name' returns. This new kind
1307 of shell is intended to be used for generic communication related
1308 to defined configurations. The main difference with global or
1309 dedicated shells is that these ones are attached to a
1310 configuration, not a buffer. This means that can be used for
1311 example to retrieve the sys.path and other stuff, without messing
1312 with user shells. Runs the hook
1313 `inferior-python-mode-hook' (after the `comint-mode-hook' is
1314 run). \(Type \\[describe-mode] in the process buffer for a list
1317 (set-process-query-on-exit-flag
1319 (python-shell-make-comint
1320 (python-shell-parse-command)
1321 (python-shell-internal-get-process-name))) nil))
1323 (defun python-shell-get-process ()
1324 "Get inferior Python process for current buffer and return it."
1325 (let* ((dedicated-proc-name (python-shell-get-process-name t))
1326 (dedicated-proc-buffer-name (format "*%s*" dedicated-proc-name))
1327 (global-proc-name (python-shell-get-process-name nil))
1328 (global-proc-buffer-name (format "*%s*" global-proc-name))
1329 (dedicated-running (comint-check-proc dedicated-proc-buffer-name))
1330 (global-running (comint-check-proc global-proc-buffer-name)))
1331 ;; Always prefer dedicated
1332 (get-buffer-process (or (and dedicated-running dedicated-proc-buffer-name)
1333 (and global-running global-proc-buffer-name)))))
1335 (defun python-shell-get-or-create-process ()
1336 "Get or create an inferior Python process for current buffer and return it."
1337 (let* ((old-buffer (current-buffer))
1338 (dedicated-proc-name (python-shell-get-process-name t))
1339 (dedicated-proc-buffer-name (format "*%s*" dedicated-proc-name))
1340 (global-proc-name (python-shell-get-process-name nil))
1341 (global-proc-buffer-name (format "*%s*" global-proc-name))
1342 (dedicated-running (comint-check-proc dedicated-proc-buffer-name))
1343 (global-running (comint-check-proc global-proc-buffer-name))
1344 (current-prefix-arg 4))
1345 (when (and (not dedicated-running) (not global-running))
1346 (if (call-interactively 'run-python)
1347 (setq dedicated-running t)
1348 (setq global-running t)))
1349 ;; Always prefer dedicated
1350 (switch-to-buffer old-buffer)
1351 (get-buffer-process (if dedicated-running
1352 dedicated-proc-buffer-name
1353 global-proc-buffer-name))))
1355 (defun python-shell-internal-get-or-create-process ()
1356 "Get or create an inferior Internal Python process."
1357 (let* ((proc-name (python-shell-internal-get-process-name))
1358 (proc-buffer-name (format "*%s*" proc-name)))
1359 (run-python-internal)
1360 (get-buffer-process proc-buffer-name)))
1362 (defun python-shell-send-string (string &optional process msg)
1363 "Send STRING to inferior Python PROCESS.
1364 When MSG is non-nil messages the first line of STRING."
1365 (interactive "sPython command: ")
1366 (let ((process (or process (python-shell-get-or-create-process)))
1367 (lines (split-string string "\n" t)))
1369 (message (format "Sent: %s..." (nth 0 lines))))
1370 (if (> (length lines) 1)
1371 (let* ((temp-file-name (make-temp-file "py"))
1372 (file-name (or (buffer-file-name) temp-file-name)))
1373 (with-temp-file temp-file-name
1375 (delete-trailing-whitespace))
1376 (python-shell-send-file file-name process temp-file-name))
1377 (comint-send-string process string)
1378 (when (or (not (string-match "\n$" string))
1379 (string-match "\n[ \t].*\n?$" string))
1380 (comint-send-string process "\n")))))
1382 (defun python-shell-send-string-no-output (string &optional process msg)
1383 "Send STRING to PROCESS and inhibit output.
1384 When MSG is non-nil messages the first line of STRING. Return
1386 (let* ((output-buffer)
1387 (process (or process (python-shell-get-or-create-process)))
1388 (comint-preoutput-filter-functions
1389 (append comint-preoutput-filter-functions
1390 '(ansi-color-filter-apply
1392 (setq output-buffer (concat output-buffer string))
1394 (python-shell-send-string string process msg)
1395 (accept-process-output process)
1396 ;; Cleanup output prompt regexp
1397 (when (and (not (string= "" output-buffer))
1398 (> (length python-shell-prompt-output-regexp) 0))
1401 (insert output-buffer)
1402 (goto-char (point-min))
1403 (forward-comment 9999)
1404 (buffer-substring-no-properties
1406 (and (looking-at python-shell-prompt-output-regexp)
1408 python-shell-prompt-output-regexp nil t 1))
1412 (lambda (string) string)
1413 (butlast (split-string output-buffer "\n")) "\n")))
1415 (defun python-shell-internal-send-string (string)
1416 "Send STRING to the Internal Python interpreter.
1417 Returns the output. See `python-shell-send-string-no-output'."
1418 (python-shell-send-string-no-output
1419 ;; Makes this function compatible with the old
1420 ;; python-send-receive. (At least for CEDET).
1421 (replace-regexp-in-string "_emacs_out +" "" string)
1422 (python-shell-internal-get-or-create-process) nil))
1424 (define-obsolete-function-alias
1425 'python-send-receive 'python-shell-internal-send-string "23.3"
1426 "Send STRING to inferior Python (if any) and return result.
1427 The result is what follows `_emacs_out' in the output.
1428 This is a no-op if `python-check-comint-prompt' returns nil.")
1430 (defun python-shell-send-region (start end)
1431 "Send the region delimited by START and END to inferior Python process."
1433 (let ((deactivate-mark nil))
1434 (python-shell-send-string (buffer-substring start end) nil t)))
1436 (defun python-shell-send-buffer ()
1437 "Send the entire buffer to inferior Python process."
1441 (python-shell-send-region (point-min) (point-max))))
1443 (defun python-shell-send-defun (arg)
1444 "Send the current defun to inferior Python process.
1445 When argument ARG is non-nil sends the innermost defun."
1448 (python-shell-send-region
1450 (or (python-beginning-of-defun-function)
1451 (progn (beginning-of-line) (point-marker))))
1453 (or (python-end-of-defun-function)
1454 (progn (end-of-line) (point-marker)))))))
1456 (defun python-shell-send-file (file-name &optional process temp-file-name)
1457 "Send FILE-NAME to inferior Python PROCESS.
1458 If TEMP-FILE-NAME is passed then that file is used for processing
1459 instead, while internally the shell will continue to use
1461 (interactive "fFile to send: ")
1462 (let* ((process (or process (python-shell-get-or-create-process)))
1463 (temp-file-name (when temp-file-name
1464 (expand-file-name temp-file-name)))
1465 (file-name (or (expand-file-name file-name) temp-file-name)))
1466 (when (not file-name)
1467 (error "If FILE-NAME is nil then TEMP-FILE-NAME must be non-nil"))
1468 (with-current-buffer (process-buffer process)
1469 (setq inferior-python-mode-current-file
1470 (convert-standard-filename file-name)))
1471 (python-shell-send-string
1473 (concat "__pyfile = open('''%s''');"
1474 "exec(compile(__pyfile.read(), '''%s''', 'exec'));"
1476 (or temp-file-name file-name) file-name)
1479 (defun python-shell-switch-to-shell ()
1480 "Switch to inferior Python process buffer."
1482 (pop-to-buffer (process-buffer (python-shell-get-or-create-process)) t))
1484 (defun python-shell-send-setup-code ()
1485 "Send all setup code for shell.
1486 This function takes the list of setup code to send from the
1487 `python-shell-setup-codes' list."
1488 (let ((msg "Sent %s")
1489 (process (get-buffer-process (current-buffer))))
1490 (accept-process-output process python-shell-send-setup-max-wait)
1491 (dolist (code python-shell-setup-codes)
1494 (setq msg (cdr code)))
1495 (message (format msg code))
1496 (python-shell-send-string-no-output
1497 (symbol-value code) process)))))
1499 (add-hook 'inferior-python-mode-hook
1500 #'python-shell-send-setup-code)
1503 ;;; Shell completion
1505 (defcustom python-shell-completion-setup-code
1509 def __COMPLETER_all_completions(text): []
1512 readline.set_completer(rlcompleter.Completer().complete)
1513 def __COMPLETER_all_completions(text):
1519 res = readline.get_completer()(text, i)
1522 completions.append(res)
1526 "Code used to setup completion in inferior Python processes."
1531 (defcustom python-shell-completion-string-code
1532 "';'.join(__COMPLETER_all_completions('''%s'''))\n"
1533 "Python code used to get a string of completions separated by semicolons."
1538 (defun python-shell-completion--get-completions (input process)
1539 "Retrieve available completions for INPUT using PROCESS."
1540 (with-current-buffer (process-buffer process)
1541 (let ((completions (python-shell-send-string-no-output
1542 (format python-shell-completion-string-code input)
1544 (when (> (length completions) 2)
1545 (split-string completions "^'\\|^\"\\|;\\|'$\\|\"$" t)))))
1547 (defun python-shell-completion--get-completion (input completions)
1548 "Get completion for INPUT using COMPLETIONS."
1549 (let ((completion (when completions
1550 (try-completion input completions))))
1551 (cond ((eq completion t)
1554 (message "Can't find completion for \"%s\"" input)
1557 ((not (string= input completion))
1560 (message "Making completion list...")
1561 (with-output-to-temp-buffer "*Python Completions*"
1562 (display-completion-list
1563 (all-completions input completions)))
1566 (defun python-shell-completion-complete-at-point ()
1567 "Perform completion at point in inferior Python process."
1569 (with-syntax-table python-dotty-syntax-table
1570 (when (and comint-last-prompt-overlay
1571 (> (point-marker) (overlay-end comint-last-prompt-overlay)))
1572 (let* ((process (get-buffer-process (current-buffer)))
1573 (input (substring-no-properties
1574 (or (comint-word (current-word)) "") nil nil)))
1575 (delete-char (- (length input)))
1577 (python-shell-completion--get-completion
1578 input (python-shell-completion--get-completions input process)))))))
1580 (defun python-shell-completion-complete-or-indent ()
1581 "Complete or indent depending on the context.
1582 If content before pointer is all whitespace indent. If not try
1585 (if (string-match "^[[:space:]]*$"
1586 (buffer-substring (comint-line-beginning-position)
1588 (indent-for-tab-command)
1589 (comint-dynamic-complete)))
1592 ;;; PDB Track integration
1594 (defcustom python-pdbtrack-stacktrace-info-regexp
1595 "> %s(\\([0-9]+\\))\\([?a-zA-Z0-9_<>]+\\)()"
1596 "Regular Expression matching stacktrace information.
1597 Used to extract the current line and module being inspected. The
1598 regexp should not start with a caret (^) and can contain a string
1599 placeholder (\%s) which is replaced with the filename beign
1600 inspected (so other files in the debugging process are not
1606 (defvar python-pdbtrack-tracking-buffers '()
1607 "Alist containing elements of form (#<buffer> . #<buffer>).
1608 The car of each element of the alist is the tracking buffer and
1609 the cdr is the tracked buffer.")
1611 (defun python-pdbtrack-get-or-add-tracking-buffers ()
1612 "Get/Add a tracked buffer for the current buffer.
1613 Internally it uses the `python-pdbtrack-tracking-buffers' alist.
1614 Returns a cons with the form:
1615 * (#<tracking buffer> . #< tracked buffer>)."
1617 (assq (current-buffer) python-pdbtrack-tracking-buffers)
1618 (let* ((file (with-current-buffer (current-buffer)
1619 inferior-python-mode-current-file))
1621 `(,(current-buffer) .
1622 ,(or (get-file-buffer file)
1623 (find-file-noselect file)))))
1624 (set-buffer (cdr tracking-buffers))
1626 (set-buffer (car tracking-buffers))
1627 (setq python-pdbtrack-tracking-buffers
1628 (cons tracking-buffers python-pdbtrack-tracking-buffers))
1631 (defun python-pdbtrack-comint-output-filter-function (output)
1632 "Move overlay arrow to current pdb line in tracked buffer.
1633 Argument OUTPUT is a string with the output from the comint process."
1634 (when (not (string= output ""))
1635 (let ((full-output (ansi-color-filter-apply
1636 (buffer-substring comint-last-input-end
1638 (if (string-match python-shell-prompt-pdb-regexp full-output)
1639 (let* ((tracking-buffers (python-pdbtrack-get-or-add-tracking-buffers))
1643 (format python-pdbtrack-stacktrace-info-regexp
1645 inferior-python-mode-current-file))
1647 (string-to-number (or (match-string-no-properties 1 full-output) ""))))
1648 (tracked-buffer-window (get-buffer-window (cdr tracking-buffers)))
1649 (tracked-buffer-line-pos))
1651 (with-current-buffer (cdr tracking-buffers)
1652 (set (make-local-variable 'overlay-arrow-string) "=>")
1653 (set (make-local-variable 'overlay-arrow-position) (make-marker))
1654 (setq tracked-buffer-line-pos (progn
1655 (goto-char (point-min))
1656 (forward-line (1- line-num))
1658 (when tracked-buffer-window
1659 (set-window-point tracked-buffer-window tracked-buffer-line-pos))
1660 (set-marker overlay-arrow-position tracked-buffer-line-pos)))
1661 (pop-to-buffer (cdr tracking-buffers))
1662 (switch-to-buffer-other-window (car tracking-buffers)))
1663 (let ((tracking-buffers (assq (current-buffer)
1664 python-pdbtrack-tracking-buffers)))
1665 (when tracking-buffers
1666 (if inferior-python-mode-current-file
1667 (with-current-buffer (cdr tracking-buffers)
1668 (set-marker overlay-arrow-position nil))
1669 (kill-buffer (cdr tracking-buffers)))
1670 (setq python-pdbtrack-tracking-buffers
1671 (assq-delete-all (current-buffer)
1672 python-pdbtrack-tracking-buffers)))))))
1676 ;;; Symbol completion
1678 (defun python-completion-complete-at-point ()
1679 "Complete current symbol at point.
1680 For this to work the best as possible you should call
1681 `python-shell-send-buffer' from time to time so context in
1682 inferior python process is updated properly."
1684 (let ((process (python-shell-get-process)))
1686 (error "Completion needs an inferior Python process running")
1687 (with-syntax-table python-dotty-syntax-table
1688 (let* ((input (substring-no-properties
1689 (or (comint-word (current-word)) "") nil nil))
1690 (completions (python-shell-completion--get-completions
1692 (delete-char (- (length input)))
1694 (python-shell-completion--get-completion
1695 input completions)))))))
1697 (add-to-list 'debug-ignored-errors "^Completion needs an inferior Python process running.")
1702 (defcustom python-fill-comment-function 'python-fill-comment
1703 "Function to fill comments.
1704 This is the function used by `python-fill-paragraph-function' to
1710 (defcustom python-fill-string-function 'python-fill-string
1711 "Function to fill strings.
1712 This is the function used by `python-fill-paragraph-function' to
1718 (defcustom python-fill-decorator-function 'python-fill-decorator
1719 "Function to fill decorators.
1720 This is the function used by `python-fill-paragraph-function' to
1726 (defcustom python-fill-paren-function 'python-fill-paren
1727 "Function to fill parens.
1728 This is the function used by `python-fill-paragraph-function' to
1734 (defun python-fill-paragraph-function (&optional justify)
1735 "`fill-paragraph-function' handling multi-line strings and possibly comments.
1736 If any of the current line is in or at the end of a multi-line string,
1737 fill the string or the paragraph of it that point is in, preserving
1738 the string's indentation.
1739 Optional argument JUSTIFY defines if the paragraph should be justified."
1742 (back-to-indentation)
1745 ((funcall python-fill-comment-function justify))
1746 ;; Strings/Docstrings
1747 ((save-excursion (skip-chars-forward "\"'uUrR")
1748 (python-info-ppss-context 'string))
1749 (funcall python-fill-string-function justify))
1751 ((equal (char-after (save-excursion
1752 (back-to-indentation)
1753 (point-marker))) ?@)
1754 (funcall python-fill-decorator-function justify))
1756 ((or (python-info-ppss-context 'paren)
1757 (looking-at (python-rx open-paren))
1759 (skip-syntax-forward "^(" (line-end-position))
1760 (looking-at (python-rx open-paren))))
1761 (funcall python-fill-paren-function justify))
1764 (defun python-fill-comment (&optional justify)
1765 "Comment fill function for `python-fill-paragraph-function'.
1766 JUSTIFY should be used (if applicable) as in `fill-paragraph'."
1767 (fill-comment-paragraph justify))
1769 (defun python-fill-string (&optional justify)
1770 "String fill function for `python-fill-paragraph-function'.
1771 JUSTIFY should be used (if applicable) as in `fill-paragraph'."
1772 (let ((marker (point-marker))
1773 (string-start-marker
1775 (skip-chars-forward "\"'uUrR")
1776 (goto-char (python-info-ppss-context 'string))
1777 (skip-chars-forward "\"'uUrR")
1779 (reg-start (line-beginning-position))
1782 (while (python-info-ppss-context 'string)
1783 (goto-char (1+ (point-marker))))
1784 (skip-chars-backward "\"'")
1786 (reg-end (line-end-position))
1787 (fill-paragraph-function))
1789 (narrow-to-region reg-start reg-end)
1791 (goto-char string-start-marker)
1792 (delete-region (point-marker) (progn
1793 (skip-syntax-forward "> ")
1795 (goto-char string-end-marker)
1796 (delete-region (point-marker) (progn
1797 (skip-syntax-backward "> ")
1801 (fill-paragraph justify))
1802 ;; If there is a newline in the docstring lets put triple
1803 ;; quote in it's own line to follow pep 8
1804 (when (save-excursion
1805 (re-search-backward "\n" string-start-marker t))
1807 (newline-and-indent))
1808 (fill-paragraph justify)))) t)
1810 (defun python-fill-decorator (&optional justify)
1811 "Decorator fill function for `python-fill-paragraph-function'.
1812 JUSTIFY should be used (if applicable) as in `fill-paragraph'."
1815 (defun python-fill-paren (&optional justify)
1816 "Paren fill function for `python-fill-paragraph-function'.
1817 JUSTIFY should be used (if applicable) as in `fill-paragraph'."
1819 (narrow-to-region (progn
1820 (while (python-info-ppss-context 'paren)
1821 (goto-char (1- (point-marker))))
1823 (line-beginning-position))
1825 (when (not (python-info-ppss-context 'paren))
1827 (when (not (python-info-ppss-context 'paren))
1828 (skip-syntax-backward "^)")))
1829 (while (python-info-ppss-context 'paren)
1830 (goto-char (1+ (point-marker))))
1832 (let ((paragraph-start "\f\\|[ \t]*$")
1833 (paragraph-separate ",")
1834 (fill-paragraph-function))
1835 (goto-char (point-min))
1836 (fill-paragraph justify))
1839 (python-indent-line)
1840 (goto-char (line-end-position)))) t)
1845 (defcustom python-skeleton-autoinsert nil
1846 "Non-nil means template skeletons will be automagically inserted.
1847 This happens when pressing \"if<SPACE>\", for example, to prompt for
1853 (defvar python-skeleton-available '()
1854 "Internal list of available skeletons.")
1856 (define-abbrev-table 'python-mode-abbrev-table ()
1857 "Abbrev table for Python mode."
1859 ;; Allow / inside abbrevs.
1860 :regexp "\\(?:^\\|[^/]\\)\\<\\([[:word:]/]+\\)\\W*"
1861 ;; Only expand in code.
1862 :enable-function (lambda ()
1864 (not (or (python-info-ppss-context 'string)
1865 (python-info-ppss-context 'comment)))
1866 python-skeleton-autoinsert)))
1868 (defmacro python-skeleton-define (name doc &rest skel)
1869 "Define a `python-mode' skeleton using NAME DOC and SKEL.
1870 The skeleton will be bound to python-skeleton-NAME and will
1871 be added to `python-mode-abbrev-table'."
1872 (let* ((name (symbol-name name))
1873 (function-name (intern (concat "python-skeleton-" name))))
1875 (define-abbrev python-mode-abbrev-table ,name "" ',function-name)
1876 (setq python-skeleton-available
1877 (cons ',function-name python-skeleton-available))
1878 (define-skeleton ,function-name
1880 (format "Insert %s statement." name))
1882 (put 'python-skeleton-define 'lisp-indent-function 2)
1884 (defmacro python-define-auxiliary-skeleton (name doc &optional &rest skel)
1885 "Define a `python-mode' auxiliary skeleton using NAME DOC and SKEL.
1886 The skeleton will be bound to python-skeleton-NAME."
1887 (let* ((name (symbol-name name))
1888 (function-name (intern (concat "python-skeleton--" name)))
1890 "Add '%s' clause? " name)))
1893 `(< ,(format "%s:" name) \n \n
1895 `(define-skeleton ,function-name
1897 (format "Auxiliary skeleton for %s statement." name))
1899 (unless (y-or-n-p ,msg)
1902 (put 'python-define-auxiliary-skeleton 'lisp-indent-function 2)
1904 (python-define-auxiliary-skeleton else nil)
1906 (python-define-auxiliary-skeleton except nil)
1908 (python-define-auxiliary-skeleton finally nil)
1910 (python-skeleton-define if nil
1914 ("other condition, %s: "
1918 '(python-skeleton--else) | ^)
1920 (python-skeleton-define while nil
1924 '(python-skeleton--else) | ^)
1926 (python-skeleton-define for nil
1930 '(python-skeleton--else) | ^)
1932 (python-skeleton-define try nil
1938 "except " str ":" \n
1941 '(python-skeleton--except)
1942 '(python-skeleton--else)
1943 '(python-skeleton--finally) | ^)
1945 (python-skeleton-define def nil
1947 "def " str " (" ("Parameter, %s: "
1948 (unless (equal ?\( (char-before)) ", ")
1950 "\"\"\"" - "\"\"\"" \n
1953 (python-skeleton-define class nil
1955 "class " str " (" ("Inheritance, %s: "
1956 (unless (equal ?\( (char-before)) ", ")
1960 "\"\"\"" - "\"\"\"" \n
1963 (defun python-skeleton-add-menu-items ()
1964 "Add menu items to Python->Skeletons menu."
1965 (let ((skeletons (sort python-skeleton-available 'string<))
1967 (dolist (skeleton skeletons)
1969 nil '("Python" "Skeletons")
1971 "Insert %s" (caddr (split-string (symbol-name skeleton) "-")))
1976 (defcustom python-ffap-setup-code
1977 "def __FFAP_get_module_path(module):
1980 path = __import__(module).__file__
1981 if path[-4:] == '.pyc' and os.path.exists(path[0:-1]):
1986 "Python code to get a module path."
1991 (defcustom python-ffap-string-code
1992 "__FFAP_get_module_path('''%s''')\n"
1993 "Python code used to get a string with the path of a module."
1998 (defun python-ffap-module-path (module)
1999 "Function for `ffap-alist' to return path for MODULE."
2001 (and (eq major-mode 'inferior-python-mode)
2002 (get-buffer-process (current-buffer)))
2003 (python-shell-get-process))))
2007 (python-shell-send-string-no-output
2008 (format python-ffap-string-code module) process)))
2010 (substring-no-properties module-file 1 -1))))))
2012 (eval-after-load "ffap"
2014 (push '(python-mode . python-ffap-module-path) ffap-alist)
2015 (push '(inferior-python-mode . python-ffap-module-path) ffap-alist)))
2020 (defcustom python-check-command
2021 "pychecker --stdlib"
2022 "Command used to check a Python file."
2027 (defvar python-check-custom-command nil
2030 (defun python-check (command)
2031 "Check a Python file (default current buffer's file).
2032 Runs COMMAND, a shell command, as if by `compile'. See
2033 `python-check-command' for the default."
2035 (list (read-string "Check command: "
2036 (or python-check-custom-command
2037 (concat python-check-command " "
2038 (shell-quote-argument
2040 (let ((name (buffer-file-name)))
2042 (file-name-nondirectory name)))
2044 (setq python-check-custom-command command)
2045 (save-some-buffers (not compilation-ask-about-save) nil)
2046 (compilation-start command))
2051 (defcustom python-eldoc-setup-code
2052 "def __PYDOC_get_help(obj):
2055 if hasattr(obj, 'startswith'):
2056 obj = eval(obj, globals())
2057 doc = inspect.getdoc(obj)
2058 if not doc and callable(obj):
2060 if inspect.isclass(obj) and hasattr(obj, '__init__'):
2061 target = obj.__init__
2067 args = inspect.formatargspec(
2068 *inspect.getargspec(target)
2071 doc = '{objtype} {name}{args}'.format(
2072 objtype=objtype, name=name, args=args
2075 doc = doc.splitlines()[0]
2082 "Python code to setup documentation retrieval."
2087 (defcustom python-eldoc-string-code
2088 "__PYDOC_get_help('''%s''')\n"
2089 "Python code used to get a string with the documentation of an object."
2094 (defun python-eldoc--get-doc-at-point (&optional force-input force-process)
2095 "Internal implementation to get documentation at point.
2096 If not FORCE-INPUT is passed then what `current-word' returns
2097 will be used. If not FORCE-PROCESS is passed what
2098 `python-shell-get-process' returns is used."
2099 (let ((process (or force-process (python-shell-get-process))))
2101 "Eldoc needs an inferior Python process running."
2102 (let* ((current-defun (python-info-current-defun))
2103 (input (or force-input
2104 (with-syntax-table python-dotty-syntax-table
2105 (if (not current-defun)
2107 (concat current-defun "." (current-word))))))
2108 (ppss (syntax-ppss))
2109 (help (when (and input
2110 (not (string= input (concat current-defun ".")))
2111 (not (or (python-info-ppss-context 'string ppss)
2112 (python-info-ppss-context 'comment ppss))))
2113 (when (string-match (concat
2114 (regexp-quote (concat current-defun "."))
2118 (goto-char (point-min))
2121 (delete-region (point-marker) (search-forward "self."))
2122 (setq input (buffer-substring (point-min) (point-max)))))
2123 (python-shell-send-string-no-output
2124 (format python-eldoc-string-code input) process))))
2125 (with-current-buffer (process-buffer process)
2126 (when comint-last-prompt-overlay
2127 (delete-region comint-last-input-end
2128 (overlay-start comint-last-prompt-overlay))))
2130 (not (string= help "\n")))
2133 (defun python-eldoc-function ()
2134 "`eldoc-documentation-function' for Python.
2135 For this to work the best as possible you should call
2136 `python-shell-send-buffer' from time to time so context in
2137 inferior python process is updated properly."
2138 (python-eldoc--get-doc-at-point))
2140 (defun python-eldoc-at-point (symbol)
2141 "Get help on SYMBOL using `help'.
2142 Interactively, prompt for symbol."
2144 (let ((symbol (with-syntax-table python-dotty-syntax-table
2146 (enable-recursive-minibuffers t))
2147 (list (read-string (if symbol
2148 (format "Describe symbol (default %s): " symbol)
2149 "Describe symbol: ")
2151 (let ((process (python-shell-get-process)))
2153 (message "Eldoc needs an inferior Python process running.")
2154 (message (python-eldoc--get-doc-at-point symbol process)))))
2159 (defcustom python-imenu-include-defun-type t
2160 "Non-nil make imenu items to include its type."
2165 (defcustom python-imenu-make-tree t
2166 "Non-nil make imenu to build a tree menu.
2167 Set to nil for speed."
2172 (defcustom python-imenu-subtree-root-label "<Jump to %s>"
2173 "Label displayed to navigate to root from a subtree.
2174 It can contain a \"%s\" which will be replaced with the root name."
2179 (defvar python-imenu-index-alist nil
2180 "Calculated index tree for imenu.")
2182 (defun python-imenu-tree-assoc (keylist tree)
2183 "Using KEYLIST traverse TREE."
2185 (python-imenu-tree-assoc (cdr keylist)
2186 (ignore-errors (assoc (car keylist) tree)))
2189 (defun python-imenu-make-element-tree (element-list full-element plain-index)
2190 "Make a tree from plain alist of module names.
2191 ELEMENT-LIST is the defun name splitted by \".\" and FULL-ELEMENT
2192 is the same thing, the difference is that FULL-ELEMENT remains
2193 untouched in all recursive calls.
2194 Argument PLAIN-INDEX is the calculated plain index used to build the tree."
2195 (when (not (python-imenu-tree-assoc full-element python-imenu-index-alist))
2197 (let* ((subelement-point (cdr (assoc
2198 (mapconcat #'identity full-element ".")
2200 (subelement-name (car element-list))
2201 (subelement-position (python-util-position
2202 subelement-name full-element))
2203 (subelement-path (when subelement-position
2206 (- (length full-element)
2207 subelement-position)))))
2208 (let ((path-ref (python-imenu-tree-assoc subelement-path
2209 python-imenu-index-alist)))
2211 (push (cons subelement-name subelement-point)
2212 python-imenu-index-alist)
2213 (when (not (listp (cdr path-ref)))
2214 ;; Modifiy root cdr to be a list
2216 (list (cons (format python-imenu-subtree-root-label
2219 (mapconcat #'identity
2220 subelement-path ".")
2222 (when (not (assoc subelement-name path-ref))
2223 (push (cons subelement-name subelement-point) (cdr path-ref))))))
2224 (python-imenu-make-element-tree (cdr element-list)
2225 full-element plain-index))))
2227 (defun python-imenu-make-tree (index)
2228 "Build the imenu alist tree from plain INDEX.
2230 The idea of this function is that given the alist:
2233 (\"Test.__init__\" . 200)
2234 (\"Test.some_method\" . 300)
2235 (\"Test.some_method.another\" . 400)
2236 (\"Test.something_else\" . 500)
2238 (\"test.reprint\" . 700)
2239 (\"test.reprint\" . 800))
2241 This tree gets built:
2243 '((\"Test\" . ((\"jump to...\" . 100)
2244 (\"__init__\" . 200)
2245 (\"some_method\" . ((\"jump to...\" . 300)
2246 (\"another\" . 400)))
2247 (\"something_else\" . 500)))
2248 (\"test\" . ((\"jump to...\" . 600)
2250 (\"reprint\" . 800))))
2252 Internally it uses `python-imenu-make-element-tree' to create all
2253 branches for each element."
2254 (setq python-imenu-index-alist nil)
2255 (mapc (lambda (element)
2256 (python-imenu-make-element-tree element element index))
2257 (mapcar (lambda (element)
2258 (split-string (car element) "\\." t)) index))
2259 python-imenu-index-alist)
2261 (defun python-imenu-create-index ()
2262 "`imenu-create-index-function' for Python."
2264 (goto-char (point-max))
2265 (while (python-beginning-of-defun-function 1 t)
2266 (let ((defun-dotted-name
2267 (python-info-current-defun python-imenu-include-defun-type)))
2268 (push (cons defun-dotted-name (point)) index)))
2269 (if python-imenu-make-tree
2270 (python-imenu-make-tree index)
2276 (defun python-info-current-defun (&optional include-type)
2277 "Return name of surrounding function with Python compatible dotty syntax.
2278 Optional argument INCLUDE-TYPE indicates to include the type of the defun.
2279 This function is compatible to be used as
2280 `add-log-current-defun-function' since it returns nil if point is
2281 not inside a defun."
2288 (goto-char (line-end-position))
2289 (forward-comment -9999)
2290 (setq min-indent (current-indentation))
2291 (while (python-beginning-of-defun-function 1 t)
2292 (when (or (< (current-indentation) min-indent)
2294 (setq first-run nil)
2295 (setq min-indent (current-indentation))
2296 (looking-at python-nav-beginning-of-defun-regexp)
2298 (if (not include-type)
2299 (match-string-no-properties 1)
2300 (mapconcat 'identity
2302 (match-string-no-properties 0)) " "))
2305 (mapconcat (lambda (string) string) names "."))))
2307 (defun python-info-closing-block ()
2308 "Return the point of the block the current line closes."
2309 (let ((closing-word (save-excursion
2310 (back-to-indentation)
2312 (indentation (current-indentation)))
2313 (when (member closing-word python-indent-dedenters)
2316 (while (and (> (current-indentation) indentation)
2318 (not (back-to-indentation))
2320 (back-to-indentation)
2322 ((not (equal indentation (current-indentation))) nil)
2323 ((string= closing-word "elif")
2324 (when (member (current-word) '("if" "elif"))
2326 ((string= closing-word "else")
2327 (when (member (current-word) '("if" "elif" "except" "for" "while"))
2329 ((string= closing-word "except")
2330 (when (member (current-word) '("try"))
2332 ((string= closing-word "finally")
2333 (when (member (current-word) '("except" "else"))
2334 (point-marker))))))))
2336 (defun python-info-line-ends-backslash-p ()
2337 "Return non-nil if current line ends with backslash."
2338 (string= (or (ignore-errors
2341 (- (line-end-position) 1))) "") "\\"))
2343 (defun python-info-continuation-line-p ()
2344 "Return non-nil if current line is continuation of another."
2345 (let ((current-ppss-context-type (python-info-ppss-context-type)))
2347 (equal (save-excursion
2348 (goto-char (line-end-position))
2349 (forward-comment 9999)
2350 (python-info-ppss-context-type))
2351 current-ppss-context-type)
2352 (or (python-info-line-ends-backslash-p)
2353 (string-match ",[[:space:]]*$" (buffer-substring
2354 (line-beginning-position)
2355 (line-end-position)))
2357 (let ((innermost-paren (progn
2358 (goto-char (line-end-position))
2359 (python-info-ppss-context 'paren))))
2360 (when (and innermost-paren
2361 (and (<= (line-beginning-position) innermost-paren)
2362 (>= (line-end-position) innermost-paren)))
2363 (goto-char innermost-paren)
2364 (looking-at (python-rx open-paren (* space) line-end)))))
2366 (back-to-indentation)
2367 (python-info-ppss-context 'paren))))))
2369 (defun python-info-block-continuation-line-p ()
2370 "Return non-nil if current line is a continuation of a block."
2372 (while (and (not (bobp))
2373 (python-info-continuation-line-p))
2376 (back-to-indentation)
2377 (when (looking-at (python-rx block-start))
2380 (defun python-info-assignment-continuation-line-p ()
2381 "Return non-nil if current line is a continuation of an assignment."
2383 (while (and (not (bobp))
2384 (python-info-continuation-line-p))
2387 (back-to-indentation)
2388 (when (and (not (looking-at (python-rx block-start)))
2390 (and (re-search-forward (python-rx not-simple-operator
2392 not-simple-operator)
2393 (line-end-position) t)
2394 (not (or (python-info-ppss-context 'string)
2395 (python-info-ppss-context 'paren)
2396 (python-info-ppss-context 'comment))))))
2399 (defun python-info-ppss-context (type &optional syntax-ppss)
2400 "Return non-nil if point is on TYPE using SYNTAX-PPSS.
2401 TYPE can be 'comment, 'string or 'paren. It returns the start
2402 character address of the specified TYPE."
2403 (let ((ppss (or syntax-ppss (syntax-ppss))))
2414 (defun python-info-ppss-context-type (&optional syntax-ppss)
2415 "Return the context type using SYNTAX-PPSS.
2416 The type returned can be 'comment, 'string or 'paren."
2417 (let ((ppss (or syntax-ppss (syntax-ppss))))
2429 ;;; Utility functions
2432 (defun python-util-merge (type list1 list2 pred)
2433 "Destructively merge lists to produce a new one.
2434 Argument TYPE is for compatibility and ignored. LIST1 and LIST2
2435 are the list to be merged. Ordering of the elements is preserved
2436 according to PRED, a `less-than' predicate on the elements."
2438 (while (and list1 list2)
2439 (if (funcall pred (car list2) (car list1))
2440 (push (pop list2) res)
2441 (push (pop list1) res)))
2442 (nconc (nreverse res) list1 list2)))
2444 (defun python-util-position (item seq)
2445 "Find the first occurrence of ITEM in SEQ.
2446 Return the index of the matching item, or nil if not found."
2447 (let ((member-result (member item seq)))
2449 (- (length seq) (length member-result)))))
2451 ;; Stolen from org-mode
2452 (defun python-util-clone-local-variables (from-buffer &optional regexp)
2453 "Clone local variables from FROM-BUFFER.
2454 Optional argument REGEXP selects variables to clone and defaults
2458 (and (symbolp (car pair))
2459 (string-match (or regexp "^python-")
2460 (symbol-name (car pair)))
2461 (set (make-local-variable (car pair))
2463 (buffer-local-variables from-buffer)))
2467 (define-derived-mode python-mode fundamental-mode "Python"
2468 "Major mode for editing Python files.
2471 Entry to this mode calls the value of `python-mode-hook'
2472 if that value is non-nil."
2473 (set (make-local-variable 'tab-width) 8)
2474 (set (make-local-variable 'indent-tabs-mode) nil)
2476 (set (make-local-variable 'comment-start) "# ")
2477 (set (make-local-variable 'comment-start-skip) "#+\\s-*")
2479 (set (make-local-variable 'parse-sexp-lookup-properties) t)
2480 (set (make-local-variable 'parse-sexp-ignore-comments) t)
2482 (set (make-local-variable 'font-lock-defaults)
2483 '(python-font-lock-keywords
2485 (font-lock-syntactic-keywords . python-font-lock-syntactic-keywords)))
2487 (set (make-local-variable 'indent-line-function) #'python-indent-line-function)
2488 (set (make-local-variable 'indent-region-function) #'python-indent-region)
2490 (set (make-local-variable 'paragraph-start) "\\s-*$")
2491 (set (make-local-variable 'fill-paragraph-function) 'python-fill-paragraph-function)
2493 (set (make-local-variable 'beginning-of-defun-function)
2494 #'python-beginning-of-defun-function)
2495 (set (make-local-variable 'end-of-defun-function)
2496 #'python-end-of-defun-function)
2498 (add-hook 'completion-at-point-functions
2499 'python-completion-complete-at-point nil 'local)
2501 (setq imenu-create-index-function #'python-imenu-create-index)
2503 (set (make-local-variable 'add-log-current-defun-function)
2504 #'python-info-current-defun)
2506 (set (make-local-variable 'skeleton-further-elements)
2508 (< '(backward-delete-char-untabify (min python-indent-offset
2510 (^ '(- (1+ (current-indentation))))))
2512 (set (make-local-variable 'eldoc-documentation-function)
2513 #'python-eldoc-function)
2515 (add-to-list 'hs-special-modes-alist
2516 `(python-mode "^\\s-*\\(?:def\\|class\\)\\>" nil "#"
2518 (python-end-of-defun-function)) nil))
2520 (set (make-local-variable 'mode-require-final-newline) t)
2522 (set (make-local-variable 'outline-regexp)
2523 (python-rx (* space) block-start))
2524 (set (make-local-variable 'outline-heading-end-regexp) ":\\s-*\n")
2525 (set (make-local-variable 'outline-level)
2527 "`outline-level' function for Python mode."
2528 (1+ (/ (current-indentation) python-indent-offset))))
2530 (python-skeleton-add-menu-items)
2532 (when python-indent-guess-indent-offset
2533 (python-indent-guess-indent-offset)))
2537 ;;; python.el ends here