Use quit-window to hide buffers temporarily displayed by xref
[emacs.git] / lisp / progmodes / python.el
blob1e8623dd90141849f8fc416a212dacf04a20729d
1 ;;; python.el --- Python's flying circus support for Emacs -*- lexical-binding: t -*-
3 ;; Copyright (C) 2003-2015 Free Software Foundation, Inc.
5 ;; Author: Fabián E. Gallina <fabian@anue.biz>
6 ;; URL: https://github.com/fgallina/python.el
7 ;; Version: 0.24.4
8 ;; Maintainer: emacs-devel@gnu.org
9 ;; Created: Jul 2010
10 ;; Keywords: languages
12 ;; This file is part of GNU Emacs.
14 ;; GNU Emacs is free software: you can redistribute it and/or modify
15 ;; it under the terms of the GNU General Public License as published
16 ;; by the Free Software Foundation, either version 3 of the License,
17 ;; or (at your option) any later version.
19 ;; GNU Emacs is distributed in the hope that it will be useful, but
20 ;; WITHOUT ANY WARRANTY; without even the implied warranty of
21 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22 ;; General Public License for more details.
24 ;; You should have received a copy of the GNU General Public License
25 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
27 ;;; Commentary:
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 ;; Implements Syntax highlighting, Indentation, Movement, Shell
34 ;; interaction, Shell completion, Shell virtualenv support, Shell
35 ;; package support, Shell syntax highlighting, Pdb tracking, Symbol
36 ;; completion, Skeletons, FFAP, Code Check, Eldoc, Imenu.
38 ;; Syntax highlighting: Fontification of code is provided and supports
39 ;; python's triple quoted strings properly.
41 ;; Indentation: Automatic indentation with indentation cycling is
42 ;; provided, it allows you to navigate different available levels of
43 ;; indentation by hitting <tab> several times. Also electric-indent-mode
44 ;; is supported such that when inserting a colon the current line is
45 ;; dedented automatically if needed.
47 ;; Movement: `beginning-of-defun' and `end-of-defun' functions are
48 ;; properly implemented. There are also specialized
49 ;; `forward-sentence' and `backward-sentence' replacements called
50 ;; `python-nav-forward-block', `python-nav-backward-block'
51 ;; respectively which navigate between beginning of blocks of code.
52 ;; Extra functions `python-nav-forward-statement',
53 ;; `python-nav-backward-statement',
54 ;; `python-nav-beginning-of-statement', `python-nav-end-of-statement',
55 ;; `python-nav-beginning-of-block', `python-nav-end-of-block' and
56 ;; `python-nav-if-name-main' are included but no bound to any key. At
57 ;; last but not least the specialized `python-nav-forward-sexp' allows
58 ;; easy navigation between code blocks. If you prefer `cc-mode'-like
59 ;; `forward-sexp' movement, setting `forward-sexp-function' to nil is
60 ;; enough, You can do that using the `python-mode-hook':
62 ;; (add-hook 'python-mode-hook
63 ;; (lambda () (setq forward-sexp-function nil)))
65 ;; Shell interaction: is provided and allows opening Python shells
66 ;; inside Emacs and executing any block of code of your current buffer
67 ;; in that inferior Python process.
69 ;; Besides that only the standard CPython (2.x and 3.x) shell and
70 ;; IPython are officially supported out of the box, the interaction
71 ;; should support any other readline based Python shells as well
72 ;; (e.g. Jython and PyPy have been reported to work). You can change
73 ;; your default interpreter and commandline arguments by setting the
74 ;; `python-shell-interpreter' and `python-shell-interpreter-args'
75 ;; variables. This example enables IPython globally:
77 ;; (setq python-shell-interpreter "ipython"
78 ;; python-shell-interpreter-args "-i")
80 ;; Using the "console" subcommand to start IPython in server-client
81 ;; mode is known to fail intermittently due a bug on IPython itself
82 ;; (see URL `http://debbugs.gnu.org/cgi/bugreport.cgi?bug=18052#27').
83 ;; There seems to be a race condition in the IPython server (A.K.A
84 ;; kernel) when code is sent while it is still initializing, sometimes
85 ;; causing the shell to get stalled. With that said, if an IPython
86 ;; kernel is already running, "console --existing" seems to work fine.
88 ;; Running IPython on Windows needs more tweaking. The way you should
89 ;; set `python-shell-interpreter' and `python-shell-interpreter-args'
90 ;; is as follows (of course you need to modify the paths according to
91 ;; your system):
93 ;; (setq python-shell-interpreter "C:\\Python27\\python.exe"
94 ;; python-shell-interpreter-args
95 ;; "-i C:\\Python27\\Scripts\\ipython-script.py")
97 ;; Missing or delayed output used to happen due to differences between
98 ;; Operating Systems' pipe buffering (e.g. CPython 3.3.4 in Windows 7.
99 ;; See URL `http://debbugs.gnu.org/cgi/bugreport.cgi?bug=17304'). To
100 ;; avoid this, the `python-shell-unbuffered' defaults to non-nil and
101 ;; controls whether `python-shell-calculate-process-environment'
102 ;; should set the "PYTHONUNBUFFERED" environment variable on startup:
103 ;; See URL `https://docs.python.org/3/using/cmdline.html#cmdoption-u'.
105 ;; The interaction relies upon having prompts for input (e.g. ">>> "
106 ;; and "... " in standard Python shell) and output (e.g. "Out[1]: " in
107 ;; IPython) detected properly. Failing that Emacs may hang but, in
108 ;; the case that happens, you can recover with \\[keyboard-quit]. To
109 ;; avoid this issue, a two-step prompt autodetection mechanism is
110 ;; provided: the first step is manual and consists of a collection of
111 ;; regular expressions matching common prompts for Python shells
112 ;; stored in `python-shell-prompt-input-regexps' and
113 ;; `python-shell-prompt-output-regexps', and dir-local friendly vars
114 ;; `python-shell-prompt-regexp', `python-shell-prompt-block-regexp',
115 ;; `python-shell-prompt-output-regexp' which are appended to the
116 ;; former automatically when a shell spawns; the second step is
117 ;; automatic and depends on the `python-shell-prompt-detect' helper
118 ;; function. See its docstring for details on global variables that
119 ;; modify its behavior.
121 ;; Shell completion: hitting tab will try to complete the current
122 ;; word. The two built-in mechanisms depend on Python's readline
123 ;; module: the "native" completion is tried first and is activated
124 ;; when `python-shell-completion-native-enable' is non-nil, the
125 ;; current `python-shell-interpreter' is not a member of the
126 ;; `python-shell-completion-native-disabled-interpreters' variable and
127 ;; `python-shell-completion-native-setup' succeeds; the "fallback" or
128 ;; "legacy" mechanism works by executing Python code in the background
129 ;; and enables auto-completion for shells that do not support
130 ;; receiving escape sequences (with some limitations, i.e. completion
131 ;; in blocks does not work). The code executed for the "fallback"
132 ;; completion can be found in `python-shell-completion-setup-code' and
133 ;; `python-shell-completion-string-code' variables. Their default
134 ;; values enable completion for both CPython and IPython, and probably
135 ;; any readline based shell (it's known to work with PyPy). If your
136 ;; Python installation lacks readline (like CPython for Windows),
137 ;; installing pyreadline (URL `http://ipython.org/pyreadline.html')
138 ;; should suffice. To troubleshoot why you are not getting any
139 ;; completions, you can try the following in your Python shell:
141 ;; >>> import readline, rlcompleter
143 ;; If you see an error, then you need to either install pyreadline or
144 ;; setup custom code that avoids that dependency.
146 ;; Shell virtualenv support: The shell also contains support for
147 ;; virtualenvs and other special environment modifications thanks to
148 ;; `python-shell-process-environment' and `python-shell-exec-path'.
149 ;; These two variables allows you to modify execution paths and
150 ;; environment variables to make easy for you to setup virtualenv rules
151 ;; or behavior modifications when running shells. Here is an example
152 ;; of how to make shell processes to be run using the /path/to/env/
153 ;; virtualenv:
155 ;; (setq python-shell-process-environment
156 ;; (list
157 ;; (format "PATH=%s" (mapconcat
158 ;; 'identity
159 ;; (reverse
160 ;; (cons (getenv "PATH")
161 ;; '("/path/to/env/bin/")))
162 ;; ":"))
163 ;; "VIRTUAL_ENV=/path/to/env/"))
164 ;; (python-shell-exec-path . ("/path/to/env/bin/"))
166 ;; Since the above is cumbersome and can be programmatically
167 ;; calculated, the variable `python-shell-virtualenv-root' is
168 ;; provided. When this variable is set with the path of the
169 ;; virtualenv to use, `process-environment' and `exec-path' get proper
170 ;; values in order to run shells inside the specified virtualenv. So
171 ;; the following will achieve the same as the previous example:
173 ;; (setq python-shell-virtualenv-root "/path/to/env/")
175 ;; Also the `python-shell-extra-pythonpaths' variable have been
176 ;; introduced as simple way of adding paths to the PYTHONPATH without
177 ;; affecting existing values.
179 ;; Shell package support: you can enable a package in the current
180 ;; shell so that relative imports work properly using the
181 ;; `python-shell-package-enable' command.
183 ;; Shell syntax highlighting: when enabled current input in shell is
184 ;; highlighted. The variable `python-shell-font-lock-enable' controls
185 ;; activation of this feature globally when shells are started.
186 ;; Activation/deactivation can be also controlled on the fly via the
187 ;; `python-shell-font-lock-toggle' command.
189 ;; Pdb tracking: when you execute a block of code that contains some
190 ;; call to pdb (or ipdb) it will prompt the block of code and will
191 ;; follow the execution of pdb marking the current line with an arrow.
193 ;; Symbol completion: you can complete the symbol at point. It uses
194 ;; the shell completion in background so you should run
195 ;; `python-shell-send-buffer' from time to time to get better results.
197 ;; Skeletons: skeletons are provided for simple inserting of things like class,
198 ;; def, for, import, if, try, and while. These skeletons are
199 ;; integrated with abbrev. If you have `abbrev-mode' activated and
200 ;; `python-skeleton-autoinsert' is set to t, then whenever you type
201 ;; the name of any of those defined and hit SPC, they will be
202 ;; automatically expanded. As an alternative you can use the defined
203 ;; skeleton commands: `python-skeleton-<foo>'.
205 ;; FFAP: You can find the filename for a given module when using ffap
206 ;; out of the box. This feature needs an inferior python shell
207 ;; running.
209 ;; Code check: Check the current file for errors with `python-check'
210 ;; using the program defined in `python-check-command'.
212 ;; Eldoc: returns documentation for object at point by using the
213 ;; inferior python subprocess to inspect its documentation. As you
214 ;; might guessed you should run `python-shell-send-buffer' from time
215 ;; to time to get better results too.
217 ;; Imenu: There are two index building functions to be used as
218 ;; `imenu-create-index-function': `python-imenu-create-index' (the
219 ;; default one, builds the alist in form of a tree) and
220 ;; `python-imenu-create-flat-index'. See also
221 ;; `python-imenu-format-item-label-function',
222 ;; `python-imenu-format-parent-item-label-function',
223 ;; `python-imenu-format-parent-item-jump-label-function' variables for
224 ;; changing the way labels are formatted in the tree version.
226 ;; If you used python-mode.el you may miss auto-indentation when
227 ;; inserting newlines. To achieve the same behavior you have two
228 ;; options:
230 ;; 1) Enable the minor-mode `electric-indent-mode' (enabled by
231 ;; default) and use RET. If this mode is disabled use
232 ;; `newline-and-indent', bound to C-j.
234 ;; 2) Add the following hook in your .emacs:
236 ;; (add-hook 'python-mode-hook
237 ;; #'(lambda ()
238 ;; (define-key python-mode-map "\C-m" 'newline-and-indent)))
240 ;; I'd recommend the first one since you'll get the same behavior for
241 ;; all modes out-of-the-box.
243 ;;; Installation:
245 ;; Add this to your .emacs:
247 ;; (add-to-list 'load-path "/folder/containing/file")
248 ;; (require 'python)
250 ;;; TODO:
252 ;;; Code:
254 (require 'ansi-color)
255 (require 'cl-lib)
256 (require 'comint)
257 (require 'json)
259 ;; Avoid compiler warnings
260 (defvar view-return-to-alist)
261 (defvar compilation-error-regexp-alist)
262 (defvar outline-heading-end-regexp)
264 (autoload 'comint-mode "comint")
265 (autoload 'help-function-arglist "help-fns")
267 ;;;###autoload
268 (add-to-list 'auto-mode-alist (cons (purecopy "\\.py\\'") 'python-mode))
269 ;;;###autoload
270 (add-to-list 'interpreter-mode-alist (cons (purecopy "python[0-9.]*") 'python-mode))
272 (defgroup python nil
273 "Python Language's flying circus support for Emacs."
274 :group 'languages
275 :version "24.3"
276 :link '(emacs-commentary-link "python"))
279 ;;; Bindings
281 (defvar python-mode-map
282 (let ((map (make-sparse-keymap)))
283 ;; Movement
284 (define-key map [remap backward-sentence] 'python-nav-backward-block)
285 (define-key map [remap forward-sentence] 'python-nav-forward-block)
286 (define-key map [remap backward-up-list] 'python-nav-backward-up-list)
287 (define-key map "\C-c\C-j" 'imenu)
288 ;; Indent specific
289 (define-key map "\177" 'python-indent-dedent-line-backspace)
290 (define-key map (kbd "<backtab>") 'python-indent-dedent-line)
291 (define-key map "\C-c<" 'python-indent-shift-left)
292 (define-key map "\C-c>" 'python-indent-shift-right)
293 ;; Skeletons
294 (define-key map "\C-c\C-tc" 'python-skeleton-class)
295 (define-key map "\C-c\C-td" 'python-skeleton-def)
296 (define-key map "\C-c\C-tf" 'python-skeleton-for)
297 (define-key map "\C-c\C-ti" 'python-skeleton-if)
298 (define-key map "\C-c\C-tm" 'python-skeleton-import)
299 (define-key map "\C-c\C-tt" 'python-skeleton-try)
300 (define-key map "\C-c\C-tw" 'python-skeleton-while)
301 ;; Shell interaction
302 (define-key map "\C-c\C-p" 'run-python)
303 (define-key map "\C-c\C-s" 'python-shell-send-string)
304 (define-key map "\C-c\C-r" 'python-shell-send-region)
305 (define-key map "\C-\M-x" 'python-shell-send-defun)
306 (define-key map "\C-c\C-c" 'python-shell-send-buffer)
307 (define-key map "\C-c\C-l" 'python-shell-send-file)
308 (define-key map "\C-c\C-z" 'python-shell-switch-to-shell)
309 ;; Some util commands
310 (define-key map "\C-c\C-v" 'python-check)
311 (define-key map "\C-c\C-f" 'python-eldoc-at-point)
312 ;; Utilities
313 (substitute-key-definition 'complete-symbol 'completion-at-point
314 map global-map)
315 (easy-menu-define python-menu map "Python Mode menu"
316 `("Python"
317 :help "Python-specific Features"
318 ["Shift region left" python-indent-shift-left :active mark-active
319 :help "Shift region left by a single indentation step"]
320 ["Shift region right" python-indent-shift-right :active mark-active
321 :help "Shift region right by a single indentation step"]
323 ["Start of def/class" beginning-of-defun
324 :help "Go to start of outermost definition around point"]
325 ["End of def/class" end-of-defun
326 :help "Go to end of definition around point"]
327 ["Mark def/class" mark-defun
328 :help "Mark outermost definition around point"]
329 ["Jump to def/class" imenu
330 :help "Jump to a class or function definition"]
331 "--"
332 ("Skeletons")
333 "---"
334 ["Start interpreter" run-python
335 :help "Run inferior Python process in a separate buffer"]
336 ["Switch to shell" python-shell-switch-to-shell
337 :help "Switch to running inferior Python process"]
338 ["Eval string" python-shell-send-string
339 :help "Eval string in inferior Python session"]
340 ["Eval buffer" python-shell-send-buffer
341 :help "Eval buffer in inferior Python session"]
342 ["Eval region" python-shell-send-region
343 :help "Eval region in inferior Python session"]
344 ["Eval defun" python-shell-send-defun
345 :help "Eval defun in inferior Python session"]
346 ["Eval file" python-shell-send-file
347 :help "Eval file in inferior Python session"]
348 ["Debugger" pdb :help "Run pdb under GUD"]
349 "----"
350 ["Check file" python-check
351 :help "Check file for errors"]
352 ["Help on symbol" python-eldoc-at-point
353 :help "Get help on symbol at point"]
354 ["Complete symbol" completion-at-point
355 :help "Complete symbol before point"]))
356 map)
357 "Keymap for `python-mode'.")
360 ;;; Python specialized rx
362 (eval-when-compile
363 (defconst python-rx-constituents
364 `((block-start . ,(rx symbol-start
365 (or "def" "class" "if" "elif" "else" "try"
366 "except" "finally" "for" "while" "with")
367 symbol-end))
368 (dedenter . ,(rx symbol-start
369 (or "elif" "else" "except" "finally")
370 symbol-end))
371 (block-ender . ,(rx symbol-start
373 "break" "continue" "pass" "raise" "return")
374 symbol-end))
375 (decorator . ,(rx line-start (* space) ?@ (any letter ?_)
376 (* (any word ?_))))
377 (defun . ,(rx symbol-start (or "def" "class") symbol-end))
378 (if-name-main . ,(rx line-start "if" (+ space) "__name__"
379 (+ space) "==" (+ space)
380 (any ?' ?\") "__main__" (any ?' ?\")
381 (* space) ?:))
382 (symbol-name . ,(rx (any letter ?_) (* (any word ?_))))
383 (open-paren . ,(rx (or "{" "[" "(")))
384 (close-paren . ,(rx (or "}" "]" ")")))
385 (simple-operator . ,(rx (any ?+ ?- ?/ ?& ?^ ?~ ?| ?* ?< ?> ?= ?%)))
386 ;; FIXME: rx should support (not simple-operator).
387 (not-simple-operator . ,(rx
388 (not
389 (any ?+ ?- ?/ ?& ?^ ?~ ?| ?* ?< ?> ?= ?%))))
390 ;; FIXME: Use regexp-opt.
391 (operator . ,(rx (or "+" "-" "/" "&" "^" "~" "|" "*" "<" ">"
392 "=" "%" "**" "//" "<<" ">>" "<=" "!="
393 "==" ">=" "is" "not")))
394 ;; FIXME: Use regexp-opt.
395 (assignment-operator . ,(rx (or "=" "+=" "-=" "*=" "/=" "//=" "%=" "**="
396 ">>=" "<<=" "&=" "^=" "|=")))
397 (string-delimiter . ,(rx (and
398 ;; Match even number of backslashes.
399 (or (not (any ?\\ ?\' ?\")) point
400 ;; Quotes might be preceded by a escaped quote.
401 (and (or (not (any ?\\)) point) ?\\
402 (* ?\\ ?\\) (any ?\' ?\")))
403 (* ?\\ ?\\)
404 ;; Match single or triple quotes of any kind.
405 (group (or "\"" "\"\"\"" "'" "'''")))))
406 (coding-cookie . ,(rx line-start ?# (* space)
408 ;; # coding=<encoding name>
409 (: "coding" (or ?: ?=) (* space) (group-n 1 (+ (or word ?-))))
410 ;; # -*- coding: <encoding name> -*-
411 (: "-*-" (* space) "coding:" (* space)
412 (group-n 1 (+ (or word ?-))) (* space) "-*-")
413 ;; # vim: set fileencoding=<encoding name> :
414 (: "vim:" (* space) "set" (+ space)
415 "fileencoding" (* space) ?= (* space)
416 (group-n 1 (+ (or word ?-))) (* space) ":")))))
417 "Additional Python specific sexps for `python-rx'")
419 (defmacro python-rx (&rest regexps)
420 "Python mode specialized rx macro.
421 This variant of `rx' supports common Python named REGEXPS."
422 (let ((rx-constituents (append python-rx-constituents rx-constituents)))
423 (cond ((null regexps)
424 (error "No regexp"))
425 ((cdr regexps)
426 (rx-to-string `(and ,@regexps) t))
428 (rx-to-string (car regexps) t))))))
431 ;;; Font-lock and syntax
433 (eval-when-compile
434 (defun python-syntax--context-compiler-macro (form type &optional syntax-ppss)
435 (pcase type
436 (`'comment
437 `(let ((ppss (or ,syntax-ppss (syntax-ppss))))
438 (and (nth 4 ppss) (nth 8 ppss))))
439 (`'string
440 `(let ((ppss (or ,syntax-ppss (syntax-ppss))))
441 (and (nth 3 ppss) (nth 8 ppss))))
442 (`'paren
443 `(nth 1 (or ,syntax-ppss (syntax-ppss))))
444 (_ form))))
446 (defun python-syntax-context (type &optional syntax-ppss)
447 "Return non-nil if point is on TYPE using SYNTAX-PPSS.
448 TYPE can be `comment', `string' or `paren'. It returns the start
449 character address of the specified TYPE."
450 (declare (compiler-macro python-syntax--context-compiler-macro))
451 (let ((ppss (or syntax-ppss (syntax-ppss))))
452 (pcase type
453 (`comment (and (nth 4 ppss) (nth 8 ppss)))
454 (`string (and (nth 3 ppss) (nth 8 ppss)))
455 (`paren (nth 1 ppss))
456 (_ nil))))
458 (defun python-syntax-context-type (&optional syntax-ppss)
459 "Return the context type using SYNTAX-PPSS.
460 The type returned can be `comment', `string' or `paren'."
461 (let ((ppss (or syntax-ppss (syntax-ppss))))
462 (cond
463 ((nth 8 ppss) (if (nth 4 ppss) 'comment 'string))
464 ((nth 1 ppss) 'paren))))
466 (defsubst python-syntax-comment-or-string-p ()
467 "Return non-nil if point is inside 'comment or 'string."
468 (nth 8 (syntax-ppss)))
470 (define-obsolete-function-alias
471 'python-info-ppss-context #'python-syntax-context "24.3")
473 (define-obsolete-function-alias
474 'python-info-ppss-context-type #'python-syntax-context-type "24.3")
476 (define-obsolete-function-alias
477 'python-info-ppss-comment-or-string-p
478 #'python-syntax-comment-or-string-p "24.3")
480 (defun python-docstring-at-p (pos)
481 "Check to see if there is a docstring at POS."
482 (save-excursion
483 (goto-char pos)
484 (if (looking-at-p "'''\\|\"\"\"")
485 (progn
486 (python-nav-backward-statement)
487 (looking-at "\\`\\|class \\|def "))
488 nil)))
490 (defun python-font-lock-syntactic-face-function (state)
491 (if (nth 3 state)
492 (if (python-docstring-at-p (nth 8 state))
493 font-lock-doc-face
494 font-lock-string-face)
495 font-lock-comment-face))
497 (defvar python-font-lock-keywords
498 ;; Keywords
499 `(,(rx symbol-start
501 "and" "del" "from" "not" "while" "as" "elif" "global" "or" "with"
502 "assert" "else" "if" "pass" "yield" "break" "except" "import" "class"
503 "in" "raise" "continue" "finally" "is" "return" "def" "for" "lambda"
504 "try"
505 ;; Python 2:
506 "print" "exec"
507 ;; Python 3:
508 ;; False, None, and True are listed as keywords on the Python 3
509 ;; documentation, but since they also qualify as constants they are
510 ;; fontified like that in order to keep font-lock consistent between
511 ;; Python versions.
512 "nonlocal"
513 ;; Extra:
514 "self")
515 symbol-end)
516 ;; functions
517 (,(rx symbol-start "def" (1+ space) (group (1+ (or word ?_))))
518 (1 font-lock-function-name-face))
519 ;; classes
520 (,(rx symbol-start "class" (1+ space) (group (1+ (or word ?_))))
521 (1 font-lock-type-face))
522 ;; Constants
523 (,(rx symbol-start
525 "Ellipsis" "False" "None" "NotImplemented" "True" "__debug__"
526 ;; copyright, license, credits, quit and exit are added by the site
527 ;; module and they are not intended to be used in programs
528 "copyright" "credits" "exit" "license" "quit")
529 symbol-end) . font-lock-constant-face)
530 ;; Decorators.
531 (,(rx line-start (* (any " \t")) (group "@" (1+ (or word ?_))
532 (0+ "." (1+ (or word ?_)))))
533 (1 font-lock-type-face))
534 ;; Builtin Exceptions
535 (,(rx symbol-start
537 "ArithmeticError" "AssertionError" "AttributeError" "BaseException"
538 "DeprecationWarning" "EOFError" "EnvironmentError" "Exception"
539 "FloatingPointError" "FutureWarning" "GeneratorExit" "IOError"
540 "ImportError" "ImportWarning" "IndexError" "KeyError"
541 "KeyboardInterrupt" "LookupError" "MemoryError" "NameError"
542 "NotImplementedError" "OSError" "OverflowError"
543 "PendingDeprecationWarning" "ReferenceError" "RuntimeError"
544 "RuntimeWarning" "StopIteration" "SyntaxError" "SyntaxWarning"
545 "SystemError" "SystemExit" "TypeError" "UnboundLocalError"
546 "UnicodeDecodeError" "UnicodeEncodeError" "UnicodeError"
547 "UnicodeTranslateError" "UnicodeWarning" "UserWarning" "VMSError"
548 "ValueError" "Warning" "WindowsError" "ZeroDivisionError"
549 ;; Python 2:
550 "StandardError"
551 ;; Python 3:
552 "BufferError" "BytesWarning" "IndentationError" "ResourceWarning"
553 "TabError")
554 symbol-end) . font-lock-type-face)
555 ;; Builtins
556 (,(rx symbol-start
558 "abs" "all" "any" "bin" "bool" "callable" "chr" "classmethod"
559 "compile" "complex" "delattr" "dict" "dir" "divmod" "enumerate"
560 "eval" "filter" "float" "format" "frozenset" "getattr" "globals"
561 "hasattr" "hash" "help" "hex" "id" "input" "int" "isinstance"
562 "issubclass" "iter" "len" "list" "locals" "map" "max" "memoryview"
563 "min" "next" "object" "oct" "open" "ord" "pow" "print" "property"
564 "range" "repr" "reversed" "round" "set" "setattr" "slice" "sorted"
565 "staticmethod" "str" "sum" "super" "tuple" "type" "vars" "zip"
566 "__import__"
567 ;; Python 2:
568 "basestring" "cmp" "execfile" "file" "long" "raw_input" "reduce"
569 "reload" "unichr" "unicode" "xrange" "apply" "buffer" "coerce"
570 "intern"
571 ;; Python 3:
572 "ascii" "bytearray" "bytes" "exec"
573 ;; Extra:
574 "__all__" "__doc__" "__name__" "__package__")
575 symbol-end) . font-lock-builtin-face)
576 ;; assignments
577 ;; support for a = b = c = 5
578 (,(lambda (limit)
579 (let ((re (python-rx (group (+ (any word ?. ?_)))
580 (? ?\[ (+ (not (any ?\]))) ?\]) (* space)
581 assignment-operator))
582 (res nil))
583 (while (and (setq res (re-search-forward re limit t))
584 (or (python-syntax-context 'paren)
585 (equal (char-after (point)) ?=))))
586 res))
587 (1 font-lock-variable-name-face nil nil))
588 ;; support for a, b, c = (1, 2, 3)
589 (,(lambda (limit)
590 (let ((re (python-rx (group (+ (any word ?. ?_))) (* space)
591 (* ?, (* space) (+ (any word ?. ?_)) (* space))
592 ?, (* space) (+ (any word ?. ?_)) (* space)
593 assignment-operator))
594 (res nil))
595 (while (and (setq res (re-search-forward re limit t))
596 (goto-char (match-end 1))
597 (python-syntax-context 'paren)))
598 res))
599 (1 font-lock-variable-name-face nil nil))))
601 (defconst python-syntax-propertize-function
602 (syntax-propertize-rules
603 ((python-rx string-delimiter)
604 (0 (ignore (python-syntax-stringify))))))
606 (defsubst python-syntax-count-quotes (quote-char &optional point limit)
607 "Count number of quotes around point (max is 3).
608 QUOTE-CHAR is the quote char to count. Optional argument POINT is
609 the point where scan starts (defaults to current point), and LIMIT
610 is used to limit the scan."
611 (let ((i 0))
612 (while (and (< i 3)
613 (or (not limit) (< (+ point i) limit))
614 (eq (char-after (+ point i)) quote-char))
615 (setq i (1+ i)))
618 (defun python-syntax-stringify ()
619 "Put `syntax-table' property correctly on single/triple quotes."
620 (let* ((num-quotes (length (match-string-no-properties 1)))
621 (ppss (prog2
622 (backward-char num-quotes)
623 (syntax-ppss)
624 (forward-char num-quotes)))
625 (string-start (and (not (nth 4 ppss)) (nth 8 ppss)))
626 (quote-starting-pos (- (point) num-quotes))
627 (quote-ending-pos (point))
628 (num-closing-quotes
629 (and string-start
630 (python-syntax-count-quotes
631 (char-before) string-start quote-starting-pos))))
632 (cond ((and string-start (= num-closing-quotes 0))
633 ;; This set of quotes doesn't match the string starting
634 ;; kind. Do nothing.
635 nil)
636 ((not string-start)
637 ;; This set of quotes delimit the start of a string.
638 (put-text-property quote-starting-pos (1+ quote-starting-pos)
639 'syntax-table (string-to-syntax "|")))
640 ((= num-quotes num-closing-quotes)
641 ;; This set of quotes delimit the end of a string.
642 (put-text-property (1- quote-ending-pos) quote-ending-pos
643 'syntax-table (string-to-syntax "|")))
644 ((> num-quotes num-closing-quotes)
645 ;; This may only happen whenever a triple quote is closing
646 ;; a single quoted string. Add string delimiter syntax to
647 ;; all three quotes.
648 (put-text-property quote-starting-pos quote-ending-pos
649 'syntax-table (string-to-syntax "|"))))))
651 (defvar python-mode-syntax-table
652 (let ((table (make-syntax-table)))
653 ;; Give punctuation syntax to ASCII that normally has symbol
654 ;; syntax or has word syntax and isn't a letter.
655 (let ((symbol (string-to-syntax "_"))
656 (sst (standard-syntax-table)))
657 (dotimes (i 128)
658 (unless (= i ?_)
659 (if (equal symbol (aref sst i))
660 (modify-syntax-entry i "." table)))))
661 (modify-syntax-entry ?$ "." table)
662 (modify-syntax-entry ?% "." table)
663 ;; exceptions
664 (modify-syntax-entry ?# "<" table)
665 (modify-syntax-entry ?\n ">" table)
666 (modify-syntax-entry ?' "\"" table)
667 (modify-syntax-entry ?` "$" table)
668 table)
669 "Syntax table for Python files.")
671 (defvar python-dotty-syntax-table
672 (let ((table (make-syntax-table python-mode-syntax-table)))
673 (modify-syntax-entry ?. "w" table)
674 (modify-syntax-entry ?_ "w" table)
675 table)
676 "Dotty syntax table for Python files.
677 It makes underscores and dots word constituent chars.")
680 ;;; Indentation
682 (defcustom python-indent-offset 4
683 "Default indentation offset for Python."
684 :group 'python
685 :type 'integer
686 :safe 'integerp)
688 (defcustom python-indent-guess-indent-offset t
689 "Non-nil tells Python mode to guess `python-indent-offset' value."
690 :type 'boolean
691 :group 'python
692 :safe 'booleanp)
694 (defcustom python-indent-trigger-commands
695 '(indent-for-tab-command yas-expand yas/expand)
696 "Commands that might trigger a `python-indent-line' call."
697 :type '(repeat symbol)
698 :group 'python)
700 (define-obsolete-variable-alias
701 'python-indent 'python-indent-offset "24.3")
703 (define-obsolete-variable-alias
704 'python-guess-indent 'python-indent-guess-indent-offset "24.3")
706 (defvar python-indent-current-level 0
707 "Current indentation level `python-indent-line-function' is using.")
709 (defvar python-indent-levels '(0)
710 "Levels of indentation available for `python-indent-line-function'.
711 Can also be `noindent' if automatic indentation can't be used.")
713 (defun python-indent-guess-indent-offset ()
714 "Guess and set `python-indent-offset' for the current buffer."
715 (interactive)
716 (save-excursion
717 (save-restriction
718 (widen)
719 (goto-char (point-min))
720 (let ((block-end))
721 (while (and (not block-end)
722 (re-search-forward
723 (python-rx line-start block-start) nil t))
724 (when (and
725 (not (python-syntax-context-type))
726 (progn
727 (goto-char (line-end-position))
728 (python-util-forward-comment -1)
729 (if (equal (char-before) ?:)
731 (forward-line 1)
732 (when (python-info-block-continuation-line-p)
733 (while (and (python-info-continuation-line-p)
734 (not (eobp)))
735 (forward-line 1))
736 (python-util-forward-comment -1)
737 (when (equal (char-before) ?:)
738 t)))))
739 (setq block-end (point-marker))))
740 (let ((indentation
741 (when block-end
742 (goto-char block-end)
743 (python-util-forward-comment)
744 (current-indentation))))
745 (if (and indentation (not (zerop indentation)))
746 (set (make-local-variable 'python-indent-offset) indentation)
747 (message "Can't guess python-indent-offset, using defaults: %s"
748 python-indent-offset)))))))
750 (defun python-indent-context ()
751 "Get information on indentation context.
752 Context information is returned with a cons with the form:
753 (STATUS . START)
755 Where status can be any of the following symbols:
757 * after-comment: When current line might continue a comment block
758 * inside-paren: If point in between (), {} or []
759 * inside-string: If point is inside a string
760 * after-backslash: Previous line ends in a backslash
761 * after-beginning-of-block: Point is after beginning of block
762 * after-line: Point is after normal line
763 * dedenter-statement: Point is on a dedenter statement.
764 * no-indent: Point is at beginning of buffer or other special case
765 START is the buffer position where the sexp starts."
766 (save-restriction
767 (widen)
768 (let ((ppss (save-excursion (beginning-of-line) (syntax-ppss)))
769 (start))
770 (cons
771 (cond
772 ;; Beginning of buffer
773 ((save-excursion
774 (goto-char (line-beginning-position))
775 (bobp))
776 'no-indent)
777 ;; Comment continuation
778 ((save-excursion
779 (when (and
781 (python-info-current-line-comment-p)
782 (python-info-current-line-empty-p))
783 (progn
784 (forward-comment -1)
785 (python-info-current-line-comment-p)))
786 (setq start (point))
787 'after-comment)))
788 ;; Inside string
789 ((setq start (python-syntax-context 'string ppss))
790 'inside-string)
791 ;; Inside a paren
792 ((setq start (python-syntax-context 'paren ppss))
793 'inside-paren)
794 ;; After backslash
795 ((setq start (when (not (or (python-syntax-context 'string ppss)
796 (python-syntax-context 'comment ppss)))
797 (let ((line-beg-pos (line-number-at-pos)))
798 (python-info-line-ends-backslash-p
799 (1- line-beg-pos)))))
800 'after-backslash)
801 ;; After beginning of block
802 ((setq start (save-excursion
803 (when (progn
804 (back-to-indentation)
805 (python-util-forward-comment -1)
806 (equal (char-before) ?:))
807 ;; Move to the first block start that's not in within
808 ;; a string, comment or paren and that's not a
809 ;; continuation line.
810 (while (and (re-search-backward
811 (python-rx block-start) nil t)
813 (python-syntax-context-type)
814 (python-info-continuation-line-p))))
815 (when (looking-at (python-rx block-start))
816 (point-marker)))))
817 'after-beginning-of-block)
818 ((when (setq start (python-info-dedenter-statement-p))
819 'dedenter-statement))
820 ;; After normal line
821 ((setq start (save-excursion
822 (back-to-indentation)
823 (skip-chars-backward (rx (or whitespace ?\n)))
824 (python-nav-beginning-of-statement)
825 (point-marker)))
826 'after-line)
827 ;; Do not indent
828 (t 'no-indent))
829 start))))
831 (defun python-indent-calculate-indentation ()
832 "Calculate correct indentation offset for the current line.
833 Returns `noindent' if the indentation does not depend on Python syntax,
834 such as in strings."
835 (let* ((indentation-context (python-indent-context))
836 (context-status (car indentation-context))
837 (context-start (cdr indentation-context)))
838 (save-restriction
839 (widen)
840 (save-excursion
841 (pcase context-status
842 (`no-indent 0)
843 (`after-comment
844 (goto-char context-start)
845 (current-indentation))
846 ;; When point is after beginning of block just add one level
847 ;; of indentation relative to the context-start
848 (`after-beginning-of-block
849 (goto-char context-start)
850 (+ (current-indentation) python-indent-offset))
851 ;; When after a simple line just use previous line
852 ;; indentation.
853 (`after-line
854 (let* ((pair (save-excursion
855 (goto-char context-start)
856 (cons
857 (current-indentation)
858 (python-info-beginning-of-block-p))))
859 (context-indentation (car pair))
860 ;; TODO: Separate block enders into its own case.
861 (adjustment
862 (if (save-excursion
863 (python-util-forward-comment -1)
864 (python-nav-beginning-of-statement)
865 (looking-at (python-rx block-ender)))
866 python-indent-offset
867 0)))
868 (- context-indentation adjustment)))
869 ;; When point is on a dedenter statement, search for the
870 ;; opening block that corresponds to it and use its
871 ;; indentation. If no opening block is found just remove
872 ;; indentation as this is an invalid python file.
873 (`dedenter-statement
874 (let ((block-start-point
875 (python-info-dedenter-opening-block-position)))
876 (save-excursion
877 (if (not block-start-point)
879 (goto-char block-start-point)
880 (current-indentation)))))
881 ;; When inside of a string, do nothing. just use the current
882 ;; indentation. XXX: perhaps it would be a good idea to
883 ;; invoke standard text indentation here
884 (`inside-string 'noindent)
885 ;; After backslash we have several possibilities.
886 (`after-backslash
887 (cond
888 ;; Check if current line is a dot continuation. For this
889 ;; the current line must start with a dot and previous
890 ;; line must contain a dot too.
891 ((save-excursion
892 (back-to-indentation)
893 (when (looking-at "\\.")
894 ;; If after moving one line back point is inside a paren it
895 ;; needs to move back until it's not anymore
896 (while (prog2
897 (forward-line -1)
898 (and (not (bobp))
899 (python-syntax-context 'paren))))
900 (goto-char (line-end-position))
901 (while (and (re-search-backward
902 "\\." (line-beginning-position) t)
903 (python-syntax-context-type)))
904 (if (and (looking-at "\\.")
905 (not (python-syntax-context-type)))
906 ;; The indentation is the same column of the
907 ;; first matching dot that's not inside a
908 ;; comment, a string or a paren
909 (current-column)
910 ;; No dot found on previous line, just add another
911 ;; indentation level.
912 (+ (current-indentation) python-indent-offset)))))
913 ;; Check if prev line is a block continuation
914 ((let ((block-continuation-start
915 (python-info-block-continuation-line-p)))
916 (when block-continuation-start
917 ;; If block-continuation-start is set jump to that
918 ;; marker and use first column after the block start
919 ;; as indentation value.
920 (goto-char block-continuation-start)
921 (re-search-forward
922 (python-rx block-start (* space))
923 (line-end-position) t)
924 (current-column))))
925 ;; Check if current line is an assignment continuation
926 ((let ((assignment-continuation-start
927 (python-info-assignment-continuation-line-p)))
928 (when assignment-continuation-start
929 ;; If assignment-continuation is set jump to that
930 ;; marker and use first column after the assignment
931 ;; operator as indentation value.
932 (goto-char assignment-continuation-start)
933 (current-column))))
935 (forward-line -1)
936 (goto-char (python-info-beginning-of-backslash))
937 (if (save-excursion
938 (and
939 (forward-line -1)
940 (goto-char
941 (or (python-info-beginning-of-backslash) (point)))
942 (python-info-line-ends-backslash-p)))
943 ;; The two previous lines ended in a backslash so we must
944 ;; respect previous line indentation.
945 (current-indentation)
946 ;; What happens here is that we are dealing with the second
947 ;; line of a backslash continuation, in that case we just going
948 ;; to add one indentation level.
949 (+ (current-indentation) python-indent-offset)))))
950 ;; When inside a paren there's a need to handle nesting
951 ;; correctly
952 (`inside-paren
953 (cond
954 ;; If current line closes the outermost open paren use the
955 ;; current indentation of the context-start line.
956 ((save-excursion
957 (skip-syntax-forward "\s" (line-end-position))
958 (when (and (looking-at (regexp-opt '(")" "]" "}")))
959 (progn
960 (forward-char 1)
961 (not (python-syntax-context 'paren))))
962 (goto-char context-start)
963 (current-indentation))))
964 ;; If open paren is contained on a line by itself add another
965 ;; indentation level, else look for the first word after the
966 ;; opening paren and use it's column position as indentation
967 ;; level.
968 ((let* ((content-starts-in-newline)
969 (indent
970 (save-excursion
971 (if (setq content-starts-in-newline
972 (progn
973 (goto-char context-start)
974 (forward-char)
975 (save-restriction
976 (narrow-to-region
977 (line-beginning-position)
978 (line-end-position))
979 (python-util-forward-comment))
980 (looking-at "$")))
981 (+ (current-indentation) python-indent-offset)
982 (current-column)))))
983 ;; Adjustments
984 (cond
985 ;; If current line closes a nested open paren de-indent one
986 ;; level.
987 ((progn
988 (back-to-indentation)
989 (looking-at (regexp-opt '(")" "]" "}"))))
990 (- indent python-indent-offset))
991 ;; If the line of the opening paren that wraps the current
992 ;; line starts a block add another level of indentation to
993 ;; follow new pep8 recommendation. See: http://ur1.ca/5rojx
994 ((save-excursion
995 (when (and content-starts-in-newline
996 (progn
997 (goto-char context-start)
998 (back-to-indentation)
999 (looking-at (python-rx block-start))))
1000 (+ indent python-indent-offset))))
1001 (t indent)))))))))))
1003 (defun python-indent-calculate-levels ()
1004 "Calculate `python-indent-levels' and reset `python-indent-current-level'."
1005 (if (or (python-info-continuation-line-p)
1006 (not (python-info-dedenter-statement-p)))
1007 ;; XXX: This asks for a refactor. Even if point is on a
1008 ;; dedenter statement, it could be multiline and in that case
1009 ;; the continuation lines should be indented with normal rules.
1010 (let* ((indentation (python-indent-calculate-indentation)))
1011 (if (not (numberp indentation))
1012 (setq python-indent-levels indentation)
1013 (let* ((remainder (% indentation python-indent-offset))
1014 (steps (/ (- indentation remainder) python-indent-offset)))
1015 (setq python-indent-levels (list 0))
1016 (dotimes (step steps)
1017 (push (* python-indent-offset (1+ step)) python-indent-levels))
1018 (when (not (eq 0 remainder))
1019 (push (+ (* python-indent-offset steps) remainder)
1020 python-indent-levels)))))
1021 (setq python-indent-levels
1023 (mapcar (lambda (pos)
1024 (save-excursion
1025 (goto-char pos)
1026 (current-indentation)))
1027 (python-info-dedenter-opening-block-positions))
1028 (list 0))))
1029 (when (listp python-indent-levels)
1030 (setq python-indent-current-level (1- (length python-indent-levels))
1031 python-indent-levels (nreverse python-indent-levels))))
1033 (defun python-indent-toggle-levels ()
1034 "Toggle `python-indent-current-level' over `python-indent-levels'."
1035 (setq python-indent-current-level (1- python-indent-current-level))
1036 (when (< python-indent-current-level 0)
1037 (setq python-indent-current-level (1- (length python-indent-levels)))))
1039 (defun python-indent-line (&optional force-toggle)
1040 "Internal implementation of `python-indent-line-function'.
1041 Uses the offset calculated in
1042 `python-indent-calculate-indentation' and available levels
1043 indicated by the variable `python-indent-levels' to set the
1044 current indentation.
1046 When the variable `last-command' is equal to one of the symbols
1047 inside `python-indent-trigger-commands' or FORCE-TOGGLE is
1048 non-nil it cycles levels indicated in the variable
1049 `python-indent-levels' by setting the current level in the
1050 variable `python-indent-current-level'.
1052 When the variable `last-command' is not equal to one of the
1053 symbols inside `python-indent-trigger-commands' and FORCE-TOGGLE
1054 is nil it calculates possible indentation levels and saves them
1055 in the variable `python-indent-levels'. Afterwards it sets the
1056 variable `python-indent-current-level' correctly so offset is
1057 equal to
1058 (nth python-indent-current-level python-indent-levels)"
1059 (if (and (or (and (memq this-command python-indent-trigger-commands)
1060 (eq last-command this-command))
1061 force-toggle)
1062 (not (equal python-indent-levels '(0))))
1063 (if (listp python-indent-levels)
1064 (python-indent-toggle-levels))
1065 (python-indent-calculate-levels))
1066 (if (eq python-indent-levels 'noindent)
1067 python-indent-levels
1068 (let* ((starting-pos (point-marker))
1069 (indent-ending-position
1070 (+ (line-beginning-position) (current-indentation)))
1071 (follow-indentation-p
1072 (or (bolp)
1073 (and (<= (line-beginning-position) starting-pos)
1074 (>= indent-ending-position starting-pos))))
1075 (next-indent (nth python-indent-current-level python-indent-levels)))
1076 (unless (= next-indent (current-indentation))
1077 (beginning-of-line)
1078 (delete-horizontal-space)
1079 (indent-to next-indent)
1080 (goto-char starting-pos))
1081 (and follow-indentation-p (back-to-indentation)))
1082 (python-info-dedenter-opening-block-message)))
1084 (defun python-indent-line-function ()
1085 "`indent-line-function' for Python mode.
1086 See `python-indent-line' for details."
1087 (python-indent-line))
1089 (defun python-indent-dedent-line ()
1090 "De-indent current line."
1091 (interactive "*")
1092 (when (and (not (python-syntax-comment-or-string-p))
1093 (<= (point) (save-excursion
1094 (back-to-indentation)
1095 (point)))
1096 (> (current-column) 0))
1097 (python-indent-line t)
1100 (defun python-indent-dedent-line-backspace (arg)
1101 "De-indent current line.
1102 Argument ARG is passed to `backward-delete-char-untabify' when
1103 point is not in between the indentation."
1104 (interactive "*p")
1105 (when (not (python-indent-dedent-line))
1106 (backward-delete-char-untabify arg)))
1107 (put 'python-indent-dedent-line-backspace 'delete-selection 'supersede)
1109 (defun python-indent-region (start end)
1110 "Indent a Python region automagically.
1112 Called from a program, START and END specify the region to indent."
1113 (let ((deactivate-mark nil))
1114 (save-excursion
1115 (goto-char end)
1116 (setq end (point-marker))
1117 (goto-char start)
1118 (or (bolp) (forward-line 1))
1119 (while (< (point) end)
1120 (or (and (bolp) (eolp))
1121 (when (and
1122 ;; Skip if previous line is empty or a comment.
1123 (save-excursion
1124 (let ((line-is-comment-p
1125 (python-info-current-line-comment-p)))
1126 (forward-line -1)
1127 (not
1128 (or (and (python-info-current-line-comment-p)
1129 ;; Unless this line is a comment too.
1130 (not line-is-comment-p))
1131 (python-info-current-line-empty-p)))))
1132 ;; Don't mess with strings, unless it's the
1133 ;; enclosing set of quotes.
1134 (or (not (python-syntax-context 'string))
1136 (syntax-after
1137 (+ (1- (point))
1138 (current-indentation)
1139 (python-syntax-count-quotes (char-after) (point))))
1140 (string-to-syntax "|")))
1141 ;; Skip if current line is a block start, a
1142 ;; dedenter or block ender.
1143 (save-excursion
1144 (back-to-indentation)
1145 (not (looking-at
1146 (python-rx
1147 (or block-start dedenter block-ender))))))
1148 (python-indent-line)))
1149 (forward-line 1))
1150 (move-marker end nil))))
1152 (defun python-indent-shift-left (start end &optional count)
1153 "Shift lines contained in region START END by COUNT columns to the left.
1154 COUNT defaults to `python-indent-offset'. If region isn't
1155 active, the current line is shifted. The shifted region includes
1156 the lines in which START and END lie. An error is signaled if
1157 any lines in the region are indented less than COUNT columns."
1158 (interactive
1159 (if mark-active
1160 (list (region-beginning) (region-end) current-prefix-arg)
1161 (list (line-beginning-position) (line-end-position) current-prefix-arg)))
1162 (if count
1163 (setq count (prefix-numeric-value count))
1164 (setq count python-indent-offset))
1165 (when (> count 0)
1166 (let ((deactivate-mark nil))
1167 (save-excursion
1168 (goto-char start)
1169 (while (< (point) end)
1170 (if (and (< (current-indentation) count)
1171 (not (looking-at "[ \t]*$")))
1172 (user-error "Can't shift all lines enough"))
1173 (forward-line))
1174 (indent-rigidly start end (- count))))))
1176 (defun python-indent-shift-right (start end &optional count)
1177 "Shift lines contained in region START END by COUNT columns to the right.
1178 COUNT defaults to `python-indent-offset'. If region isn't
1179 active, the current line is shifted. The shifted region includes
1180 the lines in which START and END lie."
1181 (interactive
1182 (if mark-active
1183 (list (region-beginning) (region-end) current-prefix-arg)
1184 (list (line-beginning-position) (line-end-position) current-prefix-arg)))
1185 (let ((deactivate-mark nil))
1186 (setq count (if count (prefix-numeric-value count)
1187 python-indent-offset))
1188 (indent-rigidly start end count)))
1190 (defun python-indent-post-self-insert-function ()
1191 "Adjust indentation after insertion of some characters.
1192 This function is intended to be added to `post-self-insert-hook.'
1193 If a line renders a paren alone, after adding a char before it,
1194 the line will be re-indented automatically if needed."
1195 (when (and electric-indent-mode
1196 (eq (char-before) last-command-event))
1197 (cond
1198 ;; Electric indent inside parens
1199 ((and
1200 (not (bolp))
1201 (let ((paren-start (python-syntax-context 'paren)))
1202 ;; Check that point is inside parens.
1203 (when paren-start
1204 (not
1205 ;; Filter the case where input is happening in the same
1206 ;; line where the open paren is.
1207 (= (line-number-at-pos)
1208 (line-number-at-pos paren-start)))))
1209 ;; When content has been added before the closing paren or a
1210 ;; comma has been inserted, it's ok to do the trick.
1212 (memq (char-after) '(?\) ?\] ?\}))
1213 (eq (char-before) ?,)))
1214 (save-excursion
1215 (goto-char (line-beginning-position))
1216 (let ((indentation (python-indent-calculate-indentation)))
1217 (when (and (numberp indentation) (< (current-indentation) indentation))
1218 (indent-line-to indentation)))))
1219 ;; Electric colon
1220 ((and (eq ?: last-command-event)
1221 (memq ?: electric-indent-chars)
1222 (not current-prefix-arg)
1223 ;; Trigger electric colon only at end of line
1224 (eolp)
1225 ;; Avoid re-indenting on extra colon
1226 (not (equal ?: (char-before (1- (point)))))
1227 (not (python-syntax-comment-or-string-p)))
1228 ;; Just re-indent dedenters
1229 (let ((dedenter-pos (python-info-dedenter-statement-p))
1230 (current-pos (point)))
1231 (when dedenter-pos
1232 (save-excursion
1233 (goto-char dedenter-pos)
1234 (python-indent-line)
1235 (unless (= (line-number-at-pos dedenter-pos)
1236 (line-number-at-pos current-pos))
1237 ;; Reindent region if this is a multiline statement
1238 (python-indent-region dedenter-pos current-pos)))))))))
1241 ;;; Navigation
1243 (defvar python-nav-beginning-of-defun-regexp
1244 (python-rx line-start (* space) defun (+ space) (group symbol-name))
1245 "Regexp matching class or function definition.
1246 The name of the defun should be grouped so it can be retrieved
1247 via `match-string'.")
1249 (defun python-nav--beginning-of-defun (&optional arg)
1250 "Internal implementation of `python-nav-beginning-of-defun'.
1251 With positive ARG search backwards, else search forwards."
1252 (when (or (null arg) (= arg 0)) (setq arg 1))
1253 (let* ((re-search-fn (if (> arg 0)
1254 #'re-search-backward
1255 #'re-search-forward))
1256 (line-beg-pos (line-beginning-position))
1257 (line-content-start (+ line-beg-pos (current-indentation)))
1258 (pos (point-marker))
1259 (beg-indentation
1260 (and (> arg 0)
1261 (save-excursion
1262 (while (and
1263 (not (python-info-looking-at-beginning-of-defun))
1264 (python-nav-backward-block)))
1265 (or (and (python-info-looking-at-beginning-of-defun)
1266 (+ (current-indentation) python-indent-offset))
1267 0))))
1268 (found
1269 (progn
1270 (when (and (< arg 0)
1271 (python-info-looking-at-beginning-of-defun))
1272 (end-of-line 1))
1273 (while (and (funcall re-search-fn
1274 python-nav-beginning-of-defun-regexp nil t)
1275 (or (python-syntax-context-type)
1276 ;; Handle nested defuns when moving
1277 ;; backwards by checking indentation.
1278 (and (> arg 0)
1279 (not (= (current-indentation) 0))
1280 (>= (current-indentation) beg-indentation)))))
1281 (and (python-info-looking-at-beginning-of-defun)
1282 (or (not (= (line-number-at-pos pos)
1283 (line-number-at-pos)))
1284 (and (>= (point) line-beg-pos)
1285 (<= (point) line-content-start)
1286 (> pos line-content-start)))))))
1287 (if found
1288 (or (beginning-of-line 1) t)
1289 (and (goto-char pos) nil))))
1291 (defun python-nav-beginning-of-defun (&optional arg)
1292 "Move point to `beginning-of-defun'.
1293 With positive ARG search backwards else search forward.
1294 ARG nil or 0 defaults to 1. When searching backwards,
1295 nested defuns are handled with care depending on current
1296 point position. Return non-nil if point is moved to
1297 `beginning-of-defun'."
1298 (when (or (null arg) (= arg 0)) (setq arg 1))
1299 (let ((found))
1300 (while (and (not (= arg 0))
1301 (let ((keep-searching-p
1302 (python-nav--beginning-of-defun arg)))
1303 (when (and keep-searching-p (null found))
1304 (setq found t))
1305 keep-searching-p))
1306 (setq arg (if (> arg 0) (1- arg) (1+ arg))))
1307 found))
1309 (defun python-nav-end-of-defun ()
1310 "Move point to the end of def or class.
1311 Returns nil if point is not in a def or class."
1312 (interactive)
1313 (let ((beg-defun-indent)
1314 (beg-pos (point)))
1315 (when (or (python-info-looking-at-beginning-of-defun)
1316 (python-nav-beginning-of-defun 1)
1317 (python-nav-beginning-of-defun -1))
1318 (setq beg-defun-indent (current-indentation))
1319 (while (progn
1320 (python-nav-end-of-statement)
1321 (python-util-forward-comment 1)
1322 (and (> (current-indentation) beg-defun-indent)
1323 (not (eobp)))))
1324 (python-util-forward-comment -1)
1325 (forward-line 1)
1326 ;; Ensure point moves forward.
1327 (and (> beg-pos (point)) (goto-char beg-pos)))))
1329 (defun python-nav--syntactically (fn poscompfn &optional contextfn)
1330 "Move point using FN avoiding places with specific context.
1331 FN must take no arguments. POSCOMPFN is a two arguments function
1332 used to compare current and previous point after it is moved
1333 using FN, this is normally a less-than or greater-than
1334 comparison. Optional argument CONTEXTFN defaults to
1335 `python-syntax-context-type' and is used for checking current
1336 point context, it must return a non-nil value if this point must
1337 be skipped."
1338 (let ((contextfn (or contextfn 'python-syntax-context-type))
1339 (start-pos (point-marker))
1340 (prev-pos))
1341 (catch 'found
1342 (while t
1343 (let* ((newpos
1344 (and (funcall fn) (point-marker)))
1345 (context (funcall contextfn)))
1346 (cond ((and (not context) newpos
1347 (or (and (not prev-pos) newpos)
1348 (and prev-pos newpos
1349 (funcall poscompfn newpos prev-pos))))
1350 (throw 'found (point-marker)))
1351 ((and newpos context)
1352 (setq prev-pos (point)))
1353 (t (when (not newpos) (goto-char start-pos))
1354 (throw 'found nil))))))))
1356 (defun python-nav--forward-defun (arg)
1357 "Internal implementation of python-nav-{backward,forward}-defun.
1358 Uses ARG to define which function to call, and how many times
1359 repeat it."
1360 (let ((found))
1361 (while (and (> arg 0)
1362 (setq found
1363 (python-nav--syntactically
1364 (lambda ()
1365 (re-search-forward
1366 python-nav-beginning-of-defun-regexp nil t))
1367 '>)))
1368 (setq arg (1- arg)))
1369 (while (and (< arg 0)
1370 (setq found
1371 (python-nav--syntactically
1372 (lambda ()
1373 (re-search-backward
1374 python-nav-beginning-of-defun-regexp nil t))
1375 '<)))
1376 (setq arg (1+ arg)))
1377 found))
1379 (defun python-nav-backward-defun (&optional arg)
1380 "Navigate to closer defun backward ARG times.
1381 Unlikely `python-nav-beginning-of-defun' this doesn't care about
1382 nested definitions."
1383 (interactive "^p")
1384 (python-nav--forward-defun (- (or arg 1))))
1386 (defun python-nav-forward-defun (&optional arg)
1387 "Navigate to closer defun forward ARG times.
1388 Unlikely `python-nav-beginning-of-defun' this doesn't care about
1389 nested definitions."
1390 (interactive "^p")
1391 (python-nav--forward-defun (or arg 1)))
1393 (defun python-nav-beginning-of-statement ()
1394 "Move to start of current statement."
1395 (interactive "^")
1396 (back-to-indentation)
1397 (let* ((ppss (syntax-ppss))
1398 (context-point
1400 (python-syntax-context 'paren ppss)
1401 (python-syntax-context 'string ppss))))
1402 (cond ((bobp))
1403 (context-point
1404 (goto-char context-point)
1405 (python-nav-beginning-of-statement))
1406 ((save-excursion
1407 (forward-line -1)
1408 (python-info-line-ends-backslash-p))
1409 (forward-line -1)
1410 (python-nav-beginning-of-statement))))
1411 (point-marker))
1413 (defun python-nav-end-of-statement (&optional noend)
1414 "Move to end of current statement.
1415 Optional argument NOEND is internal and makes the logic to not
1416 jump to the end of line when moving forward searching for the end
1417 of the statement."
1418 (interactive "^")
1419 (let (string-start bs-pos)
1420 (while (and (or noend (goto-char (line-end-position)))
1421 (not (eobp))
1422 (cond ((setq string-start (python-syntax-context 'string))
1423 (goto-char string-start)
1424 (if (python-syntax-context 'paren)
1425 ;; Ended up inside a paren, roll again.
1426 (python-nav-end-of-statement t)
1427 ;; This is not inside a paren, move to the
1428 ;; end of this string.
1429 (goto-char (+ (point)
1430 (python-syntax-count-quotes
1431 (char-after (point)) (point))))
1432 (or (re-search-forward (rx (syntax string-delimiter)) nil t)
1433 (goto-char (point-max)))))
1434 ((python-syntax-context 'paren)
1435 ;; The statement won't end before we've escaped
1436 ;; at least one level of parenthesis.
1437 (condition-case err
1438 (goto-char (scan-lists (point) 1 -1))
1439 (scan-error (goto-char (nth 3 err)))))
1440 ((setq bs-pos (python-info-line-ends-backslash-p))
1441 (goto-char bs-pos)
1442 (forward-line 1))))))
1443 (point-marker))
1445 (defun python-nav-backward-statement (&optional arg)
1446 "Move backward to previous statement.
1447 With ARG, repeat. See `python-nav-forward-statement'."
1448 (interactive "^p")
1449 (or arg (setq arg 1))
1450 (python-nav-forward-statement (- arg)))
1452 (defun python-nav-forward-statement (&optional arg)
1453 "Move forward to next statement.
1454 With ARG, repeat. With negative argument, move ARG times
1455 backward to previous statement."
1456 (interactive "^p")
1457 (or arg (setq arg 1))
1458 (while (> arg 0)
1459 (python-nav-end-of-statement)
1460 (python-util-forward-comment)
1461 (python-nav-beginning-of-statement)
1462 (setq arg (1- arg)))
1463 (while (< arg 0)
1464 (python-nav-beginning-of-statement)
1465 (python-util-forward-comment -1)
1466 (python-nav-beginning-of-statement)
1467 (setq arg (1+ arg))))
1469 (defun python-nav-beginning-of-block ()
1470 "Move to start of current block."
1471 (interactive "^")
1472 (let ((starting-pos (point)))
1473 (if (progn
1474 (python-nav-beginning-of-statement)
1475 (looking-at (python-rx block-start)))
1476 (point-marker)
1477 ;; Go to first line beginning a statement
1478 (while (and (not (bobp))
1479 (or (and (python-nav-beginning-of-statement) nil)
1480 (python-info-current-line-comment-p)
1481 (python-info-current-line-empty-p)))
1482 (forward-line -1))
1483 (let ((block-matching-indent
1484 (- (current-indentation) python-indent-offset)))
1485 (while
1486 (and (python-nav-backward-block)
1487 (> (current-indentation) block-matching-indent)))
1488 (if (and (looking-at (python-rx block-start))
1489 (= (current-indentation) block-matching-indent))
1490 (point-marker)
1491 (and (goto-char starting-pos) nil))))))
1493 (defun python-nav-end-of-block ()
1494 "Move to end of current block."
1495 (interactive "^")
1496 (when (python-nav-beginning-of-block)
1497 (let ((block-indentation (current-indentation)))
1498 (python-nav-end-of-statement)
1499 (while (and (forward-line 1)
1500 (not (eobp))
1501 (or (and (> (current-indentation) block-indentation)
1502 (or (python-nav-end-of-statement) t))
1503 (python-info-current-line-comment-p)
1504 (python-info-current-line-empty-p))))
1505 (python-util-forward-comment -1)
1506 (point-marker))))
1508 (defun python-nav-backward-block (&optional arg)
1509 "Move backward to previous block of code.
1510 With ARG, repeat. See `python-nav-forward-block'."
1511 (interactive "^p")
1512 (or arg (setq arg 1))
1513 (python-nav-forward-block (- arg)))
1515 (defun python-nav-forward-block (&optional arg)
1516 "Move forward to next block of code.
1517 With ARG, repeat. With negative argument, move ARG times
1518 backward to previous block."
1519 (interactive "^p")
1520 (or arg (setq arg 1))
1521 (let ((block-start-regexp
1522 (python-rx line-start (* whitespace) block-start))
1523 (starting-pos (point)))
1524 (while (> arg 0)
1525 (python-nav-end-of-statement)
1526 (while (and
1527 (re-search-forward block-start-regexp nil t)
1528 (python-syntax-context-type)))
1529 (setq arg (1- arg)))
1530 (while (< arg 0)
1531 (python-nav-beginning-of-statement)
1532 (while (and
1533 (re-search-backward block-start-regexp nil t)
1534 (python-syntax-context-type)))
1535 (setq arg (1+ arg)))
1536 (python-nav-beginning-of-statement)
1537 (if (not (looking-at (python-rx block-start)))
1538 (and (goto-char starting-pos) nil)
1539 (and (not (= (point) starting-pos)) (point-marker)))))
1541 (defun python-nav--lisp-forward-sexp (&optional arg)
1542 "Standard version `forward-sexp'.
1543 It ignores completely the value of `forward-sexp-function' by
1544 setting it to nil before calling `forward-sexp'. With positive
1545 ARG move forward only one sexp, else move backwards."
1546 (let ((forward-sexp-function)
1547 (arg (if (or (not arg) (> arg 0)) 1 -1)))
1548 (forward-sexp arg)))
1550 (defun python-nav--lisp-forward-sexp-safe (&optional arg)
1551 "Safe version of standard `forward-sexp'.
1552 When at end of sexp (i.e. looking at a opening/closing paren)
1553 skips it instead of throwing an error. With positive ARG move
1554 forward only one sexp, else move backwards."
1555 (let* ((arg (if (or (not arg) (> arg 0)) 1 -1))
1556 (paren-regexp
1557 (if (> arg 0) (python-rx close-paren) (python-rx open-paren)))
1558 (search-fn
1559 (if (> arg 0) #'re-search-forward #'re-search-backward)))
1560 (condition-case nil
1561 (python-nav--lisp-forward-sexp arg)
1562 (error
1563 (while (and (funcall search-fn paren-regexp nil t)
1564 (python-syntax-context 'paren)))))))
1566 (defun python-nav--forward-sexp (&optional dir safe)
1567 "Move to forward sexp.
1568 With positive optional argument DIR direction move forward, else
1569 backwards. When optional argument SAFE is non-nil do not throw
1570 errors when at end of sexp, skip it instead."
1571 (setq dir (or dir 1))
1572 (unless (= dir 0)
1573 (let* ((forward-p (if (> dir 0)
1574 (and (setq dir 1) t)
1575 (and (setq dir -1) nil)))
1576 (context-type (python-syntax-context-type)))
1577 (cond
1578 ((memq context-type '(string comment))
1579 ;; Inside of a string, get out of it.
1580 (let ((forward-sexp-function))
1581 (forward-sexp dir)))
1582 ((or (eq context-type 'paren)
1583 (and forward-p (looking-at (python-rx open-paren)))
1584 (and (not forward-p)
1585 (eq (syntax-class (syntax-after (1- (point))))
1586 (car (string-to-syntax ")")))))
1587 ;; Inside a paren or looking at it, lisp knows what to do.
1588 (if safe
1589 (python-nav--lisp-forward-sexp-safe dir)
1590 (python-nav--lisp-forward-sexp dir)))
1592 ;; This part handles the lispy feel of
1593 ;; `python-nav-forward-sexp'. Knowing everything about the
1594 ;; current context and the context of the next sexp tries to
1595 ;; follow the lisp sexp motion commands in a symmetric manner.
1596 (let* ((context
1597 (cond
1598 ((python-info-beginning-of-block-p) 'block-start)
1599 ((python-info-end-of-block-p) 'block-end)
1600 ((python-info-beginning-of-statement-p) 'statement-start)
1601 ((python-info-end-of-statement-p) 'statement-end)))
1602 (next-sexp-pos
1603 (save-excursion
1604 (if safe
1605 (python-nav--lisp-forward-sexp-safe dir)
1606 (python-nav--lisp-forward-sexp dir))
1607 (point)))
1608 (next-sexp-context
1609 (save-excursion
1610 (goto-char next-sexp-pos)
1611 (cond
1612 ((python-info-beginning-of-block-p) 'block-start)
1613 ((python-info-end-of-block-p) 'block-end)
1614 ((python-info-beginning-of-statement-p) 'statement-start)
1615 ((python-info-end-of-statement-p) 'statement-end)
1616 ((python-info-statement-starts-block-p) 'starts-block)
1617 ((python-info-statement-ends-block-p) 'ends-block)))))
1618 (if forward-p
1619 (cond ((and (not (eobp))
1620 (python-info-current-line-empty-p))
1621 (python-util-forward-comment dir)
1622 (python-nav--forward-sexp dir))
1623 ((eq context 'block-start)
1624 (python-nav-end-of-block))
1625 ((eq context 'statement-start)
1626 (python-nav-end-of-statement))
1627 ((and (memq context '(statement-end block-end))
1628 (eq next-sexp-context 'ends-block))
1629 (goto-char next-sexp-pos)
1630 (python-nav-end-of-block))
1631 ((and (memq context '(statement-end block-end))
1632 (eq next-sexp-context 'starts-block))
1633 (goto-char next-sexp-pos)
1634 (python-nav-end-of-block))
1635 ((memq context '(statement-end block-end))
1636 (goto-char next-sexp-pos)
1637 (python-nav-end-of-statement))
1638 (t (goto-char next-sexp-pos)))
1639 (cond ((and (not (bobp))
1640 (python-info-current-line-empty-p))
1641 (python-util-forward-comment dir)
1642 (python-nav--forward-sexp dir))
1643 ((eq context 'block-end)
1644 (python-nav-beginning-of-block))
1645 ((eq context 'statement-end)
1646 (python-nav-beginning-of-statement))
1647 ((and (memq context '(statement-start block-start))
1648 (eq next-sexp-context 'starts-block))
1649 (goto-char next-sexp-pos)
1650 (python-nav-beginning-of-block))
1651 ((and (memq context '(statement-start block-start))
1652 (eq next-sexp-context 'ends-block))
1653 (goto-char next-sexp-pos)
1654 (python-nav-beginning-of-block))
1655 ((memq context '(statement-start block-start))
1656 (goto-char next-sexp-pos)
1657 (python-nav-beginning-of-statement))
1658 (t (goto-char next-sexp-pos))))))))))
1660 (defun python-nav-forward-sexp (&optional arg)
1661 "Move forward across expressions.
1662 With ARG, do it that many times. Negative arg -N means move
1663 backward N times."
1664 (interactive "^p")
1665 (or arg (setq arg 1))
1666 (while (> arg 0)
1667 (python-nav--forward-sexp 1)
1668 (setq arg (1- arg)))
1669 (while (< arg 0)
1670 (python-nav--forward-sexp -1)
1671 (setq arg (1+ arg))))
1673 (defun python-nav-backward-sexp (&optional arg)
1674 "Move backward across expressions.
1675 With ARG, do it that many times. Negative arg -N means move
1676 forward N times."
1677 (interactive "^p")
1678 (or arg (setq arg 1))
1679 (python-nav-forward-sexp (- arg)))
1681 (defun python-nav-forward-sexp-safe (&optional arg)
1682 "Move forward safely across expressions.
1683 With ARG, do it that many times. Negative arg -N means move
1684 backward N times."
1685 (interactive "^p")
1686 (or arg (setq arg 1))
1687 (while (> arg 0)
1688 (python-nav--forward-sexp 1 t)
1689 (setq arg (1- arg)))
1690 (while (< arg 0)
1691 (python-nav--forward-sexp -1 t)
1692 (setq arg (1+ arg))))
1694 (defun python-nav-backward-sexp-safe (&optional arg)
1695 "Move backward safely across expressions.
1696 With ARG, do it that many times. Negative arg -N means move
1697 forward N times."
1698 (interactive "^p")
1699 (or arg (setq arg 1))
1700 (python-nav-forward-sexp-safe (- arg)))
1702 (defun python-nav--up-list (&optional dir)
1703 "Internal implementation of `python-nav-up-list'.
1704 DIR is always 1 or -1 and comes sanitized from
1705 `python-nav-up-list' calls."
1706 (let ((context (python-syntax-context-type))
1707 (forward-p (> dir 0)))
1708 (cond
1709 ((memq context '(string comment)))
1710 ((eq context 'paren)
1711 (let ((forward-sexp-function))
1712 (up-list dir)))
1713 ((and forward-p (python-info-end-of-block-p))
1714 (let ((parent-end-pos
1715 (save-excursion
1716 (let ((indentation (and
1717 (python-nav-beginning-of-block)
1718 (current-indentation))))
1719 (while (and indentation
1720 (> indentation 0)
1721 (>= (current-indentation) indentation)
1722 (python-nav-backward-block)))
1723 (python-nav-end-of-block)))))
1724 (and (> (or parent-end-pos (point)) (point))
1725 (goto-char parent-end-pos))))
1726 (forward-p (python-nav-end-of-block))
1727 ((and (not forward-p)
1728 (> (current-indentation) 0)
1729 (python-info-beginning-of-block-p))
1730 (let ((prev-block-pos
1731 (save-excursion
1732 (let ((indentation (current-indentation)))
1733 (while (and (python-nav-backward-block)
1734 (>= (current-indentation) indentation))))
1735 (point))))
1736 (and (> (point) prev-block-pos)
1737 (goto-char prev-block-pos))))
1738 ((not forward-p) (python-nav-beginning-of-block)))))
1740 (defun python-nav-up-list (&optional arg)
1741 "Move forward out of one level of parentheses (or blocks).
1742 With ARG, do this that many times.
1743 A negative argument means move backward but still to a less deep spot.
1744 This command assumes point is not in a string or comment."
1745 (interactive "^p")
1746 (or arg (setq arg 1))
1747 (while (> arg 0)
1748 (python-nav--up-list 1)
1749 (setq arg (1- arg)))
1750 (while (< arg 0)
1751 (python-nav--up-list -1)
1752 (setq arg (1+ arg))))
1754 (defun python-nav-backward-up-list (&optional arg)
1755 "Move backward out of one level of parentheses (or blocks).
1756 With ARG, do this that many times.
1757 A negative argument means move forward but still to a less deep spot.
1758 This command assumes point is not in a string or comment."
1759 (interactive "^p")
1760 (or arg (setq arg 1))
1761 (python-nav-up-list (- arg)))
1763 (defun python-nav-if-name-main ()
1764 "Move point at the beginning the __main__ block.
1765 When \"if __name__ == '__main__':\" is found returns its
1766 position, else returns nil."
1767 (interactive)
1768 (let ((point (point))
1769 (found (catch 'found
1770 (goto-char (point-min))
1771 (while (re-search-forward
1772 (python-rx line-start
1773 "if" (+ space)
1774 "__name__" (+ space)
1775 "==" (+ space)
1776 (group-n 1 (or ?\" ?\'))
1777 "__main__" (backref 1) (* space) ":")
1778 nil t)
1779 (when (not (python-syntax-context-type))
1780 (beginning-of-line)
1781 (throw 'found t))))))
1782 (if found
1783 (point)
1784 (ignore (goto-char point)))))
1787 ;;; Shell integration
1789 (defcustom python-shell-buffer-name "Python"
1790 "Default buffer name for Python interpreter."
1791 :type 'string
1792 :group 'python
1793 :safe 'stringp)
1795 (defcustom python-shell-interpreter "python"
1796 "Default Python interpreter for shell."
1797 :type 'string
1798 :group 'python)
1800 (defcustom python-shell-internal-buffer-name "Python Internal"
1801 "Default buffer name for the Internal Python interpreter."
1802 :type 'string
1803 :group 'python
1804 :safe 'stringp)
1806 (defcustom python-shell-interpreter-args "-i"
1807 "Default arguments for the Python interpreter."
1808 :type 'string
1809 :group 'python)
1811 (defcustom python-shell-interpreter-interactive-arg "-i"
1812 "Interpreter argument to force it to run interactively."
1813 :type 'string
1814 :version "24.4")
1816 (defcustom python-shell-prompt-detect-enabled t
1817 "Non-nil enables autodetection of interpreter prompts."
1818 :type 'boolean
1819 :safe 'booleanp
1820 :version "24.4")
1822 (defcustom python-shell-prompt-detect-failure-warning t
1823 "Non-nil enables warnings when detection of prompts fail."
1824 :type 'boolean
1825 :safe 'booleanp
1826 :version "24.4")
1828 (defcustom python-shell-prompt-input-regexps
1829 '(">>> " "\\.\\.\\. " ; Python
1830 "In \\[[0-9]+\\]: " ; IPython
1831 " \\.\\.\\.: " ; IPython
1832 ;; Using ipdb outside IPython may fail to cleanup and leave static
1833 ;; IPython prompts activated, this adds some safeguard for that.
1834 "In : " "\\.\\.\\.: ")
1835 "List of regular expressions matching input prompts."
1836 :type '(repeat string)
1837 :version "24.4")
1839 (defcustom python-shell-prompt-output-regexps
1840 '("" ; Python
1841 "Out\\[[0-9]+\\]: " ; IPython
1842 "Out :") ; ipdb safeguard
1843 "List of regular expressions matching output prompts."
1844 :type '(repeat string)
1845 :version "24.4")
1847 (defcustom python-shell-prompt-regexp ">>> "
1848 "Regular expression matching top level input prompt of Python shell.
1849 It should not contain a caret (^) at the beginning."
1850 :type 'string)
1852 (defcustom python-shell-prompt-block-regexp "\\.\\.\\. "
1853 "Regular expression matching block input prompt of Python shell.
1854 It should not contain a caret (^) at the beginning."
1855 :type 'string)
1857 (defcustom python-shell-prompt-output-regexp ""
1858 "Regular expression matching output prompt of Python shell.
1859 It should not contain a caret (^) at the beginning."
1860 :type 'string)
1862 (defcustom python-shell-prompt-pdb-regexp "[(<]*[Ii]?[Pp]db[>)]+ "
1863 "Regular expression matching pdb input prompt of Python shell.
1864 It should not contain a caret (^) at the beginning."
1865 :type 'string)
1867 (define-obsolete-variable-alias
1868 'python-shell-enable-font-lock 'python-shell-font-lock-enable "25.1")
1870 (defcustom python-shell-font-lock-enable t
1871 "Should syntax highlighting be enabled in the Python shell buffer?
1872 Restart the Python shell after changing this variable for it to take effect."
1873 :type 'boolean
1874 :group 'python
1875 :safe 'booleanp)
1877 (defcustom python-shell-unbuffered t
1878 "Should shell output be unbuffered?.
1879 When non-nil, this may prevent delayed and missing output in the
1880 Python shell. See commentary for details."
1881 :type 'boolean
1882 :group 'python
1883 :safe 'booleanp)
1885 (defcustom python-shell-process-environment nil
1886 "List of environment variables for Python shell.
1887 This variable follows the same rules as `process-environment'
1888 since it merges with it before the process creation routines are
1889 called. When this variable is nil, the Python shell is run with
1890 the default `process-environment'."
1891 :type '(repeat string)
1892 :group 'python
1893 :safe 'listp)
1895 (defcustom python-shell-extra-pythonpaths nil
1896 "List of extra pythonpaths for Python shell.
1897 The values of this variable are added to the existing value of
1898 PYTHONPATH in the `process-environment' variable."
1899 :type '(repeat string)
1900 :group 'python
1901 :safe 'listp)
1903 (defcustom python-shell-exec-path nil
1904 "List of path to search for binaries.
1905 This variable follows the same rules as `exec-path' since it
1906 merges with it before the process creation routines are called.
1907 When this variable is nil, the Python shell is run with the
1908 default `exec-path'."
1909 :type '(repeat string)
1910 :group 'python
1911 :safe 'listp)
1913 (defcustom python-shell-virtualenv-root nil
1914 "Path to virtualenv root.
1915 This variable, when set to a string, makes the values stored in
1916 `python-shell-process-environment' and `python-shell-exec-path'
1917 to be modified properly so shells are started with the specified
1918 virtualenv."
1919 :type '(choice (const nil) string)
1920 :group 'python
1921 :safe 'stringp)
1923 (define-obsolete-variable-alias
1924 'python-shell-virtualenv-path 'python-shell-virtualenv-root "25.1")
1926 (defcustom python-shell-setup-codes '(python-shell-completion-setup-code
1927 python-ffap-setup-code
1928 python-eldoc-setup-code)
1929 "List of code run by `python-shell-send-setup-codes'."
1930 :type '(repeat symbol)
1931 :group 'python
1932 :safe 'listp)
1934 (defcustom python-shell-compilation-regexp-alist
1935 `((,(rx line-start (1+ (any " \t")) "File \""
1936 (group (1+ (not (any "\"<")))) ; avoid `<stdin>' &c
1937 "\", line " (group (1+ digit)))
1938 1 2)
1939 (,(rx " in file " (group (1+ not-newline)) " on line "
1940 (group (1+ digit)))
1941 1 2)
1942 (,(rx line-start "> " (group (1+ (not (any "(\"<"))))
1943 "(" (group (1+ digit)) ")" (1+ (not (any "("))) "()")
1944 1 2))
1945 "`compilation-error-regexp-alist' for inferior Python."
1946 :type '(alist string)
1947 :group 'python)
1949 (defvar python-shell--prompt-calculated-input-regexp nil
1950 "Calculated input prompt regexp for inferior python shell.
1951 Do not set this variable directly, instead use
1952 `python-shell-prompt-set-calculated-regexps'.")
1954 (defvar python-shell--prompt-calculated-output-regexp nil
1955 "Calculated output prompt regexp for inferior python shell.
1956 Do not set this variable directly, instead use
1957 `python-shell-set-prompt-regexp'.")
1959 (defun python-shell-prompt-detect ()
1960 "Detect prompts for the current `python-shell-interpreter'.
1961 When prompts can be retrieved successfully from the
1962 `python-shell-interpreter' run with
1963 `python-shell-interpreter-interactive-arg', returns a list of
1964 three elements, where the first two are input prompts and the
1965 last one is an output prompt. When no prompts can be detected
1966 and `python-shell-prompt-detect-failure-warning' is non-nil,
1967 shows a warning with instructions to avoid hangs and returns nil.
1968 When `python-shell-prompt-detect-enabled' is nil avoids any
1969 detection and just returns nil."
1970 (when python-shell-prompt-detect-enabled
1971 (let* ((process-environment (python-shell-calculate-process-environment))
1972 (exec-path (python-shell-calculate-exec-path))
1973 (code (concat
1974 "import sys\n"
1975 "ps = [getattr(sys, 'ps%s' % i, '') for i in range(1,4)]\n"
1976 ;; JSON is built manually for compatibility
1977 "ps_json = '\\n[\"%s\", \"%s\", \"%s\"]\\n' % tuple(ps)\n"
1978 "print (ps_json)\n"
1979 "sys.exit(0)\n"))
1980 (output
1981 (with-temp-buffer
1982 ;; TODO: improve error handling by using
1983 ;; `condition-case' and displaying the error message to
1984 ;; the user in the no-prompts warning.
1985 (ignore-errors
1986 (let ((code-file (python-shell--save-temp-file code)))
1987 ;; Use `process-file' as it is remote-host friendly.
1988 (process-file
1989 python-shell-interpreter
1990 code-file
1991 '(t nil)
1993 python-shell-interpreter-interactive-arg)
1994 ;; Try to cleanup
1995 (delete-file code-file)))
1996 (buffer-string)))
1997 (prompts
1998 (catch 'prompts
1999 (dolist (line (split-string output "\n" t))
2000 (let ((res
2001 ;; Check if current line is a valid JSON array
2002 (and (string= (substring line 0 2) "[\"")
2003 (ignore-errors
2004 ;; Return prompts as a list, not vector
2005 (append (json-read-from-string line) nil)))))
2006 ;; The list must contain 3 strings, where the first
2007 ;; is the input prompt, the second is the block
2008 ;; prompt and the last one is the output prompt. The
2009 ;; input prompt is the only one that can't be empty.
2010 (when (and (= (length res) 3)
2011 (cl-every #'stringp res)
2012 (not (string= (car res) "")))
2013 (throw 'prompts res))))
2014 nil)))
2015 (when (and (not prompts)
2016 python-shell-prompt-detect-failure-warning)
2017 (lwarn
2018 '(python python-shell-prompt-regexp)
2019 :warning
2020 (concat
2021 "Python shell prompts cannot be detected.\n"
2022 "If your emacs session hangs when starting python shells\n"
2023 "recover with `keyboard-quit' and then try fixing the\n"
2024 "interactive flag for your interpreter by adjusting the\n"
2025 "`python-shell-interpreter-interactive-arg' or add regexps\n"
2026 "matching shell prompts in the directory-local friendly vars:\n"
2027 " + `python-shell-prompt-regexp'\n"
2028 " + `python-shell-prompt-block-regexp'\n"
2029 " + `python-shell-prompt-output-regexp'\n"
2030 "Or alternatively in:\n"
2031 " + `python-shell-prompt-input-regexps'\n"
2032 " + `python-shell-prompt-output-regexps'")))
2033 prompts)))
2035 (defun python-shell-prompt-validate-regexps ()
2036 "Validate all user provided regexps for prompts.
2037 Signals `user-error' if any of these vars contain invalid
2038 regexps: `python-shell-prompt-regexp',
2039 `python-shell-prompt-block-regexp',
2040 `python-shell-prompt-pdb-regexp',
2041 `python-shell-prompt-output-regexp',
2042 `python-shell-prompt-input-regexps',
2043 `python-shell-prompt-output-regexps'."
2044 (dolist (symbol (list 'python-shell-prompt-input-regexps
2045 'python-shell-prompt-output-regexps
2046 'python-shell-prompt-regexp
2047 'python-shell-prompt-block-regexp
2048 'python-shell-prompt-pdb-regexp
2049 'python-shell-prompt-output-regexp))
2050 (dolist (regexp (let ((regexps (symbol-value symbol)))
2051 (if (listp regexps)
2052 regexps
2053 (list regexps))))
2054 (when (not (python-util-valid-regexp-p regexp))
2055 (user-error "Invalid regexp %s in `%s'"
2056 regexp symbol)))))
2058 (defun python-shell-prompt-set-calculated-regexps ()
2059 "Detect and set input and output prompt regexps.
2060 Build and set the values for `python-shell-input-prompt-regexp'
2061 and `python-shell-output-prompt-regexp' using the values from
2062 `python-shell-prompt-regexp', `python-shell-prompt-block-regexp',
2063 `python-shell-prompt-pdb-regexp',
2064 `python-shell-prompt-output-regexp',
2065 `python-shell-prompt-input-regexps',
2066 `python-shell-prompt-output-regexps' and detected prompts from
2067 `python-shell-prompt-detect'."
2068 (when (not (and python-shell--prompt-calculated-input-regexp
2069 python-shell--prompt-calculated-output-regexp))
2070 (let* ((detected-prompts (python-shell-prompt-detect))
2071 (input-prompts nil)
2072 (output-prompts nil)
2073 (build-regexp
2074 (lambda (prompts)
2075 (concat "^\\("
2076 (mapconcat #'identity
2077 (sort prompts
2078 (lambda (a b)
2079 (let ((length-a (length a))
2080 (length-b (length b)))
2081 (if (= length-a length-b)
2082 (string< a b)
2083 (> (length a) (length b))))))
2084 "\\|")
2085 "\\)"))))
2086 ;; Validate ALL regexps
2087 (python-shell-prompt-validate-regexps)
2088 ;; Collect all user defined input prompts
2089 (dolist (prompt (append python-shell-prompt-input-regexps
2090 (list python-shell-prompt-regexp
2091 python-shell-prompt-block-regexp
2092 python-shell-prompt-pdb-regexp)))
2093 (cl-pushnew prompt input-prompts :test #'string=))
2094 ;; Collect all user defined output prompts
2095 (dolist (prompt (cons python-shell-prompt-output-regexp
2096 python-shell-prompt-output-regexps))
2097 (cl-pushnew prompt output-prompts :test #'string=))
2098 ;; Collect detected prompts if any
2099 (when detected-prompts
2100 (dolist (prompt (butlast detected-prompts))
2101 (setq prompt (regexp-quote prompt))
2102 (cl-pushnew prompt input-prompts :test #'string=))
2103 (cl-pushnew (regexp-quote
2104 (car (last detected-prompts)))
2105 output-prompts :test #'string=))
2106 ;; Set input and output prompt regexps from collected prompts
2107 (setq python-shell--prompt-calculated-input-regexp
2108 (funcall build-regexp input-prompts)
2109 python-shell--prompt-calculated-output-regexp
2110 (funcall build-regexp output-prompts)))))
2112 (defun python-shell-get-process-name (dedicated)
2113 "Calculate the appropriate process name for inferior Python process.
2114 If DEDICATED is t returns a string with the form
2115 `python-shell-buffer-name'[`buffer-name'] else returns the value
2116 of `python-shell-buffer-name'."
2117 (if dedicated
2118 (format "%s[%s]" python-shell-buffer-name (buffer-name))
2119 python-shell-buffer-name))
2121 (defun python-shell-internal-get-process-name ()
2122 "Calculate the appropriate process name for Internal Python process.
2123 The name is calculated from `python-shell-global-buffer-name' and
2124 the `buffer-name'."
2125 (format "%s[%s]" python-shell-internal-buffer-name (buffer-name)))
2127 (defun python-shell-calculate-command ()
2128 "Calculate the string used to execute the inferior Python process."
2129 (let ((exec-path (python-shell-calculate-exec-path)))
2130 ;; `exec-path' gets tweaked so that virtualenv's specific
2131 ;; `python-shell-interpreter' absolute path can be found by
2132 ;; `executable-find'.
2133 (format "%s %s"
2134 ;; FIXME: Why executable-find?
2135 (shell-quote-argument
2136 (executable-find python-shell-interpreter))
2137 python-shell-interpreter-args)))
2139 (define-obsolete-function-alias
2140 'python-shell-parse-command
2141 #'python-shell-calculate-command "25.1")
2143 (defun python-shell-calculate-pythonpath ()
2144 "Calculate the PYTHONPATH using `python-shell-extra-pythonpaths'."
2145 (let ((pythonpath (getenv "PYTHONPATH"))
2146 (extra (mapconcat 'identity
2147 python-shell-extra-pythonpaths
2148 path-separator)))
2149 (if pythonpath
2150 (concat extra path-separator pythonpath)
2151 extra)))
2153 (defun python-shell-calculate-process-environment ()
2154 "Calculate process environment given `python-shell-virtualenv-root'."
2155 (let ((process-environment (append
2156 python-shell-process-environment
2157 process-environment nil))
2158 (virtualenv (if python-shell-virtualenv-root
2159 (directory-file-name python-shell-virtualenv-root)
2160 nil)))
2161 (when python-shell-unbuffered
2162 (setenv "PYTHONUNBUFFERED" "1"))
2163 (when python-shell-extra-pythonpaths
2164 (setenv "PYTHONPATH" (python-shell-calculate-pythonpath)))
2165 (if (not virtualenv)
2166 process-environment
2167 (setenv "PYTHONHOME" nil)
2168 (setenv "PATH" (format "%s/bin%s%s"
2169 virtualenv path-separator
2170 (or (getenv "PATH") "")))
2171 (setenv "VIRTUAL_ENV" virtualenv))
2172 process-environment))
2174 (defun python-shell-calculate-exec-path ()
2175 "Calculate exec path given `python-shell-virtualenv-root'."
2176 (let ((path (append
2177 ;; Use nil as the tail so that the list is a full copy,
2178 ;; this is a paranoid safeguard for side-effects.
2179 python-shell-exec-path exec-path nil)))
2180 (if (not python-shell-virtualenv-root)
2181 path
2182 (cons (expand-file-name "bin" python-shell-virtualenv-root)
2183 path))))
2185 (defvar python-shell--package-depth 10)
2187 (defun python-shell-package-enable (directory package)
2188 "Add DIRECTORY parent to $PYTHONPATH and enable PACKAGE."
2189 (interactive
2190 (let* ((dir (expand-file-name
2191 (read-directory-name
2192 "Package root: "
2193 (file-name-directory
2194 (or (buffer-file-name) default-directory)))))
2195 (name (completing-read
2196 "Package: "
2197 (python-util-list-packages
2198 dir python-shell--package-depth))))
2199 (list dir name)))
2200 (python-shell-send-string
2201 (format
2202 (concat
2203 "import os.path;import sys;"
2204 "sys.path.append(os.path.dirname(os.path.dirname('''%s''')));"
2205 "__package__ = '''%s''';"
2206 "import %s")
2207 directory package package)
2208 (python-shell-get-process)))
2210 (defun python-shell-accept-process-output (process &optional timeout regexp)
2211 "Accept PROCESS output with TIMEOUT until REGEXP is found.
2212 Optional argument TIMEOUT is the timeout argument to
2213 `accept-process-output' calls. Optional argument REGEXP
2214 overrides the regexp to match the end of output, defaults to
2215 `comint-prompt-regexp.'. Returns non-nil when output was
2216 properly captured.
2218 This utility is useful in situations where the output may be
2219 received in chunks, since `accept-process-output' gives no
2220 guarantees they will be grabbed in a single call. An example use
2221 case for this would be the CPython shell start-up, where the
2222 banner and the initial prompt are received separately."
2223 (let ((regexp (or regexp comint-prompt-regexp)))
2224 (catch 'found
2225 (while t
2226 (when (not (accept-process-output process timeout))
2227 (throw 'found nil))
2228 (when (looking-back regexp)
2229 (throw 'found t))))))
2231 (defun python-shell-comint-end-of-output-p (output)
2232 "Return non-nil if OUTPUT is ends with input prompt."
2233 (string-match
2234 ;; XXX: It seems on OSX an extra carriage return is attached
2235 ;; at the end of output, this handles that too.
2236 (concat
2237 "\r?\n?"
2238 ;; Remove initial caret from calculated regexp
2239 (replace-regexp-in-string
2240 (rx string-start ?^) ""
2241 python-shell--prompt-calculated-input-regexp)
2242 (rx eos))
2243 output))
2245 (define-obsolete-function-alias
2246 'python-comint-output-filter-function
2247 'ansi-color-filter-apply
2248 "25.1")
2250 (defun python-comint-postoutput-scroll-to-bottom (output)
2251 "Faster version of `comint-postoutput-scroll-to-bottom'.
2252 Avoids `recenter' calls until OUTPUT is completely sent."
2253 (when (and (not (string= "" output))
2254 (python-shell-comint-end-of-output-p
2255 (ansi-color-filter-apply output)))
2256 (comint-postoutput-scroll-to-bottom output))
2257 output)
2259 (defvar python-shell--parent-buffer nil)
2261 (defmacro python-shell-with-shell-buffer (&rest body)
2262 "Execute the forms in BODY with the shell buffer temporarily current.
2263 Signals an error if no shell buffer is available for current buffer."
2264 (declare (indent 0) (debug t))
2265 (let ((shell-process (make-symbol "shell-process")))
2266 `(let ((,shell-process (python-shell-get-process-or-error)))
2267 (with-current-buffer (process-buffer ,shell-process)
2268 ,@body))))
2270 (defvar python-shell--font-lock-buffer nil)
2272 (defun python-shell-font-lock-get-or-create-buffer ()
2273 "Get or create a font-lock buffer for current inferior process."
2274 (python-shell-with-shell-buffer
2275 (if python-shell--font-lock-buffer
2276 python-shell--font-lock-buffer
2277 (let ((process-name
2278 (process-name (get-buffer-process (current-buffer)))))
2279 (generate-new-buffer
2280 (format "*%s-font-lock*" process-name))))))
2282 (defun python-shell-font-lock-kill-buffer ()
2283 "Kill the font-lock buffer safely."
2284 (python-shell-with-shell-buffer
2285 (when (and python-shell--font-lock-buffer
2286 (buffer-live-p python-shell--font-lock-buffer))
2287 (kill-buffer python-shell--font-lock-buffer)
2288 (when (derived-mode-p 'inferior-python-mode)
2289 (setq python-shell--font-lock-buffer nil)))))
2291 (defmacro python-shell-font-lock-with-font-lock-buffer (&rest body)
2292 "Execute the forms in BODY in the font-lock buffer.
2293 The value returned is the value of the last form in BODY. See
2294 also `with-current-buffer'."
2295 (declare (indent 0) (debug t))
2296 `(python-shell-with-shell-buffer
2297 (save-current-buffer
2298 (when (not (and python-shell--font-lock-buffer
2299 (get-buffer python-shell--font-lock-buffer)))
2300 (setq python-shell--font-lock-buffer
2301 (python-shell-font-lock-get-or-create-buffer)))
2302 (set-buffer python-shell--font-lock-buffer)
2303 (set (make-local-variable 'delay-mode-hooks) t)
2304 (let ((python-indent-guess-indent-offset nil))
2305 (when (not (derived-mode-p 'python-mode))
2306 (python-mode))
2307 ,@body))))
2309 (defun python-shell-font-lock-cleanup-buffer ()
2310 "Cleanup the font-lock buffer.
2311 Provided as a command because this might be handy if something
2312 goes wrong and syntax highlighting in the shell gets messed up."
2313 (interactive)
2314 (python-shell-with-shell-buffer
2315 (python-shell-font-lock-with-font-lock-buffer
2316 (delete-region (point-min) (point-max)))))
2318 (defun python-shell-font-lock-comint-output-filter-function (output)
2319 "Clean up the font-lock buffer after any OUTPUT."
2320 (when (and (not (string= "" output))
2321 ;; Is end of output and is not just a prompt.
2322 (not (member
2323 (python-shell-comint-end-of-output-p
2324 (ansi-color-filter-apply output))
2325 '(nil 0))))
2326 ;; If output is other than an input prompt then "real" output has
2327 ;; been received and the font-lock buffer must be cleaned up.
2328 (python-shell-font-lock-cleanup-buffer))
2329 output)
2331 (defun python-shell-font-lock-post-command-hook ()
2332 "Fontifies current line in shell buffer."
2333 (if (eq this-command 'comint-send-input)
2334 ;; Add a newline when user sends input as this may be a block.
2335 (python-shell-font-lock-with-font-lock-buffer
2336 (goto-char (line-end-position))
2337 (newline))
2338 (when (and (python-util-comint-last-prompt)
2339 (> (point) (cdr (python-util-comint-last-prompt))))
2340 (let ((input (buffer-substring-no-properties
2341 (cdr (python-util-comint-last-prompt)) (point-max)))
2342 (old-input (python-shell-font-lock-with-font-lock-buffer
2343 (buffer-substring-no-properties
2344 (line-beginning-position) (point-max))))
2345 (current-point (point))
2346 (buffer-undo-list t))
2347 ;; When input hasn't changed, do nothing.
2348 (when (not (string= input old-input))
2349 (delete-region (cdr (python-util-comint-last-prompt)) (point-max))
2350 (insert
2351 (python-shell-font-lock-with-font-lock-buffer
2352 (delete-region (line-beginning-position)
2353 (line-end-position))
2354 (insert input)
2355 ;; Ensure buffer is fontified, keeping it
2356 ;; compatible with Emacs < 24.4.
2357 (if (fboundp 'font-lock-ensure)
2358 (funcall 'font-lock-ensure)
2359 (font-lock-default-fontify-buffer))
2360 ;; Replace FACE text properties with FONT-LOCK-FACE so
2361 ;; they are not overwritten by comint buffer's font lock.
2362 (python-util-text-properties-replace-name
2363 'face 'font-lock-face)
2364 (buffer-substring (line-beginning-position)
2365 (line-end-position))))
2366 (goto-char current-point))))))
2368 (defun python-shell-font-lock-turn-on (&optional msg)
2369 "Turn on shell font-lock.
2370 With argument MSG show activation message."
2371 (interactive "p")
2372 (python-shell-with-shell-buffer
2373 (python-shell-font-lock-kill-buffer)
2374 (set (make-local-variable 'python-shell--font-lock-buffer) nil)
2375 (add-hook 'post-command-hook
2376 #'python-shell-font-lock-post-command-hook nil 'local)
2377 (add-hook 'kill-buffer-hook
2378 #'python-shell-font-lock-kill-buffer nil 'local)
2379 (add-hook 'comint-output-filter-functions
2380 #'python-shell-font-lock-comint-output-filter-function
2381 'append 'local)
2382 (when msg
2383 (message "Shell font-lock is enabled"))))
2385 (defun python-shell-font-lock-turn-off (&optional msg)
2386 "Turn off shell font-lock.
2387 With argument MSG show deactivation message."
2388 (interactive "p")
2389 (python-shell-with-shell-buffer
2390 (python-shell-font-lock-kill-buffer)
2391 (when (python-util-comint-last-prompt)
2392 ;; Cleanup current fontification
2393 (remove-text-properties
2394 (cdr (python-util-comint-last-prompt))
2395 (line-end-position)
2396 '(face nil font-lock-face nil)))
2397 (set (make-local-variable 'python-shell--font-lock-buffer) nil)
2398 (remove-hook 'post-command-hook
2399 #'python-shell-font-lock-post-command-hook'local)
2400 (remove-hook 'kill-buffer-hook
2401 #'python-shell-font-lock-kill-buffer 'local)
2402 (remove-hook 'comint-output-filter-functions
2403 #'python-shell-font-lock-comint-output-filter-function
2404 'local)
2405 (when msg
2406 (message "Shell font-lock is disabled"))))
2408 (defun python-shell-font-lock-toggle (&optional msg)
2409 "Toggle font-lock for shell.
2410 With argument MSG show activation/deactivation message."
2411 (interactive "p")
2412 (python-shell-with-shell-buffer
2413 (set (make-local-variable 'python-shell-font-lock-enable)
2414 (not python-shell-font-lock-enable))
2415 (if python-shell-font-lock-enable
2416 (python-shell-font-lock-turn-on msg)
2417 (python-shell-font-lock-turn-off msg))
2418 python-shell-font-lock-enable))
2420 (define-derived-mode inferior-python-mode comint-mode "Inferior Python"
2421 "Major mode for Python inferior process.
2422 Runs a Python interpreter as a subprocess of Emacs, with Python
2423 I/O through an Emacs buffer. Variables `python-shell-interpreter'
2424 and `python-shell-interpreter-args' control which Python
2425 interpreter is run. Variables
2426 `python-shell-prompt-regexp',
2427 `python-shell-prompt-output-regexp',
2428 `python-shell-prompt-block-regexp',
2429 `python-shell-font-lock-enable',
2430 `python-shell-completion-setup-code',
2431 `python-shell-completion-string-code',
2432 `python-eldoc-setup-code', `python-eldoc-string-code',
2433 `python-ffap-setup-code' and `python-ffap-string-code' can
2434 customize this mode for different Python interpreters.
2436 This mode resets `comint-output-filter-functions' locally, so you
2437 may want to re-add custom functions to it using the
2438 `inferior-python-mode-hook'.
2440 You can also add additional setup code to be run at
2441 initialization of the interpreter via `python-shell-setup-codes'
2442 variable.
2444 \(Type \\[describe-mode] in the process buffer for a list of commands.)"
2445 (let ((interpreter python-shell-interpreter)
2446 (args python-shell-interpreter-args))
2447 (when python-shell--parent-buffer
2448 (python-util-clone-local-variables python-shell--parent-buffer))
2449 ;; Users can override default values for these vars when calling
2450 ;; `run-python'. This ensures new values let-bound in
2451 ;; `python-shell-make-comint' are locally set.
2452 (set (make-local-variable 'python-shell-interpreter) interpreter)
2453 (set (make-local-variable 'python-shell-interpreter-args) args))
2454 (set (make-local-variable 'python-shell--prompt-calculated-input-regexp) nil)
2455 (set (make-local-variable 'python-shell--prompt-calculated-output-regexp) nil)
2456 (python-shell-prompt-set-calculated-regexps)
2457 (setq comint-prompt-regexp python-shell--prompt-calculated-input-regexp)
2458 (set (make-local-variable 'comint-prompt-read-only) t)
2459 (setq mode-line-process '(":%s"))
2460 (set (make-local-variable 'comint-output-filter-functions)
2461 '(ansi-color-process-output
2462 python-pdbtrack-comint-output-filter-function
2463 python-comint-postoutput-scroll-to-bottom))
2464 (set (make-local-variable 'compilation-error-regexp-alist)
2465 python-shell-compilation-regexp-alist)
2466 (add-hook 'completion-at-point-functions
2467 #'python-shell-completion-at-point nil 'local)
2468 (define-key inferior-python-mode-map "\t"
2469 'python-shell-completion-complete-or-indent)
2470 (make-local-variable 'python-pdbtrack-buffers-to-kill)
2471 (make-local-variable 'python-pdbtrack-tracked-buffer)
2472 (make-local-variable 'python-shell-internal-last-output)
2473 (when python-shell-font-lock-enable
2474 (python-shell-font-lock-turn-on))
2475 (compilation-shell-minor-mode 1)
2476 (python-shell-accept-process-output
2477 (get-buffer-process (current-buffer))))
2479 (defun python-shell-make-comint (cmd proc-name &optional show internal)
2480 "Create a Python shell comint buffer.
2481 CMD is the Python command to be executed and PROC-NAME is the
2482 process name the comint buffer will get. After the comint buffer
2483 is created the `inferior-python-mode' is activated. When
2484 optional argument SHOW is non-nil the buffer is shown. When
2485 optional argument INTERNAL is non-nil this process is run on a
2486 buffer with a name that starts with a space, following the Emacs
2487 convention for temporary/internal buffers, and also makes sure
2488 the user is not queried for confirmation when the process is
2489 killed."
2490 (save-excursion
2491 (let* ((proc-buffer-name
2492 (format (if (not internal) "*%s*" " *%s*") proc-name))
2493 (process-environment (python-shell-calculate-process-environment))
2494 (exec-path (python-shell-calculate-exec-path)))
2495 (when (not (comint-check-proc proc-buffer-name))
2496 (let* ((cmdlist (split-string-and-unquote cmd))
2497 (interpreter (car cmdlist))
2498 (args (cdr cmdlist))
2499 (buffer (apply #'make-comint-in-buffer proc-name proc-buffer-name
2500 interpreter nil args))
2501 (python-shell--parent-buffer (current-buffer))
2502 (process (get-buffer-process buffer))
2503 ;; As the user may have overridden default values for
2504 ;; these vars on `run-python', let-binding them allows
2505 ;; to have the new right values in all setup code
2506 ;; that's is done in `inferior-python-mode', which is
2507 ;; important, especially for prompt detection.
2508 (python-shell-interpreter interpreter)
2509 (python-shell-interpreter-args
2510 (mapconcat #'identity args " ")))
2511 (with-current-buffer buffer
2512 (inferior-python-mode))
2513 (when show (display-buffer buffer))
2514 (and internal (set-process-query-on-exit-flag process nil))))
2515 proc-buffer-name)))
2517 ;;;###autoload
2518 (defun run-python (&optional cmd dedicated show)
2519 "Run an inferior Python process.
2521 Argument CMD defaults to `python-shell-calculate-command' return
2522 value. When called interactively with `prefix-arg', it allows
2523 the user to edit such value and choose whether the interpreter
2524 should be DEDICATED for the current buffer. When numeric prefix
2525 arg is other than 0 or 4 do not SHOW.
2527 For a given buffer and same values of DEDICATED, if a process is
2528 already running for it, it will do nothing. This means that if
2529 the current buffer is using a global process, the user is still
2530 able to switch it to use a dedicated one.
2532 Runs the hook `inferior-python-mode-hook' after
2533 `comint-mode-hook' is run. (Type \\[describe-mode] in the
2534 process buffer for a list of commands.)"
2535 (interactive
2536 (if current-prefix-arg
2537 (list
2538 (read-shell-command "Run Python: " (python-shell-calculate-command))
2539 (y-or-n-p "Make dedicated process? ")
2540 (= (prefix-numeric-value current-prefix-arg) 4))
2541 (list (python-shell-calculate-command) nil t)))
2542 (get-buffer-process
2543 (python-shell-make-comint
2544 (or cmd (python-shell-calculate-command))
2545 (python-shell-get-process-name dedicated) show)))
2547 (defun run-python-internal ()
2548 "Run an inferior Internal Python process.
2549 Input and output via buffer named after
2550 `python-shell-internal-buffer-name' and what
2551 `python-shell-internal-get-process-name' returns.
2553 This new kind of shell is intended to be used for generic
2554 communication related to defined configurations; the main
2555 difference with global or dedicated shells is that these ones are
2556 attached to a configuration, not a buffer. This means that can
2557 be used for example to retrieve the sys.path and other stuff,
2558 without messing with user shells. Note that
2559 `python-shell-font-lock-enable' and `inferior-python-mode-hook'
2560 are set to nil for these shells, so setup codes are not sent at
2561 startup."
2562 (let ((python-shell-font-lock-enable nil)
2563 (inferior-python-mode-hook nil))
2564 (get-buffer-process
2565 (python-shell-make-comint
2566 (python-shell-calculate-command)
2567 (python-shell-internal-get-process-name) nil t))))
2569 (defun python-shell-get-buffer ()
2570 "Return inferior Python buffer for current buffer.
2571 If current buffer is in `inferior-python-mode', return it."
2572 (if (derived-mode-p 'inferior-python-mode)
2573 (current-buffer)
2574 (let* ((dedicated-proc-name (python-shell-get-process-name t))
2575 (dedicated-proc-buffer-name (format "*%s*" dedicated-proc-name))
2576 (global-proc-name (python-shell-get-process-name nil))
2577 (global-proc-buffer-name (format "*%s*" global-proc-name))
2578 (dedicated-running (comint-check-proc dedicated-proc-buffer-name))
2579 (global-running (comint-check-proc global-proc-buffer-name)))
2580 ;; Always prefer dedicated
2581 (or (and dedicated-running dedicated-proc-buffer-name)
2582 (and global-running global-proc-buffer-name)))))
2584 (defun python-shell-get-process ()
2585 "Return inferior Python process for current buffer."
2586 (get-buffer-process (python-shell-get-buffer)))
2588 (defun python-shell-get-process-or-error (&optional interactivep)
2589 "Return inferior Python process for current buffer or signal error.
2590 When argument INTERACTIVEP is non-nil, use `user-error' instead
2591 of `error' with a user-friendly message."
2592 (or (python-shell-get-process)
2593 (if interactivep
2594 (user-error
2595 "Start a Python process first with `M-x run-python' or `%s'."
2596 ;; Get the binding.
2597 (key-description
2598 (where-is-internal
2599 #'run-python overriding-local-map t)))
2600 (error
2601 "No inferior Python process running."))))
2603 (defun python-shell-get-or-create-process (&optional cmd dedicated show)
2604 "Get or create an inferior Python process for current buffer and return it.
2605 Arguments CMD, DEDICATED and SHOW are those of `run-python' and
2606 are used to start the shell. If those arguments are not
2607 provided, `run-python' is called interactively and the user will
2608 be asked for their values."
2609 (let ((shell-process (python-shell-get-process)))
2610 (when (not shell-process)
2611 (if (not cmd)
2612 ;; XXX: Refactor code such that calling `run-python'
2613 ;; interactively is not needed anymore.
2614 (call-interactively 'run-python)
2615 (run-python cmd dedicated show)))
2616 (or shell-process (python-shell-get-process))))
2618 (make-obsolete
2619 #'python-shell-get-or-create-process
2620 "Instead call `python-shell-get-process' and create one if returns nil."
2621 "25.1")
2623 (defvar python-shell-internal-buffer nil
2624 "Current internal shell buffer for the current buffer.
2625 This is really not necessary at all for the code to work but it's
2626 there for compatibility with CEDET.")
2628 (defvar python-shell-internal-last-output nil
2629 "Last output captured by the internal shell.
2630 This is really not necessary at all for the code to work but it's
2631 there for compatibility with CEDET.")
2633 (defun python-shell-internal-get-or-create-process ()
2634 "Get or create an inferior Internal Python process."
2635 (let ((proc-name (python-shell-internal-get-process-name)))
2636 (if (process-live-p proc-name)
2637 (get-process proc-name)
2638 (run-python-internal))))
2640 (define-obsolete-function-alias
2641 'python-proc 'python-shell-internal-get-or-create-process "24.3")
2643 (define-obsolete-variable-alias
2644 'python-buffer 'python-shell-internal-buffer "24.3")
2646 (define-obsolete-variable-alias
2647 'python-preoutput-result 'python-shell-internal-last-output "24.3")
2649 (defun python-shell--save-temp-file (string)
2650 (let* ((temporary-file-directory
2651 (if (file-remote-p default-directory)
2652 (concat (file-remote-p default-directory) "/tmp")
2653 temporary-file-directory))
2654 (temp-file-name (make-temp-file "py"))
2655 (coding-system-for-write (python-info-encoding)))
2656 (with-temp-file temp-file-name
2657 (insert string)
2658 (delete-trailing-whitespace))
2659 temp-file-name))
2661 (defun python-shell-send-string (string &optional process msg)
2662 "Send STRING to inferior Python PROCESS.
2663 When optional argument MSG is non-nil, forces display of a
2664 user-friendly message if there's no process running; defaults to
2665 t when called interactively."
2666 (interactive
2667 (list (read-string "Python command: ") nil t))
2668 (let ((process (or process (python-shell-get-process-or-error msg))))
2669 (if (string-match ".\n+." string) ;Multiline.
2670 (let* ((temp-file-name (python-shell--save-temp-file string))
2671 (file-name (or (buffer-file-name) temp-file-name)))
2672 (python-shell-send-file file-name process temp-file-name t))
2673 (comint-send-string process string)
2674 (when (or (not (string-match "\n\\'" string))
2675 (string-match "\n[ \t].*\n?\\'" string))
2676 (comint-send-string process "\n")))))
2678 (defvar python-shell-output-filter-in-progress nil)
2679 (defvar python-shell-output-filter-buffer nil)
2681 (defun python-shell-output-filter (string)
2682 "Filter used in `python-shell-send-string-no-output' to grab output.
2683 STRING is the output received to this point from the process.
2684 This filter saves received output from the process in
2685 `python-shell-output-filter-buffer' and stops receiving it after
2686 detecting a prompt at the end of the buffer."
2687 (setq
2688 string (ansi-color-filter-apply string)
2689 python-shell-output-filter-buffer
2690 (concat python-shell-output-filter-buffer string))
2691 (when (python-shell-comint-end-of-output-p
2692 python-shell-output-filter-buffer)
2693 ;; Output ends when `python-shell-output-filter-buffer' contains
2694 ;; the prompt attached at the end of it.
2695 (setq python-shell-output-filter-in-progress nil
2696 python-shell-output-filter-buffer
2697 (substring python-shell-output-filter-buffer
2698 0 (match-beginning 0)))
2699 (when (string-match
2700 python-shell--prompt-calculated-output-regexp
2701 python-shell-output-filter-buffer)
2702 ;; Some shells, like IPython might append a prompt before the
2703 ;; output, clean that.
2704 (setq python-shell-output-filter-buffer
2705 (substring python-shell-output-filter-buffer (match-end 0)))))
2708 (defun python-shell-send-string-no-output (string &optional process)
2709 "Send STRING to PROCESS and inhibit output.
2710 Return the output."
2711 (let ((process (or process (python-shell-get-process-or-error)))
2712 (comint-preoutput-filter-functions
2713 '(python-shell-output-filter))
2714 (python-shell-output-filter-in-progress t)
2715 (inhibit-quit t))
2717 (with-local-quit
2718 (python-shell-send-string string process)
2719 (while python-shell-output-filter-in-progress
2720 ;; `python-shell-output-filter' takes care of setting
2721 ;; `python-shell-output-filter-in-progress' to NIL after it
2722 ;; detects end of output.
2723 (accept-process-output process))
2724 (prog1
2725 python-shell-output-filter-buffer
2726 (setq python-shell-output-filter-buffer nil)))
2727 (with-current-buffer (process-buffer process)
2728 (comint-interrupt-subjob)))))
2730 (defun python-shell-internal-send-string (string)
2731 "Send STRING to the Internal Python interpreter.
2732 Returns the output. See `python-shell-send-string-no-output'."
2733 ;; XXX Remove `python-shell-internal-last-output' once CEDET is
2734 ;; updated to support this new mode.
2735 (setq python-shell-internal-last-output
2736 (python-shell-send-string-no-output
2737 ;; Makes this function compatible with the old
2738 ;; python-send-receive. (At least for CEDET).
2739 (replace-regexp-in-string "_emacs_out +" "" string)
2740 (python-shell-internal-get-or-create-process))))
2742 (define-obsolete-function-alias
2743 'python-send-receive 'python-shell-internal-send-string "24.3")
2745 (define-obsolete-function-alias
2746 'python-send-string 'python-shell-internal-send-string "24.3")
2748 (defun python-shell-buffer-substring (start end &optional nomain)
2749 "Send buffer substring from START to END formatted for shell.
2750 This is a wrapper over `buffer-substring' that takes care of
2751 different transformations for the code sent to be evaluated in
2752 the python shell:
2753 1. When optional argument NOMAIN is non-nil everything under an
2754 \"if __name__ == '__main__'\" block will be removed.
2755 2. When a subregion of the buffer is sent, it takes care of
2756 appending extra empty lines so tracebacks are correct.
2757 3. When the region sent is a substring of the current buffer, a
2758 coding cookie is added.
2759 4. Wraps indented regions under an \"if True:\" block so the
2760 interpreter evaluates them correctly."
2761 (let* ((substring (buffer-substring-no-properties start end))
2762 (starts-at-point-min-p (save-restriction
2763 (widen)
2764 (= (point-min) start)))
2765 (encoding (python-info-encoding))
2766 (fillstr (when (not starts-at-point-min-p)
2767 (concat
2768 (format "# -*- coding: %s -*-\n" encoding)
2769 (make-string
2770 ;; Subtract 2 because of the coding cookie.
2771 (- (line-number-at-pos start) 2) ?\n))))
2772 (toplevel-block-p (save-excursion
2773 (goto-char start)
2774 (or (zerop (line-number-at-pos start))
2775 (progn
2776 (python-util-forward-comment 1)
2777 (zerop (current-indentation)))))))
2778 (with-temp-buffer
2779 (python-mode)
2780 (if fillstr (insert fillstr))
2781 (insert substring)
2782 (goto-char (point-min))
2783 (when (not toplevel-block-p)
2784 (insert "if True:")
2785 (delete-region (point) (line-end-position)))
2786 (when nomain
2787 (let* ((if-name-main-start-end
2788 (and nomain
2789 (save-excursion
2790 (when (python-nav-if-name-main)
2791 (cons (point)
2792 (progn (python-nav-forward-sexp-safe)
2793 ;; Include ending newline
2794 (forward-line 1)
2795 (point)))))))
2796 ;; Oh destructuring bind, how I miss you.
2797 (if-name-main-start (car if-name-main-start-end))
2798 (if-name-main-end (cdr if-name-main-start-end))
2799 (fillstr (make-string
2800 (- (line-number-at-pos if-name-main-end)
2801 (line-number-at-pos if-name-main-start)) ?\n)))
2802 (when if-name-main-start-end
2803 (goto-char if-name-main-start)
2804 (delete-region if-name-main-start if-name-main-end)
2805 (insert fillstr))))
2806 ;; Ensure there's only one coding cookie in the generated string.
2807 (goto-char (point-min))
2808 (when (looking-at-p (python-rx coding-cookie))
2809 (forward-line 1)
2810 (when (looking-at-p (python-rx coding-cookie))
2811 (delete-region
2812 (line-beginning-position) (line-end-position))))
2813 (buffer-substring-no-properties (point-min) (point-max)))))
2815 (defun python-shell-send-region (start end &optional send-main msg)
2816 "Send the region delimited by START and END to inferior Python process.
2817 When optional argument SEND-MAIN is non-nil, allow execution of
2818 code inside blocks delimited by \"if __name__== '__main__':\".
2819 When called interactively SEND-MAIN defaults to nil, unless it's
2820 called with prefix argument. When optional argument MSG is
2821 non-nil, forces display of a user-friendly message if there's no
2822 process running; defaults to t when called interactively."
2823 (interactive
2824 (list (region-beginning) (region-end) current-prefix-arg t))
2825 (let* ((string (python-shell-buffer-substring start end (not send-main)))
2826 (process (python-shell-get-process-or-error msg))
2827 (original-string (buffer-substring-no-properties start end))
2828 (_ (string-match "\\`\n*\\(.*\\)" original-string)))
2829 (message "Sent: %s..." (match-string 1 original-string))
2830 (python-shell-send-string string process)))
2832 (defun python-shell-send-buffer (&optional send-main msg)
2833 "Send the entire buffer to inferior Python process.
2834 When optional argument SEND-MAIN is non-nil, allow execution of
2835 code inside blocks delimited by \"if __name__== '__main__':\".
2836 When called interactively SEND-MAIN defaults to nil, unless it's
2837 called with prefix argument. When optional argument MSG is
2838 non-nil, forces display of a user-friendly message if there's no
2839 process running; defaults to t when called interactively."
2840 (interactive (list current-prefix-arg t))
2841 (save-restriction
2842 (widen)
2843 (python-shell-send-region (point-min) (point-max) send-main msg)))
2845 (defun python-shell-send-defun (&optional arg msg)
2846 "Send the current defun to inferior Python process.
2847 When argument ARG is non-nil do not include decorators. When
2848 optional argument MSG is non-nil, forces display of a
2849 user-friendly message if there's no process running; defaults to
2850 t when called interactively."
2851 (interactive (list current-prefix-arg t))
2852 (save-excursion
2853 (python-shell-send-region
2854 (progn
2855 (end-of-line 1)
2856 (while (and (or (python-nav-beginning-of-defun)
2857 (beginning-of-line 1))
2858 (> (current-indentation) 0)))
2859 (when (not arg)
2860 (while (and (forward-line -1)
2861 (looking-at (python-rx decorator))))
2862 (forward-line 1))
2863 (point-marker))
2864 (progn
2865 (or (python-nav-end-of-defun)
2866 (end-of-line 1))
2867 (point-marker))
2868 nil ;; noop
2869 msg)))
2871 (defun python-shell-send-file (file-name &optional process temp-file-name
2872 delete msg)
2873 "Send FILE-NAME to inferior Python PROCESS.
2874 If TEMP-FILE-NAME is passed then that file is used for processing
2875 instead, while internally the shell will continue to use
2876 FILE-NAME. If TEMP-FILE-NAME and DELETE are non-nil, then
2877 TEMP-FILE-NAME is deleted after evaluation is performed. When
2878 optional argument MSG is non-nil, forces display of a
2879 user-friendly message if there's no process running; defaults to
2880 t when called interactively."
2881 (interactive
2882 (list
2883 (read-file-name "File to send: ") ; file-name
2884 nil ; process
2885 nil ; temp-file-name
2886 nil ; delete
2887 t)) ; msg
2888 (let* ((process (or process (python-shell-get-process-or-error msg)))
2889 (encoding (with-temp-buffer
2890 (insert-file-contents
2891 (or temp-file-name file-name))
2892 (python-info-encoding)))
2893 (file-name (expand-file-name
2894 (or (file-remote-p file-name 'localname)
2895 file-name)))
2896 (temp-file-name (when temp-file-name
2897 (expand-file-name
2898 (or (file-remote-p temp-file-name 'localname)
2899 temp-file-name)))))
2900 (python-shell-send-string
2901 (format
2902 (concat
2903 "import codecs, os;"
2904 "__pyfile = codecs.open('''%s''', encoding='''%s''');"
2905 "__code = __pyfile.read().encode('''%s''');"
2906 "__pyfile.close();"
2907 (when (and delete temp-file-name)
2908 (format "os.remove('''%s''');" temp-file-name))
2909 "exec(compile(__code, '''%s''', 'exec'));")
2910 (or temp-file-name file-name) encoding encoding file-name)
2911 process)))
2913 (defun python-shell-switch-to-shell (&optional msg)
2914 "Switch to inferior Python process buffer.
2915 When optional argument MSG is non-nil, forces display of a
2916 user-friendly message if there's no process running; defaults to
2917 t when called interactively."
2918 (interactive "p")
2919 (pop-to-buffer
2920 (process-buffer (python-shell-get-process-or-error msg)) nil t))
2922 (defun python-shell-send-setup-code ()
2923 "Send all setup code for shell.
2924 This function takes the list of setup code to send from the
2925 `python-shell-setup-codes' list."
2926 (let ((process (python-shell-get-process))
2927 (code (concat
2928 (mapconcat
2929 (lambda (elt)
2930 (cond ((stringp elt) elt)
2931 ((symbolp elt) (symbol-value elt))
2932 (t "")))
2933 python-shell-setup-codes
2934 "\n\n")
2935 "\n\nprint ('python.el: sent setup code')")))
2936 (python-shell-send-string code process)
2937 (python-shell-accept-process-output process)))
2939 (add-hook 'inferior-python-mode-hook
2940 #'python-shell-send-setup-code)
2943 ;;; Shell completion
2945 (defcustom python-shell-completion-setup-code
2946 "try:
2947 import __builtin__
2948 except ImportError:
2949 # Python 3
2950 import builtins as __builtin__
2951 try:
2952 import readline, rlcompleter
2953 except:
2954 def __PYTHON_EL_get_completions(text):
2955 return []
2956 else:
2957 def __PYTHON_EL_get_completions(text):
2958 builtins = dir(__builtin__)
2959 completions = []
2960 try:
2961 splits = text.split()
2962 is_module = splits and splits[0] in ('from', 'import')
2963 is_ipython = ('__IPYTHON__' in builtins or
2964 '__IPYTHON__active' in builtins)
2965 if is_module:
2966 from IPython.core.completerlib import module_completion
2967 completions = module_completion(text.strip())
2968 elif is_ipython and '__IP' in builtins:
2969 completions = __IP.complete(text)
2970 elif is_ipython and 'get_ipython' in builtins:
2971 completions = get_ipython().Completer.all_completions(text)
2972 else:
2973 i = 0
2974 while True:
2975 res = readline.get_completer()(text, i)
2976 if not res:
2977 break
2978 i += 1
2979 completions.append(res)
2980 except:
2981 pass
2982 return completions"
2983 "Code used to setup completion in inferior Python processes."
2984 :type 'string
2985 :group 'python)
2987 (defcustom python-shell-completion-string-code
2988 "';'.join(__PYTHON_EL_get_completions('''%s'''))\n"
2989 "Python code used to get a string of completions separated by semicolons.
2990 The string passed to the function is the current python name or
2991 the full statement in the case of imports."
2992 :type 'string
2993 :group 'python)
2995 (define-obsolete-variable-alias
2996 'python-shell-completion-module-string-code
2997 'python-shell-completion-string-code
2998 "24.4"
2999 "Completion string code must also autocomplete modules.")
3001 (define-obsolete-variable-alias
3002 'python-shell-completion-pdb-string-code
3003 'python-shell-completion-string-code
3004 "25.1"
3005 "Completion string code must work for (i)pdb.")
3007 (defcustom python-shell-completion-native-disabled-interpreters
3008 ;; PyPy's readline cannot handle some escape sequences yet.
3009 (list "pypy")
3010 "List of disabled interpreters.
3011 When a match is found, native completion is disabled."
3012 :type '(repeat string))
3014 (defcustom python-shell-completion-native-enable t
3015 "Enable readline based native completion."
3016 :type 'boolean)
3018 (defcustom python-shell-completion-native-output-timeout 0.01
3019 "Time in seconds to wait for completion output before giving up."
3020 :type 'float)
3022 (defvar python-shell-completion-native-redirect-buffer
3023 " *Python completions redirect*"
3024 "Buffer to be used to redirect output of readline commands.")
3026 (defun python-shell-completion-native-interpreter-disabled-p ()
3027 "Return non-nil if interpreter has native completion disabled."
3028 (when python-shell-completion-native-disabled-interpreters
3029 (string-match
3030 (regexp-opt python-shell-completion-native-disabled-interpreters)
3031 (file-name-nondirectory python-shell-interpreter))))
3033 (defun python-shell-completion-native-try ()
3034 "Return non-nil if can trigger native completion."
3035 (let ((python-shell-completion-native-enable t))
3036 (python-shell-completion-native-get-completions
3037 (get-buffer-process (current-buffer))
3038 nil "int")))
3040 (defun python-shell-completion-native-setup ()
3041 "Try to setup native completion, return non-nil on success."
3042 (let ((process (python-shell-get-process)))
3043 (python-shell-send-string
3044 (funcall
3045 'mapconcat
3046 #'identity
3047 (list
3048 "try:"
3049 " import readline, rlcompleter"
3050 ;; Remove parens on callables as it breaks completion on
3051 ;; arguments (e.g. str(Ari<tab>)).
3052 " class Completer(rlcompleter.Completer):"
3053 " def _callable_postfix(self, val, word):"
3054 " return word"
3055 " readline.set_completer(Completer().complete)"
3056 " if readline.__doc__ and 'libedit' in readline.__doc__:"
3057 " readline.parse_and_bind('bind ^I rl_complete')"
3058 " else:"
3059 " readline.parse_and_bind('tab: complete')"
3060 " print ('python.el: readline is available')"
3061 "except:"
3062 " print ('python.el: readline not available')")
3063 "\n")
3064 process)
3065 (python-shell-accept-process-output process)
3066 (when (save-excursion
3067 (re-search-backward
3068 (regexp-quote "python.el: readline is available") nil t 1))
3069 (python-shell-completion-native-try))))
3071 (defun python-shell-completion-native-turn-off (&optional msg)
3072 "Turn off shell native completions.
3073 With argument MSG show deactivation message."
3074 (interactive "p")
3075 (python-shell-with-shell-buffer
3076 (set (make-local-variable 'python-shell-completion-native-enable) nil)
3077 (when msg
3078 (message "Shell native completion is disabled, using fallback"))))
3080 (defun python-shell-completion-native-turn-on (&optional msg)
3081 "Turn on shell native completions.
3082 With argument MSG show deactivation message."
3083 (interactive "p")
3084 (python-shell-with-shell-buffer
3085 (set (make-local-variable 'python-shell-completion-native-enable) t)
3086 (python-shell-completion-native-turn-on-maybe msg)))
3088 (defun python-shell-completion-native-turn-on-maybe (&optional msg)
3089 "Turn on native completions if enabled and available.
3090 With argument MSG show activation/deactivation message."
3091 (interactive "p")
3092 (python-shell-with-shell-buffer
3093 (when python-shell-completion-native-enable
3094 (cond
3095 ((python-shell-completion-native-interpreter-disabled-p)
3096 (python-shell-completion-native-turn-off msg))
3097 ((python-shell-completion-native-setup)
3098 (when msg
3099 (message "Shell native completion is enabled.")))
3100 (t (lwarn
3101 '(python python-shell-completion-native-turn-on-maybe)
3102 :warning
3103 (concat
3104 "Your `python-shell-interpreter' doesn't seem to "
3105 "support readline, yet `python-shell-completion-native' "
3106 (format "was `t' and %S is not part of the "
3107 (file-name-nondirectory python-shell-interpreter))
3108 "`python-shell-completion-native-disabled-interpreters' "
3109 "list. Native completions have been disabled locally. "))
3110 (python-shell-completion-native-turn-off msg))))))
3112 (defun python-shell-completion-native-turn-on-maybe-with-msg ()
3113 "Like `python-shell-completion-native-turn-on-maybe' but force messages."
3114 (python-shell-completion-native-turn-on-maybe t))
3116 (add-hook 'inferior-python-mode-hook
3117 #'python-shell-completion-native-turn-on-maybe-with-msg)
3119 (defun python-shell-completion-native-toggle (&optional msg)
3120 "Toggle shell native completion.
3121 With argument MSG show activation/deactivation message."
3122 (interactive "p")
3123 (python-shell-with-shell-buffer
3124 (if python-shell-completion-native-enable
3125 (python-shell-completion-native-turn-off msg)
3126 (python-shell-completion-native-turn-on msg))
3127 python-shell-completion-native-enable))
3129 (defun python-shell-completion-native-get-completions (process import input)
3130 "Get completions using native readline for PROCESS.
3131 When IMPORT is non-nil takes precedence over INPUT for
3132 completion."
3133 (when (and python-shell-completion-native-enable
3134 (python-util-comint-last-prompt)
3135 (>= (point) (cdr (python-util-comint-last-prompt))))
3136 (let* ((input (or import input))
3137 (original-filter-fn (process-filter process))
3138 (redirect-buffer (get-buffer-create
3139 python-shell-completion-native-redirect-buffer))
3140 (separators (python-rx
3141 (or whitespace open-paren close-paren)))
3142 (trigger "\t\t\t")
3143 (new-input (concat input trigger))
3144 (input-length
3145 (save-excursion
3146 (+ (- (point-max) (comint-bol)) (length new-input))))
3147 (delete-line-command (make-string input-length ?\b))
3148 (input-to-send (concat new-input delete-line-command)))
3149 ;; Ensure restoring the process filter, even if the user quits
3150 ;; or there's some other error.
3151 (unwind-protect
3152 (with-current-buffer redirect-buffer
3153 ;; Cleanup the redirect buffer
3154 (delete-region (point-min) (point-max))
3155 ;; Mimic `comint-redirect-send-command', unfortunately it
3156 ;; can't be used here because it expects a newline in the
3157 ;; command and that's exactly what we are trying to avoid.
3158 (let ((comint-redirect-echo-input nil)
3159 (comint-redirect-verbose nil)
3160 (comint-redirect-perform-sanity-check nil)
3161 (comint-redirect-insert-matching-regexp nil)
3162 ;; Feed it some regex that will never match.
3163 (comint-redirect-finished-regexp "^\\'$")
3164 (comint-redirect-output-buffer redirect-buffer))
3165 ;; Compatibility with Emacs 24.x. Comint changed and
3166 ;; now `comint-redirect-filter' gets 3 args. This
3167 ;; checks which version of `comint-redirect-filter' is
3168 ;; in use based on its args and uses `apply-partially'
3169 ;; to make it up for the 3 args case.
3170 (if (= (length
3171 (help-function-arglist 'comint-redirect-filter)) 3)
3172 (set-process-filter
3173 process (apply-partially
3174 #'comint-redirect-filter original-filter-fn))
3175 (set-process-filter process #'comint-redirect-filter))
3176 (process-send-string process input-to-send)
3177 (accept-process-output
3178 process
3179 python-shell-completion-native-output-timeout)
3180 ;; XXX: can't use `python-shell-accept-process-output'
3181 ;; here because there are no guarantees on how output
3182 ;; ends. The workaround here is to call
3183 ;; `accept-process-output' until we don't find anything
3184 ;; else to accept.
3185 (while (accept-process-output
3186 process
3187 python-shell-completion-native-output-timeout))
3188 (cl-remove-duplicates
3189 (split-string
3190 (buffer-substring-no-properties
3191 (point-min) (point-max))
3192 separators t))))
3193 (set-process-filter process original-filter-fn)))))
3195 (defun python-shell-completion-get-completions (process import input)
3196 "Do completion at point using PROCESS for IMPORT or INPUT.
3197 When IMPORT is non-nil takes precedence over INPUT for
3198 completion."
3199 (with-current-buffer (process-buffer process)
3200 (let* ((prompt
3201 (let ((prompt-boundaries (python-util-comint-last-prompt)))
3202 (buffer-substring-no-properties
3203 (car prompt-boundaries) (cdr prompt-boundaries))))
3204 (completion-code
3205 ;; Check whether a prompt matches a pdb string, an import
3206 ;; statement or just the standard prompt and use the
3207 ;; correct python-shell-completion-*-code string
3208 (cond ((and (string-match
3209 (concat "^" python-shell-prompt-pdb-regexp) prompt))
3210 ;; Since there are no guarantees the user will remain
3211 ;; in the same context where completion code was sent
3212 ;; (e.g. user steps into a function), safeguard
3213 ;; resending completion setup continuously.
3214 (concat python-shell-completion-setup-code
3215 "\nprint (" python-shell-completion-string-code ")"))
3216 ((string-match
3217 python-shell--prompt-calculated-input-regexp prompt)
3218 python-shell-completion-string-code)
3219 (t nil)))
3220 (subject (or import input)))
3221 (and completion-code
3222 (> (length input) 0)
3223 (let ((completions
3224 (python-util-strip-string
3225 (python-shell-send-string-no-output
3226 (format completion-code subject) process))))
3227 (and (> (length completions) 2)
3228 (split-string completions
3229 "^'\\|^\"\\|;\\|'$\\|\"$" t)))))))
3231 (defun python-shell-completion-at-point (&optional process)
3232 "Function for `completion-at-point-functions' in `inferior-python-mode'.
3233 Optional argument PROCESS forces completions to be retrieved
3234 using that one instead of current buffer's process."
3235 (setq process (or process (get-buffer-process (current-buffer))))
3236 (let* ((last-prompt-end (cdr (python-util-comint-last-prompt)))
3237 (import-statement
3238 (when (string-match-p
3239 (rx (* space) word-start (or "from" "import") word-end space)
3240 (buffer-substring-no-properties last-prompt-end (point)))
3241 (buffer-substring-no-properties last-prompt-end (point))))
3242 (start
3243 (save-excursion
3244 (if (not (re-search-backward
3245 (python-rx
3246 (or whitespace open-paren close-paren string-delimiter))
3247 last-prompt-end
3248 t 1))
3249 last-prompt-end
3250 (forward-char (length (match-string-no-properties 0)))
3251 (point))))
3252 (end (point))
3253 (completion-fn
3254 (if python-shell-completion-native-enable
3255 #'python-shell-completion-native-get-completions
3256 #'python-shell-completion-get-completions)))
3257 (list start end
3258 (completion-table-dynamic
3259 (apply-partially
3260 completion-fn
3261 process import-statement)))))
3263 (define-obsolete-function-alias
3264 'python-shell-completion-complete-at-point
3265 'python-shell-completion-at-point
3266 "25.1")
3268 (defun python-shell-completion-complete-or-indent ()
3269 "Complete or indent depending on the context.
3270 If content before pointer is all whitespace, indent.
3271 If not try to complete."
3272 (interactive)
3273 (if (string-match "^[[:space:]]*$"
3274 (buffer-substring (comint-line-beginning-position)
3275 (point)))
3276 (indent-for-tab-command)
3277 (completion-at-point)))
3280 ;;; PDB Track integration
3282 (defcustom python-pdbtrack-activate t
3283 "Non-nil makes Python shell enable pdbtracking."
3284 :type 'boolean
3285 :group 'python
3286 :safe 'booleanp)
3288 (defcustom python-pdbtrack-stacktrace-info-regexp
3289 "> \\([^\"(<]+\\)(\\([0-9]+\\))\\([?a-zA-Z0-9_<>]+\\)()"
3290 "Regular expression matching stacktrace information.
3291 Used to extract the current line and module being inspected."
3292 :type 'string
3293 :group 'python
3294 :safe 'stringp)
3296 (defvar python-pdbtrack-tracked-buffer nil
3297 "Variable containing the value of the current tracked buffer.
3298 Never set this variable directly, use
3299 `python-pdbtrack-set-tracked-buffer' instead.")
3301 (defvar python-pdbtrack-buffers-to-kill nil
3302 "List of buffers to be deleted after tracking finishes.")
3304 (defun python-pdbtrack-set-tracked-buffer (file-name)
3305 "Set the buffer for FILE-NAME as the tracked buffer.
3306 Internally it uses the `python-pdbtrack-tracked-buffer' variable.
3307 Returns the tracked buffer."
3308 (let ((file-buffer (get-file-buffer
3309 (concat (file-remote-p default-directory)
3310 file-name))))
3311 (if file-buffer
3312 (setq python-pdbtrack-tracked-buffer file-buffer)
3313 (setq file-buffer (find-file-noselect file-name))
3314 (when (not (member file-buffer python-pdbtrack-buffers-to-kill))
3315 (add-to-list 'python-pdbtrack-buffers-to-kill file-buffer)))
3316 file-buffer))
3318 (defun python-pdbtrack-comint-output-filter-function (output)
3319 "Move overlay arrow to current pdb line in tracked buffer.
3320 Argument OUTPUT is a string with the output from the comint process."
3321 (when (and python-pdbtrack-activate (not (string= output "")))
3322 (let* ((full-output (ansi-color-filter-apply
3323 (buffer-substring comint-last-input-end (point-max))))
3324 (line-number)
3325 (file-name
3326 (with-temp-buffer
3327 (insert full-output)
3328 ;; When the debugger encounters a pdb.set_trace()
3329 ;; command, it prints a single stack frame. Sometimes
3330 ;; it prints a bit of extra information about the
3331 ;; arguments of the present function. When ipdb
3332 ;; encounters an exception, it prints the _entire_ stack
3333 ;; trace. To handle all of these cases, we want to find
3334 ;; the _last_ stack frame printed in the most recent
3335 ;; batch of output, then jump to the corresponding
3336 ;; file/line number.
3337 (goto-char (point-max))
3338 (when (re-search-backward python-pdbtrack-stacktrace-info-regexp nil t)
3339 (setq line-number (string-to-number
3340 (match-string-no-properties 2)))
3341 (match-string-no-properties 1)))))
3342 (if (and file-name line-number)
3343 (let* ((tracked-buffer
3344 (python-pdbtrack-set-tracked-buffer file-name))
3345 (shell-buffer (current-buffer))
3346 (tracked-buffer-window (get-buffer-window tracked-buffer))
3347 (tracked-buffer-line-pos))
3348 (with-current-buffer tracked-buffer
3349 (set (make-local-variable 'overlay-arrow-string) "=>")
3350 (set (make-local-variable 'overlay-arrow-position) (make-marker))
3351 (setq tracked-buffer-line-pos (progn
3352 (goto-char (point-min))
3353 (forward-line (1- line-number))
3354 (point-marker)))
3355 (when tracked-buffer-window
3356 (set-window-point
3357 tracked-buffer-window tracked-buffer-line-pos))
3358 (set-marker overlay-arrow-position tracked-buffer-line-pos))
3359 (pop-to-buffer tracked-buffer)
3360 (switch-to-buffer-other-window shell-buffer))
3361 (when python-pdbtrack-tracked-buffer
3362 (with-current-buffer python-pdbtrack-tracked-buffer
3363 (set-marker overlay-arrow-position nil))
3364 (mapc #'(lambda (buffer)
3365 (ignore-errors (kill-buffer buffer)))
3366 python-pdbtrack-buffers-to-kill)
3367 (setq python-pdbtrack-tracked-buffer nil
3368 python-pdbtrack-buffers-to-kill nil)))))
3369 output)
3372 ;;; Symbol completion
3374 (defun python-completion-at-point ()
3375 "Function for `completion-at-point-functions' in `python-mode'.
3376 For this to work as best as possible you should call
3377 `python-shell-send-buffer' from time to time so context in
3378 inferior Python process is updated properly."
3379 (let ((process (python-shell-get-process)))
3380 (when process
3381 (python-shell-completion-at-point process))))
3383 (define-obsolete-function-alias
3384 'python-completion-complete-at-point
3385 'python-completion-at-point
3386 "25.1")
3389 ;;; Fill paragraph
3391 (defcustom python-fill-comment-function 'python-fill-comment
3392 "Function to fill comments.
3393 This is the function used by `python-fill-paragraph' to
3394 fill comments."
3395 :type 'symbol
3396 :group 'python)
3398 (defcustom python-fill-string-function 'python-fill-string
3399 "Function to fill strings.
3400 This is the function used by `python-fill-paragraph' to
3401 fill strings."
3402 :type 'symbol
3403 :group 'python)
3405 (defcustom python-fill-decorator-function 'python-fill-decorator
3406 "Function to fill decorators.
3407 This is the function used by `python-fill-paragraph' to
3408 fill decorators."
3409 :type 'symbol
3410 :group 'python)
3412 (defcustom python-fill-paren-function 'python-fill-paren
3413 "Function to fill parens.
3414 This is the function used by `python-fill-paragraph' to
3415 fill parens."
3416 :type 'symbol
3417 :group 'python)
3419 (defcustom python-fill-docstring-style 'pep-257
3420 "Style used to fill docstrings.
3421 This affects `python-fill-string' behavior with regards to
3422 triple quotes positioning.
3424 Possible values are `django', `onetwo', `pep-257', `pep-257-nn',
3425 `symmetric', and nil. A value of nil won't care about quotes
3426 position and will treat docstrings a normal string, any other
3427 value may result in one of the following docstring styles:
3429 `django':
3431 \"\"\"
3432 Process foo, return bar.
3433 \"\"\"
3435 \"\"\"
3436 Process foo, return bar.
3438 If processing fails throw ProcessingError.
3439 \"\"\"
3441 `onetwo':
3443 \"\"\"Process foo, return bar.\"\"\"
3445 \"\"\"
3446 Process foo, return bar.
3448 If processing fails throw ProcessingError.
3450 \"\"\"
3452 `pep-257':
3454 \"\"\"Process foo, return bar.\"\"\"
3456 \"\"\"Process foo, return bar.
3458 If processing fails throw ProcessingError.
3460 \"\"\"
3462 `pep-257-nn':
3464 \"\"\"Process foo, return bar.\"\"\"
3466 \"\"\"Process foo, return bar.
3468 If processing fails throw ProcessingError.
3469 \"\"\"
3471 `symmetric':
3473 \"\"\"Process foo, return bar.\"\"\"
3475 \"\"\"
3476 Process foo, return bar.
3478 If processing fails throw ProcessingError.
3479 \"\"\""
3480 :type '(choice
3481 (const :tag "Don't format docstrings" nil)
3482 (const :tag "Django's coding standards style." django)
3483 (const :tag "One newline and start and Two at end style." onetwo)
3484 (const :tag "PEP-257 with 2 newlines at end of string." pep-257)
3485 (const :tag "PEP-257 with 1 newline at end of string." pep-257-nn)
3486 (const :tag "Symmetric style." symmetric))
3487 :group 'python
3488 :safe (lambda (val)
3489 (memq val '(django onetwo pep-257 pep-257-nn symmetric nil))))
3491 (defun python-fill-paragraph (&optional justify)
3492 "`fill-paragraph-function' handling multi-line strings and possibly comments.
3493 If any of the current line is in or at the end of a multi-line string,
3494 fill the string or the paragraph of it that point is in, preserving
3495 the string's indentation.
3496 Optional argument JUSTIFY defines if the paragraph should be justified."
3497 (interactive "P")
3498 (save-excursion
3499 (cond
3500 ;; Comments
3501 ((python-syntax-context 'comment)
3502 (funcall python-fill-comment-function justify))
3503 ;; Strings/Docstrings
3504 ((save-excursion (or (python-syntax-context 'string)
3505 (equal (string-to-syntax "|")
3506 (syntax-after (point)))))
3507 (funcall python-fill-string-function justify))
3508 ;; Decorators
3509 ((equal (char-after (save-excursion
3510 (python-nav-beginning-of-statement))) ?@)
3511 (funcall python-fill-decorator-function justify))
3512 ;; Parens
3513 ((or (python-syntax-context 'paren)
3514 (looking-at (python-rx open-paren))
3515 (save-excursion
3516 (skip-syntax-forward "^(" (line-end-position))
3517 (looking-at (python-rx open-paren))))
3518 (funcall python-fill-paren-function justify))
3519 (t t))))
3521 (defun python-fill-comment (&optional justify)
3522 "Comment fill function for `python-fill-paragraph'.
3523 JUSTIFY should be used (if applicable) as in `fill-paragraph'."
3524 (fill-comment-paragraph justify))
3526 (defun python-fill-string (&optional justify)
3527 "String fill function for `python-fill-paragraph'.
3528 JUSTIFY should be used (if applicable) as in `fill-paragraph'."
3529 (let* ((str-start-pos
3530 (set-marker
3531 (make-marker)
3532 (or (python-syntax-context 'string)
3533 (and (equal (string-to-syntax "|")
3534 (syntax-after (point)))
3535 (point)))))
3536 (num-quotes (python-syntax-count-quotes
3537 (char-after str-start-pos) str-start-pos))
3538 (str-end-pos
3539 (save-excursion
3540 (goto-char (+ str-start-pos num-quotes))
3541 (or (re-search-forward (rx (syntax string-delimiter)) nil t)
3542 (goto-char (point-max)))
3543 (point-marker)))
3544 (multi-line-p
3545 ;; Docstring styles may vary for oneliners and multi-liners.
3546 (> (count-matches "\n" str-start-pos str-end-pos) 0))
3547 (delimiters-style
3548 (pcase python-fill-docstring-style
3549 ;; delimiters-style is a cons cell with the form
3550 ;; (START-NEWLINES . END-NEWLINES). When any of the sexps
3551 ;; is NIL means to not add any newlines for start or end
3552 ;; of docstring. See `python-fill-docstring-style' for a
3553 ;; graphic idea of each style.
3554 (`django (cons 1 1))
3555 (`onetwo (and multi-line-p (cons 1 2)))
3556 (`pep-257 (and multi-line-p (cons nil 2)))
3557 (`pep-257-nn (and multi-line-p (cons nil 1)))
3558 (`symmetric (and multi-line-p (cons 1 1)))))
3559 (docstring-p (save-excursion
3560 ;; Consider docstrings those strings which
3561 ;; start on a line by themselves.
3562 (python-nav-beginning-of-statement)
3563 (and (= (point) str-start-pos))))
3564 (fill-paragraph-function))
3565 (save-restriction
3566 (narrow-to-region str-start-pos str-end-pos)
3567 (fill-paragraph justify))
3568 (save-excursion
3569 (when (and docstring-p python-fill-docstring-style)
3570 ;; Add the number of newlines indicated by the selected style
3571 ;; at the start of the docstring.
3572 (goto-char (+ str-start-pos num-quotes))
3573 (delete-region (point) (progn
3574 (skip-syntax-forward "> ")
3575 (point)))
3576 (and (car delimiters-style)
3577 (or (newline (car delimiters-style)) t)
3578 ;; Indent only if a newline is added.
3579 (indent-according-to-mode))
3580 ;; Add the number of newlines indicated by the selected style
3581 ;; at the end of the docstring.
3582 (goto-char (if (not (= str-end-pos (point-max)))
3583 (- str-end-pos num-quotes)
3584 str-end-pos))
3585 (delete-region (point) (progn
3586 (skip-syntax-backward "> ")
3587 (point)))
3588 (and (cdr delimiters-style)
3589 ;; Add newlines only if string ends.
3590 (not (= str-end-pos (point-max)))
3591 (or (newline (cdr delimiters-style)) t)
3592 ;; Again indent only if a newline is added.
3593 (indent-according-to-mode))))) t)
3595 (defun python-fill-decorator (&optional _justify)
3596 "Decorator fill function for `python-fill-paragraph'.
3597 JUSTIFY should be used (if applicable) as in `fill-paragraph'."
3600 (defun python-fill-paren (&optional justify)
3601 "Paren fill function for `python-fill-paragraph'.
3602 JUSTIFY should be used (if applicable) as in `fill-paragraph'."
3603 (save-restriction
3604 (narrow-to-region (progn
3605 (while (python-syntax-context 'paren)
3606 (goto-char (1- (point))))
3607 (line-beginning-position))
3608 (progn
3609 (when (not (python-syntax-context 'paren))
3610 (end-of-line)
3611 (when (not (python-syntax-context 'paren))
3612 (skip-syntax-backward "^)")))
3613 (while (and (python-syntax-context 'paren)
3614 (not (eobp)))
3615 (goto-char (1+ (point))))
3616 (point)))
3617 (let ((paragraph-start "\f\\|[ \t]*$")
3618 (paragraph-separate ",")
3619 (fill-paragraph-function))
3620 (goto-char (point-min))
3621 (fill-paragraph justify))
3622 (while (not (eobp))
3623 (forward-line 1)
3624 (python-indent-line)
3625 (goto-char (line-end-position))))
3629 ;;; Skeletons
3631 (defcustom python-skeleton-autoinsert nil
3632 "Non-nil means template skeletons will be automagically inserted.
3633 This happens when pressing \"if<SPACE>\", for example, to prompt for
3634 the if condition."
3635 :type 'boolean
3636 :group 'python
3637 :safe 'booleanp)
3639 (define-obsolete-variable-alias
3640 'python-use-skeletons 'python-skeleton-autoinsert "24.3")
3642 (defvar python-skeleton-available '()
3643 "Internal list of available skeletons.")
3645 (define-abbrev-table 'python-mode-skeleton-abbrev-table ()
3646 "Abbrev table for Python mode skeletons."
3647 :case-fixed t
3648 ;; Allow / inside abbrevs.
3649 :regexp "\\(?:^\\|[^/]\\)\\<\\([[:word:]/]+\\)\\W*"
3650 ;; Only expand in code.
3651 :enable-function (lambda ()
3652 (and
3653 (not (python-syntax-comment-or-string-p))
3654 python-skeleton-autoinsert)))
3656 (defmacro python-skeleton-define (name doc &rest skel)
3657 "Define a `python-mode' skeleton using NAME DOC and SKEL.
3658 The skeleton will be bound to python-skeleton-NAME and will
3659 be added to `python-mode-skeleton-abbrev-table'."
3660 (declare (indent 2))
3661 (let* ((name (symbol-name name))
3662 (function-name (intern (concat "python-skeleton-" name))))
3663 `(progn
3664 (define-abbrev python-mode-skeleton-abbrev-table
3665 ,name "" ',function-name :system t)
3666 (setq python-skeleton-available
3667 (cons ',function-name python-skeleton-available))
3668 (define-skeleton ,function-name
3669 ,(or doc
3670 (format "Insert %s statement." name))
3671 ,@skel))))
3673 (define-abbrev-table 'python-mode-abbrev-table ()
3674 "Abbrev table for Python mode."
3675 :parents (list python-mode-skeleton-abbrev-table))
3677 (defmacro python-define-auxiliary-skeleton (name doc &optional &rest skel)
3678 "Define a `python-mode' auxiliary skeleton using NAME DOC and SKEL.
3679 The skeleton will be bound to python-skeleton-NAME."
3680 (declare (indent 2))
3681 (let* ((name (symbol-name name))
3682 (function-name (intern (concat "python-skeleton--" name)))
3683 (msg (format
3684 "Add '%s' clause? " name)))
3685 (when (not skel)
3686 (setq skel
3687 `(< ,(format "%s:" name) \n \n
3688 > _ \n)))
3689 `(define-skeleton ,function-name
3690 ,(or doc
3691 (format "Auxiliary skeleton for %s statement." name))
3693 (unless (y-or-n-p ,msg)
3694 (signal 'quit t))
3695 ,@skel)))
3697 (python-define-auxiliary-skeleton else nil)
3699 (python-define-auxiliary-skeleton except nil)
3701 (python-define-auxiliary-skeleton finally nil)
3703 (python-skeleton-define if nil
3704 "Condition: "
3705 "if " str ":" \n
3706 _ \n
3707 ("other condition, %s: "
3709 "elif " str ":" \n
3710 > _ \n nil)
3711 '(python-skeleton--else) | ^)
3713 (python-skeleton-define while nil
3714 "Condition: "
3715 "while " str ":" \n
3716 > _ \n
3717 '(python-skeleton--else) | ^)
3719 (python-skeleton-define for nil
3720 "Iteration spec: "
3721 "for " str ":" \n
3722 > _ \n
3723 '(python-skeleton--else) | ^)
3725 (python-skeleton-define import nil
3726 "Import from module: "
3727 "from " str & " " | -5
3728 "import "
3729 ("Identifier: " str ", ") -2 \n _)
3731 (python-skeleton-define try nil
3733 "try:" \n
3734 > _ \n
3735 ("Exception, %s: "
3737 "except " str ":" \n
3738 > _ \n nil)
3739 resume:
3740 '(python-skeleton--except)
3741 '(python-skeleton--else)
3742 '(python-skeleton--finally) | ^)
3744 (python-skeleton-define def nil
3745 "Function name: "
3746 "def " str "(" ("Parameter, %s: "
3747 (unless (equal ?\( (char-before)) ", ")
3748 str) "):" \n
3749 "\"\"\"" - "\"\"\"" \n
3750 > _ \n)
3752 (python-skeleton-define class nil
3753 "Class name: "
3754 "class " str "(" ("Inheritance, %s: "
3755 (unless (equal ?\( (char-before)) ", ")
3756 str)
3757 & ")" | -1
3758 ":" \n
3759 "\"\"\"" - "\"\"\"" \n
3760 > _ \n)
3762 (defun python-skeleton-add-menu-items ()
3763 "Add menu items to Python->Skeletons menu."
3764 (let ((skeletons (sort python-skeleton-available 'string<)))
3765 (dolist (skeleton skeletons)
3766 (easy-menu-add-item
3767 nil '("Python" "Skeletons")
3768 `[,(format
3769 "Insert %s" (nth 2 (split-string (symbol-name skeleton) "-")))
3770 ,skeleton t]))))
3772 ;;; FFAP
3774 (defcustom python-ffap-setup-code
3775 "def __FFAP_get_module_path(module):
3776 try:
3777 import os
3778 path = __import__(module).__file__
3779 if path[-4:] == '.pyc' and os.path.exists(path[0:-1]):
3780 path = path[:-1]
3781 return path
3782 except:
3783 return ''"
3784 "Python code to get a module path."
3785 :type 'string
3786 :group 'python)
3788 (defcustom python-ffap-string-code
3789 "__FFAP_get_module_path('''%s''')\n"
3790 "Python code used to get a string with the path of a module."
3791 :type 'string
3792 :group 'python)
3794 (defun python-ffap-module-path (module)
3795 "Function for `ffap-alist' to return path for MODULE."
3796 (let ((process (or
3797 (and (derived-mode-p 'inferior-python-mode)
3798 (get-buffer-process (current-buffer)))
3799 (python-shell-get-process))))
3800 (if (not process)
3802 (let ((module-file
3803 (python-shell-send-string-no-output
3804 (format python-ffap-string-code module) process)))
3805 (when module-file
3806 (substring-no-properties module-file 1 -1))))))
3808 (defvar ffap-alist)
3810 (eval-after-load "ffap"
3811 '(progn
3812 (push '(python-mode . python-ffap-module-path) ffap-alist)
3813 (push '(inferior-python-mode . python-ffap-module-path) ffap-alist)))
3816 ;;; Code check
3818 (defcustom python-check-command
3819 "pyflakes"
3820 "Command used to check a Python file."
3821 :type 'string
3822 :group 'python)
3824 (defcustom python-check-buffer-name
3825 "*Python check: %s*"
3826 "Buffer name used for check commands."
3827 :type 'string
3828 :group 'python)
3830 (defvar python-check-custom-command nil
3831 "Internal use.")
3833 (defun python-check (command)
3834 "Check a Python file (default current buffer's file).
3835 Runs COMMAND, a shell command, as if by `compile'.
3836 See `python-check-command' for the default."
3837 (interactive
3838 (list (read-string "Check command: "
3839 (or python-check-custom-command
3840 (concat python-check-command " "
3841 (shell-quote-argument
3843 (let ((name (buffer-file-name)))
3844 (and name
3845 (file-name-nondirectory name)))
3846 "")))))))
3847 (setq python-check-custom-command command)
3848 (save-some-buffers (not compilation-ask-about-save) nil)
3849 (let ((process-environment (python-shell-calculate-process-environment))
3850 (exec-path (python-shell-calculate-exec-path)))
3851 (compilation-start command nil
3852 (lambda (_modename)
3853 (format python-check-buffer-name command)))))
3856 ;;; Eldoc
3858 (defcustom python-eldoc-setup-code
3859 "def __PYDOC_get_help(obj):
3860 try:
3861 import inspect
3862 try:
3863 str_type = basestring
3864 except NameError:
3865 str_type = str
3866 if isinstance(obj, str_type):
3867 obj = eval(obj, globals())
3868 doc = inspect.getdoc(obj)
3869 if not doc and callable(obj):
3870 target = None
3871 if inspect.isclass(obj) and hasattr(obj, '__init__'):
3872 target = obj.__init__
3873 objtype = 'class'
3874 else:
3875 target = obj
3876 objtype = 'def'
3877 if target:
3878 args = inspect.formatargspec(
3879 *inspect.getargspec(target)
3881 name = obj.__name__
3882 doc = '{objtype} {name}{args}'.format(
3883 objtype=objtype, name=name, args=args
3885 else:
3886 doc = doc.splitlines()[0]
3887 except:
3888 doc = ''
3889 print (doc)"
3890 "Python code to setup documentation retrieval."
3891 :type 'string
3892 :group 'python)
3894 (defcustom python-eldoc-string-code
3895 "__PYDOC_get_help('''%s''')\n"
3896 "Python code used to get a string with the documentation of an object."
3897 :type 'string
3898 :group 'python)
3900 (defun python-eldoc--get-doc-at-point (&optional force-input force-process)
3901 "Internal implementation to get documentation at point.
3902 If not FORCE-INPUT is passed then what `python-info-current-symbol'
3903 returns will be used. If not FORCE-PROCESS is passed what
3904 `python-shell-get-process' returns is used."
3905 (let ((process (or force-process (python-shell-get-process))))
3906 (when process
3907 (let ((input (or force-input
3908 (python-info-current-symbol t))))
3909 (and input
3910 ;; Prevent resizing the echo area when iPython is
3911 ;; enabled. Bug#18794.
3912 (python-util-strip-string
3913 (python-shell-send-string-no-output
3914 (format python-eldoc-string-code input)
3915 process)))))))
3917 (defun python-eldoc-function ()
3918 "`eldoc-documentation-function' for Python.
3919 For this to work as best as possible you should call
3920 `python-shell-send-buffer' from time to time so context in
3921 inferior Python process is updated properly."
3922 (python-eldoc--get-doc-at-point))
3924 (defun python-eldoc-at-point (symbol)
3925 "Get help on SYMBOL using `help'.
3926 Interactively, prompt for symbol."
3927 (interactive
3928 (let ((symbol (python-info-current-symbol t))
3929 (enable-recursive-minibuffers t))
3930 (list (read-string (if symbol
3931 (format "Describe symbol (default %s): " symbol)
3932 "Describe symbol: ")
3933 nil nil symbol))))
3934 (message (python-eldoc--get-doc-at-point symbol)))
3937 ;;; Imenu
3939 (defvar python-imenu-format-item-label-function
3940 'python-imenu-format-item-label
3941 "Imenu function used to format an item label.
3942 It must be a function with two arguments: TYPE and NAME.")
3944 (defvar python-imenu-format-parent-item-label-function
3945 'python-imenu-format-parent-item-label
3946 "Imenu function used to format a parent item label.
3947 It must be a function with two arguments: TYPE and NAME.")
3949 (defvar python-imenu-format-parent-item-jump-label-function
3950 'python-imenu-format-parent-item-jump-label
3951 "Imenu function used to format a parent jump item label.
3952 It must be a function with two arguments: TYPE and NAME.")
3954 (defun python-imenu-format-item-label (type name)
3955 "Return Imenu label for single node using TYPE and NAME."
3956 (format "%s (%s)" name type))
3958 (defun python-imenu-format-parent-item-label (type name)
3959 "Return Imenu label for parent node using TYPE and NAME."
3960 (format "%s..." (python-imenu-format-item-label type name)))
3962 (defun python-imenu-format-parent-item-jump-label (type _name)
3963 "Return Imenu label for parent node jump using TYPE and NAME."
3964 (if (string= type "class")
3965 "*class definition*"
3966 "*function definition*"))
3968 (defun python-imenu--put-parent (type name pos tree)
3969 "Add the parent with TYPE, NAME and POS to TREE."
3970 (let ((label
3971 (funcall python-imenu-format-item-label-function type name))
3972 (jump-label
3973 (funcall python-imenu-format-parent-item-jump-label-function type name)))
3974 (if (not tree)
3975 (cons label pos)
3976 (cons label (cons (cons jump-label pos) tree)))))
3978 (defun python-imenu--build-tree (&optional min-indent prev-indent tree)
3979 "Recursively build the tree of nested definitions of a node.
3980 Arguments MIN-INDENT, PREV-INDENT and TREE are internal and should
3981 not be passed explicitly unless you know what you are doing."
3982 (setq min-indent (or min-indent 0)
3983 prev-indent (or prev-indent python-indent-offset))
3984 (let* ((pos (python-nav-backward-defun))
3985 (type)
3986 (name (when (and pos (looking-at python-nav-beginning-of-defun-regexp))
3987 (let ((split (split-string (match-string-no-properties 0))))
3988 (setq type (car split))
3989 (cadr split))))
3990 (label (when name
3991 (funcall python-imenu-format-item-label-function type name)))
3992 (indent (current-indentation))
3993 (children-indent-limit (+ python-indent-offset min-indent)))
3994 (cond ((not pos)
3995 ;; Nothing found, probably near to bobp.
3996 nil)
3997 ((<= indent min-indent)
3998 ;; The current indentation points that this is a parent
3999 ;; node, add it to the tree and stop recursing.
4000 (python-imenu--put-parent type name pos tree))
4002 (python-imenu--build-tree
4003 min-indent
4004 indent
4005 (if (<= indent children-indent-limit)
4006 ;; This lies within the children indent offset range,
4007 ;; so it's a normal child of its parent (i.e., not
4008 ;; a child of a child).
4009 (cons (cons label pos) tree)
4010 ;; Oh no, a child of a child?! Fear not, we
4011 ;; know how to roll. We recursively parse these by
4012 ;; swapping prev-indent and min-indent plus adding this
4013 ;; newly found item to a fresh subtree. This works, I
4014 ;; promise.
4015 (cons
4016 (python-imenu--build-tree
4017 prev-indent indent (list (cons label pos)))
4018 tree)))))))
4020 (defun python-imenu-create-index ()
4021 "Return tree Imenu alist for the current Python buffer.
4022 Change `python-imenu-format-item-label-function',
4023 `python-imenu-format-parent-item-label-function',
4024 `python-imenu-format-parent-item-jump-label-function' to
4025 customize how labels are formatted."
4026 (goto-char (point-max))
4027 (let ((index)
4028 (tree))
4029 (while (setq tree (python-imenu--build-tree))
4030 (setq index (cons tree index)))
4031 index))
4033 (defun python-imenu-create-flat-index (&optional alist prefix)
4034 "Return flat outline of the current Python buffer for Imenu.
4035 Optional argument ALIST is the tree to be flattened; when nil
4036 `python-imenu-build-index' is used with
4037 `python-imenu-format-parent-item-jump-label-function'
4038 `python-imenu-format-parent-item-label-function'
4039 `python-imenu-format-item-label-function' set to
4040 (lambda (type name) name)
4041 Optional argument PREFIX is used in recursive calls and should
4042 not be passed explicitly.
4044 Converts this:
4046 ((\"Foo\" . 103)
4047 (\"Bar\" . 138)
4048 (\"decorator\"
4049 (\"decorator\" . 173)
4050 (\"wrap\"
4051 (\"wrap\" . 353)
4052 (\"wrapped_f\" . 393))))
4054 To this:
4056 ((\"Foo\" . 103)
4057 (\"Bar\" . 138)
4058 (\"decorator\" . 173)
4059 (\"decorator.wrap\" . 353)
4060 (\"decorator.wrapped_f\" . 393))"
4061 ;; Inspired by imenu--flatten-index-alist removed in revno 21853.
4062 (apply
4063 'nconc
4064 (mapcar
4065 (lambda (item)
4066 (let ((name (if prefix
4067 (concat prefix "." (car item))
4068 (car item)))
4069 (pos (cdr item)))
4070 (cond ((or (numberp pos) (markerp pos))
4071 (list (cons name pos)))
4072 ((listp pos)
4073 (cons
4074 (cons name (cdar pos))
4075 (python-imenu-create-flat-index (cddr item) name))))))
4076 (or alist
4077 (let* ((fn (lambda (_type name) name))
4078 (python-imenu-format-item-label-function fn)
4079 (python-imenu-format-parent-item-label-function fn)
4080 (python-imenu-format-parent-item-jump-label-function fn))
4081 (python-imenu-create-index))))))
4084 ;;; Misc helpers
4086 (defun python-info-current-defun (&optional include-type)
4087 "Return name of surrounding function with Python compatible dotty syntax.
4088 Optional argument INCLUDE-TYPE indicates to include the type of the defun.
4089 This function can be used as the value of `add-log-current-defun-function'
4090 since it returns nil if point is not inside a defun."
4091 (save-restriction
4092 (widen)
4093 (save-excursion
4094 (end-of-line 1)
4095 (let ((names)
4096 (starting-indentation (current-indentation))
4097 (starting-pos (point))
4098 (first-run t)
4099 (last-indent)
4100 (type))
4101 (catch 'exit
4102 (while (python-nav-beginning-of-defun 1)
4103 (when (save-match-data
4104 (and
4105 (or (not last-indent)
4106 (< (current-indentation) last-indent))
4108 (and first-run
4109 (save-excursion
4110 ;; If this is the first run, we may add
4111 ;; the current defun at point.
4112 (setq first-run nil)
4113 (goto-char starting-pos)
4114 (python-nav-beginning-of-statement)
4115 (beginning-of-line 1)
4116 (looking-at-p
4117 python-nav-beginning-of-defun-regexp)))
4118 (< starting-pos
4119 (save-excursion
4120 (let ((min-indent
4121 (+ (current-indentation)
4122 python-indent-offset)))
4123 (if (< starting-indentation min-indent)
4124 ;; If the starting indentation is not
4125 ;; within the min defun indent make the
4126 ;; check fail.
4127 starting-pos
4128 ;; Else go to the end of defun and add
4129 ;; up the current indentation to the
4130 ;; ending position.
4131 (python-nav-end-of-defun)
4132 (+ (point)
4133 (if (>= (current-indentation) min-indent)
4134 (1+ (current-indentation))
4135 0)))))))))
4136 (save-match-data (setq last-indent (current-indentation)))
4137 (if (or (not include-type) type)
4138 (setq names (cons (match-string-no-properties 1) names))
4139 (let ((match (split-string (match-string-no-properties 0))))
4140 (setq type (car match))
4141 (setq names (cons (cadr match) names)))))
4142 ;; Stop searching ASAP.
4143 (and (= (current-indentation) 0) (throw 'exit t))))
4144 (and names
4145 (concat (and type (format "%s " type))
4146 (mapconcat 'identity names ".")))))))
4148 (defun python-info-current-symbol (&optional replace-self)
4149 "Return current symbol using dotty syntax.
4150 With optional argument REPLACE-SELF convert \"self\" to current
4151 parent defun name."
4152 (let ((name
4153 (and (not (python-syntax-comment-or-string-p))
4154 (with-syntax-table python-dotty-syntax-table
4155 (let ((sym (symbol-at-point)))
4156 (and sym
4157 (substring-no-properties (symbol-name sym))))))))
4158 (when name
4159 (if (not replace-self)
4160 name
4161 (let ((current-defun (python-info-current-defun)))
4162 (if (not current-defun)
4163 name
4164 (replace-regexp-in-string
4165 (python-rx line-start word-start "self" word-end ?.)
4166 (concat
4167 (mapconcat 'identity
4168 (butlast (split-string current-defun "\\."))
4169 ".") ".")
4170 name)))))))
4172 (defun python-info-statement-starts-block-p ()
4173 "Return non-nil if current statement opens a block."
4174 (save-excursion
4175 (python-nav-beginning-of-statement)
4176 (looking-at (python-rx block-start))))
4178 (defun python-info-statement-ends-block-p ()
4179 "Return non-nil if point is at end of block."
4180 (let ((end-of-block-pos (save-excursion
4181 (python-nav-end-of-block)))
4182 (end-of-statement-pos (save-excursion
4183 (python-nav-end-of-statement))))
4184 (and end-of-block-pos end-of-statement-pos
4185 (= end-of-block-pos end-of-statement-pos))))
4187 (defun python-info-beginning-of-statement-p ()
4188 "Return non-nil if point is at beginning of statement."
4189 (= (point) (save-excursion
4190 (python-nav-beginning-of-statement)
4191 (point))))
4193 (defun python-info-end-of-statement-p ()
4194 "Return non-nil if point is at end of statement."
4195 (= (point) (save-excursion
4196 (python-nav-end-of-statement)
4197 (point))))
4199 (defun python-info-beginning-of-block-p ()
4200 "Return non-nil if point is at beginning of block."
4201 (and (python-info-beginning-of-statement-p)
4202 (python-info-statement-starts-block-p)))
4204 (defun python-info-end-of-block-p ()
4205 "Return non-nil if point is at end of block."
4206 (and (python-info-end-of-statement-p)
4207 (python-info-statement-ends-block-p)))
4209 (define-obsolete-function-alias
4210 'python-info-closing-block
4211 'python-info-dedenter-opening-block-position "24.4")
4213 (defun python-info-dedenter-opening-block-position ()
4214 "Return the point of the closest block the current line closes.
4215 Returns nil if point is not on a dedenter statement or no opening
4216 block can be detected. The latter case meaning current file is
4217 likely an invalid python file."
4218 (let ((positions (python-info-dedenter-opening-block-positions))
4219 (indentation (current-indentation))
4220 (position))
4221 (while (and (not position)
4222 positions)
4223 (save-excursion
4224 (goto-char (car positions))
4225 (if (<= (current-indentation) indentation)
4226 (setq position (car positions))
4227 (setq positions (cdr positions)))))
4228 position))
4230 (defun python-info-dedenter-opening-block-positions ()
4231 "Return points of blocks the current line may close sorted by closer.
4232 Returns nil if point is not on a dedenter statement or no opening
4233 block can be detected. The latter case meaning current file is
4234 likely an invalid python file."
4235 (save-excursion
4236 (let ((dedenter-pos (python-info-dedenter-statement-p)))
4237 (when dedenter-pos
4238 (goto-char dedenter-pos)
4239 (let* ((pairs '(("elif" "elif" "if")
4240 ("else" "if" "elif" "except" "for" "while")
4241 ("except" "except" "try")
4242 ("finally" "else" "except" "try")))
4243 (dedenter (match-string-no-properties 0))
4244 (possible-opening-blocks (cdr (assoc-string dedenter pairs)))
4245 (collected-indentations)
4246 (opening-blocks))
4247 (catch 'exit
4248 (while (python-nav--syntactically
4249 (lambda ()
4250 (re-search-backward (python-rx block-start) nil t))
4251 #'<)
4252 (let ((indentation (current-indentation)))
4253 (when (and (not (memq indentation collected-indentations))
4254 (or (not collected-indentations)
4255 (< indentation (apply #'min collected-indentations))))
4256 (setq collected-indentations
4257 (cons indentation collected-indentations))
4258 (when (member (match-string-no-properties 0)
4259 possible-opening-blocks)
4260 (setq opening-blocks (cons (point) opening-blocks))))
4261 (when (zerop indentation)
4262 (throw 'exit nil)))))
4263 ;; sort by closer
4264 (nreverse opening-blocks))))))
4266 (define-obsolete-function-alias
4267 'python-info-closing-block-message
4268 'python-info-dedenter-opening-block-message "24.4")
4270 (defun python-info-dedenter-opening-block-message ()
4271 "Message the first line of the block the current statement closes."
4272 (let ((point (python-info-dedenter-opening-block-position)))
4273 (when point
4274 (save-restriction
4275 (widen)
4276 (message "Closes %s" (save-excursion
4277 (goto-char point)
4278 (buffer-substring
4279 (point) (line-end-position))))))))
4281 (defun python-info-dedenter-statement-p ()
4282 "Return point if current statement is a dedenter.
4283 Sets `match-data' to the keyword that starts the dedenter
4284 statement."
4285 (save-excursion
4286 (python-nav-beginning-of-statement)
4287 (when (and (not (python-syntax-context-type))
4288 (looking-at (python-rx dedenter)))
4289 (point))))
4291 (defun python-info-line-ends-backslash-p (&optional line-number)
4292 "Return non-nil if current line ends with backslash.
4293 With optional argument LINE-NUMBER, check that line instead."
4294 (save-excursion
4295 (save-restriction
4296 (widen)
4297 (when line-number
4298 (python-util-goto-line line-number))
4299 (while (and (not (eobp))
4300 (goto-char (line-end-position))
4301 (python-syntax-context 'paren)
4302 (not (equal (char-before (point)) ?\\)))
4303 (forward-line 1))
4304 (when (equal (char-before) ?\\)
4305 (point-marker)))))
4307 (defun python-info-beginning-of-backslash (&optional line-number)
4308 "Return the point where the backslashed line start.
4309 Optional argument LINE-NUMBER forces the line number to check against."
4310 (save-excursion
4311 (save-restriction
4312 (widen)
4313 (when line-number
4314 (python-util-goto-line line-number))
4315 (when (python-info-line-ends-backslash-p)
4316 (while (save-excursion
4317 (goto-char (line-beginning-position))
4318 (python-syntax-context 'paren))
4319 (forward-line -1))
4320 (back-to-indentation)
4321 (point-marker)))))
4323 (defun python-info-continuation-line-p ()
4324 "Check if current line is continuation of another.
4325 When current line is continuation of another return the point
4326 where the continued line ends."
4327 (save-excursion
4328 (save-restriction
4329 (widen)
4330 (let* ((context-type (progn
4331 (back-to-indentation)
4332 (python-syntax-context-type)))
4333 (line-start (line-number-at-pos))
4334 (context-start (when context-type
4335 (python-syntax-context context-type))))
4336 (cond ((equal context-type 'paren)
4337 ;; Lines inside a paren are always a continuation line
4338 ;; (except the first one).
4339 (python-util-forward-comment -1)
4340 (point-marker))
4341 ((member context-type '(string comment))
4342 ;; move forward an roll again
4343 (goto-char context-start)
4344 (python-util-forward-comment)
4345 (python-info-continuation-line-p))
4347 ;; Not within a paren, string or comment, the only way
4348 ;; we are dealing with a continuation line is that
4349 ;; previous line contains a backslash, and this can
4350 ;; only be the previous line from current
4351 (back-to-indentation)
4352 (python-util-forward-comment -1)
4353 (when (and (equal (1- line-start) (line-number-at-pos))
4354 (python-info-line-ends-backslash-p))
4355 (point-marker))))))))
4357 (defun python-info-block-continuation-line-p ()
4358 "Return non-nil if current line is a continuation of a block."
4359 (save-excursion
4360 (when (python-info-continuation-line-p)
4361 (forward-line -1)
4362 (back-to-indentation)
4363 (when (looking-at (python-rx block-start))
4364 (point-marker)))))
4366 (defun python-info-assignment-continuation-line-p ()
4367 "Check if current line is a continuation of an assignment.
4368 When current line is continuation of another with an assignment
4369 return the point of the first non-blank character after the
4370 operator."
4371 (save-excursion
4372 (when (python-info-continuation-line-p)
4373 (forward-line -1)
4374 (back-to-indentation)
4375 (when (and (not (looking-at (python-rx block-start)))
4376 (and (re-search-forward (python-rx not-simple-operator
4377 assignment-operator
4378 not-simple-operator)
4379 (line-end-position) t)
4380 (not (python-syntax-context-type))))
4381 (skip-syntax-forward "\s")
4382 (point-marker)))))
4384 (defun python-info-looking-at-beginning-of-defun (&optional syntax-ppss)
4385 "Check if point is at `beginning-of-defun' using SYNTAX-PPSS."
4386 (and (not (python-syntax-context-type (or syntax-ppss (syntax-ppss))))
4387 (save-excursion
4388 (beginning-of-line 1)
4389 (looking-at python-nav-beginning-of-defun-regexp))))
4391 (defun python-info-current-line-comment-p ()
4392 "Return non-nil if current line is a comment line."
4393 (char-equal
4394 (or (char-after (+ (line-beginning-position) (current-indentation))) ?_)
4395 ?#))
4397 (defun python-info-current-line-empty-p ()
4398 "Return non-nil if current line is empty, ignoring whitespace."
4399 (save-excursion
4400 (beginning-of-line 1)
4401 (looking-at
4402 (python-rx line-start (* whitespace)
4403 (group (* not-newline))
4404 (* whitespace) line-end))
4405 (string-equal "" (match-string-no-properties 1))))
4407 (defun python-info-encoding-from-cookie ()
4408 "Detect current buffer's encoding from its coding cookie.
4409 Returns the encoding as a symbol."
4410 (let ((first-two-lines
4411 (save-excursion
4412 (save-restriction
4413 (widen)
4414 (goto-char (point-min))
4415 (forward-line 2)
4416 (buffer-substring-no-properties
4417 (point)
4418 (point-min))))))
4419 (when (string-match (python-rx coding-cookie) first-two-lines)
4420 (intern (match-string-no-properties 1 first-two-lines)))))
4422 (defun python-info-encoding ()
4423 "Return encoding for file.
4424 Try `python-info-encoding-from-cookie', if none is found then
4425 default to utf-8."
4426 ;; If no encoding is defined, then it's safe to use UTF-8: Python 2
4427 ;; uses ASCII as default while Python 3 uses UTF-8. This means that
4428 ;; in the worst case scenario python.el will make things work for
4429 ;; Python 2 files with unicode data and no encoding defined.
4430 (or (python-info-encoding-from-cookie)
4431 'utf-8))
4434 ;;; Utility functions
4436 (defun python-util-goto-line (line-number)
4437 "Move point to LINE-NUMBER."
4438 (goto-char (point-min))
4439 (forward-line (1- line-number)))
4441 ;; Stolen from org-mode
4442 (defun python-util-clone-local-variables (from-buffer &optional regexp)
4443 "Clone local variables from FROM-BUFFER.
4444 Optional argument REGEXP selects variables to clone and defaults
4445 to \"^python-\"."
4446 (mapc
4447 (lambda (pair)
4448 (and (symbolp (car pair))
4449 (string-match (or regexp "^python-")
4450 (symbol-name (car pair)))
4451 (set (make-local-variable (car pair))
4452 (cdr pair))))
4453 (buffer-local-variables from-buffer)))
4455 (defvar comint-last-prompt-overlay) ; Shut up, byte compiler.
4457 (defun python-util-comint-last-prompt ()
4458 "Return comint last prompt overlay start and end.
4459 This is for compatibility with Emacs < 24.4."
4460 (cond ((bound-and-true-p comint-last-prompt-overlay)
4461 (cons (overlay-start comint-last-prompt-overlay)
4462 (overlay-end comint-last-prompt-overlay)))
4463 ((bound-and-true-p comint-last-prompt)
4464 comint-last-prompt)
4465 (t nil)))
4467 (defun python-util-forward-comment (&optional direction)
4468 "Python mode specific version of `forward-comment'.
4469 Optional argument DIRECTION defines the direction to move to."
4470 (let ((comment-start (python-syntax-context 'comment))
4471 (factor (if (< (or direction 0) 0)
4472 -99999
4473 99999)))
4474 (when comment-start
4475 (goto-char comment-start))
4476 (forward-comment factor)))
4478 (defun python-util-list-directories (directory &optional predicate max-depth)
4479 "List DIRECTORY subdirs, filtered by PREDICATE and limited by MAX-DEPTH.
4480 Argument PREDICATE defaults to `identity' and must be a function
4481 that takes one argument (a full path) and returns non-nil for
4482 allowed files. When optional argument MAX-DEPTH is non-nil, stop
4483 searching when depth is reached, else don't limit."
4484 (let* ((dir (expand-file-name directory))
4485 (dir-length (length dir))
4486 (predicate (or predicate #'identity))
4487 (to-scan (list dir))
4488 (tally nil))
4489 (while to-scan
4490 (let ((current-dir (car to-scan)))
4491 (when (funcall predicate current-dir)
4492 (setq tally (cons current-dir tally)))
4493 (setq to-scan (append (cdr to-scan)
4494 (python-util-list-files
4495 current-dir #'file-directory-p)
4496 nil))
4497 (when (and max-depth
4498 (<= max-depth
4499 (length (split-string
4500 (substring current-dir dir-length)
4501 "/\\|\\\\" t))))
4502 (setq to-scan nil))))
4503 (nreverse tally)))
4505 (defun python-util-list-files (dir &optional predicate)
4506 "List files in DIR, filtering with PREDICATE.
4507 Argument PREDICATE defaults to `identity' and must be a function
4508 that takes one argument (a full path) and returns non-nil for
4509 allowed files."
4510 (let ((dir-name (file-name-as-directory dir)))
4511 (apply #'nconc
4512 (mapcar (lambda (file-name)
4513 (let ((full-file-name (expand-file-name file-name dir-name)))
4514 (when (and
4515 (not (member file-name '("." "..")))
4516 (funcall (or predicate #'identity) full-file-name))
4517 (list full-file-name))))
4518 (directory-files dir-name)))))
4520 (defun python-util-list-packages (dir &optional max-depth)
4521 "List packages in DIR, limited by MAX-DEPTH.
4522 When optional argument MAX-DEPTH is non-nil, stop searching when
4523 depth is reached, else don't limit."
4524 (let* ((dir (expand-file-name dir))
4525 (parent-dir (file-name-directory
4526 (directory-file-name
4527 (file-name-directory
4528 (file-name-as-directory dir)))))
4529 (subpath-length (length parent-dir)))
4530 (mapcar
4531 (lambda (file-name)
4532 (replace-regexp-in-string
4533 (rx (or ?\\ ?/)) "." (substring file-name subpath-length)))
4534 (python-util-list-directories
4535 (directory-file-name dir)
4536 (lambda (dir)
4537 (file-exists-p (expand-file-name "__init__.py" dir)))
4538 max-depth))))
4540 (defun python-util-popn (lst n)
4541 "Return LST first N elements.
4542 N should be an integer, when negative its opposite is used.
4543 When N is bigger than the length of LST, the list is
4544 returned as is."
4545 (let* ((n (min (abs n)))
4546 (len (length lst))
4547 (acc))
4548 (if (> n len)
4550 (while (< 0 n)
4551 (setq acc (cons (car lst) acc)
4552 lst (cdr lst)
4553 n (1- n)))
4554 (reverse acc))))
4556 (defun python-util-text-properties-replace-name
4557 (from to &optional start end)
4558 "Replace properties named FROM to TO, keeping its value.
4559 Arguments START and END narrow the buffer region to work on."
4560 (save-excursion
4561 (goto-char (or start (point-min)))
4562 (while (not (eobp))
4563 (let ((plist (text-properties-at (point)))
4564 (next-change (or (next-property-change (point) (current-buffer))
4565 (or end (point-max)))))
4566 (when (plist-get plist from)
4567 (let* ((face (plist-get plist from))
4568 (plist (plist-put plist from nil))
4569 (plist (plist-put plist to face)))
4570 (set-text-properties (point) next-change plist (current-buffer))))
4571 (goto-char next-change)))))
4573 (defun python-util-strip-string (string)
4574 "Strip STRING whitespace and newlines from end and beginning."
4575 (replace-regexp-in-string
4576 (rx (or (: string-start (* (any whitespace ?\r ?\n)))
4577 (: (* (any whitespace ?\r ?\n)) string-end)))
4579 string))
4581 (defun python-util-valid-regexp-p (regexp)
4582 "Return non-nil if REGEXP is valid."
4583 (ignore-errors (string-match regexp "") t))
4586 (defun python-electric-pair-string-delimiter ()
4587 (when (and electric-pair-mode
4588 (memq last-command-event '(?\" ?\'))
4589 (let ((count 0))
4590 (while (eq (char-before (- (point) count)) last-command-event)
4591 (cl-incf count))
4592 (= count 3))
4593 (eq (char-after) last-command-event))
4594 (save-excursion (insert (make-string 2 last-command-event)))))
4596 (defvar electric-indent-inhibit)
4598 ;;;###autoload
4599 (define-derived-mode python-mode prog-mode "Python"
4600 "Major mode for editing Python files.
4602 \\{python-mode-map}"
4603 (set (make-local-variable 'tab-width) 8)
4604 (set (make-local-variable 'indent-tabs-mode) nil)
4606 (set (make-local-variable 'comment-start) "# ")
4607 (set (make-local-variable 'comment-start-skip) "#+\\s-*")
4609 (set (make-local-variable 'parse-sexp-lookup-properties) t)
4610 (set (make-local-variable 'parse-sexp-ignore-comments) t)
4612 (set (make-local-variable 'forward-sexp-function)
4613 'python-nav-forward-sexp)
4615 (set (make-local-variable 'font-lock-defaults)
4616 '(python-font-lock-keywords
4617 nil nil nil nil
4618 (font-lock-syntactic-face-function
4619 . python-font-lock-syntactic-face-function)))
4621 (set (make-local-variable 'syntax-propertize-function)
4622 python-syntax-propertize-function)
4624 (set (make-local-variable 'indent-line-function)
4625 #'python-indent-line-function)
4626 (set (make-local-variable 'indent-region-function) #'python-indent-region)
4627 ;; Because indentation is not redundant, we cannot safely reindent code.
4628 (set (make-local-variable 'electric-indent-inhibit) t)
4629 (set (make-local-variable 'electric-indent-chars)
4630 (cons ?: electric-indent-chars))
4632 ;; Add """ ... """ pairing to electric-pair-mode.
4633 (add-hook 'post-self-insert-hook
4634 #'python-electric-pair-string-delimiter 'append t)
4636 (set (make-local-variable 'paragraph-start) "\\s-*$")
4637 (set (make-local-variable 'fill-paragraph-function)
4638 #'python-fill-paragraph)
4640 (set (make-local-variable 'beginning-of-defun-function)
4641 #'python-nav-beginning-of-defun)
4642 (set (make-local-variable 'end-of-defun-function)
4643 #'python-nav-end-of-defun)
4645 (add-hook 'completion-at-point-functions
4646 #'python-completion-at-point nil 'local)
4648 (add-hook 'post-self-insert-hook
4649 #'python-indent-post-self-insert-function 'append 'local)
4651 (set (make-local-variable 'imenu-create-index-function)
4652 #'python-imenu-create-index)
4654 (set (make-local-variable 'add-log-current-defun-function)
4655 #'python-info-current-defun)
4657 (add-hook 'which-func-functions #'python-info-current-defun nil t)
4659 (set (make-local-variable 'skeleton-further-elements)
4660 '((abbrev-mode nil)
4661 (< '(backward-delete-char-untabify (min python-indent-offset
4662 (current-column))))
4663 (^ '(- (1+ (current-indentation))))))
4665 (set (make-local-variable 'eldoc-documentation-function)
4666 #'python-eldoc-function)
4668 (add-to-list 'hs-special-modes-alist
4669 `(python-mode "^\\s-*\\(?:def\\|class\\)\\>" nil "#"
4670 ,(lambda (_arg)
4671 (python-nav-end-of-defun))
4672 nil))
4674 (set (make-local-variable 'outline-regexp)
4675 (python-rx (* space) block-start))
4676 (set (make-local-variable 'outline-heading-end-regexp) ":[^\n]*\n")
4677 (set (make-local-variable 'outline-level)
4678 #'(lambda ()
4679 "`outline-level' function for Python mode."
4680 (1+ (/ (current-indentation) python-indent-offset))))
4682 (python-skeleton-add-menu-items)
4684 (make-local-variable 'python-shell-internal-buffer)
4686 (when python-indent-guess-indent-offset
4687 (python-indent-guess-indent-offset)))
4690 (provide 'python)
4692 ;; Local Variables:
4693 ;; coding: utf-8
4694 ;; indent-tabs-mode: nil
4695 ;; End:
4697 ;;; python.el ends here