| blob | 620ea8cd51966ab2e4ee5c23fc47e6f2a0850b11 |
1 ;;; python.el --- silly walks for Python -*- coding: iso-8859-1 -*-
3 ;; Copyright (C) 2003-2012 Free Software Foundation, Inc.
5 ;; Author: Dave Love <fx@gnu.org>
6 ;; Maintainer: FSF
7 ;; Created: Nov 2003
8 ;; Keywords: languages
10 ;; This file is part of GNU Emacs.
12 ;; GNU Emacs is free software: you can redistribute it and/or modify
13 ;; it under the terms of the GNU General Public License as published by
14 ;; the Free Software Foundation, either version 3 of the License, or
15 ;; (at your option) any later version.
17 ;; GNU Emacs is distributed in the hope that it will be useful,
18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 ;; GNU General Public License for more details.
22 ;; You should have received a copy of the GNU General Public License
23 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
25 ;;; Commentary:
27 ;; Major mode for editing Python, with support for inferior processes.
29 ;; There is another Python mode, python-mode.el:
30 ;; http://launchpad.net/python-mode
31 ;; used by XEmacs, and originally maintained with Python.
32 ;; That isn't covered by an FSF copyright assignment (?), unlike this
33 ;; code, and seems not to be well-maintained for Emacs (though I've
34 ;; submitted fixes). This mode is rather simpler and is better in
35 ;; other ways. In particular, using the syntax functions with text
36 ;; properties maintained by font-lock makes it more correct with
37 ;; arbitrary string and comment contents.
39 ;; This doesn't implement all the facilities of python-mode.el. Some
40 ;; just need doing, e.g. catching exceptions in the inferior Python
41 ;; buffer (but see M-x pdb for debugging). [Actually, the use of
42 ;; `compilation-shell-minor-mode' now is probably enough for that.]
43 ;; Others don't seem appropriate. For instance,
44 ;; `forward-into-nomenclature' should be done separately, since it's
45 ;; not specific to Python, and I've installed a minor mode to do the
46 ;; job properly in Emacs 23. [CC mode 5.31 contains an incompatible
47 ;; feature, `subword-mode' which is intended to have a similar
48 ;; effect, but actually only affects word-oriented keybindings.]
50 ;; Other things seem more natural or canonical here, e.g. the
51 ;; {beginning,end}-of-defun implementation dealing with nested
52 ;; definitions, and the inferior mode following `cmuscheme'. (The
53 ;; inferior mode can find the source of errors from
54 ;; `python-send-region' & al via `compilation-shell-minor-mode'.)
55 ;; There is (limited) symbol completion using lookup in Python and
56 ;; Eldoc support also using the inferior process. Successive TABs
57 ;; cycle between possible indentations for the line.
59 ;; Even where it has similar facilities, this mode is incompatible
60 ;; with python-mode.el in some respects. For instance, various key
61 ;; bindings are changed to obey Emacs conventions.
63 ;; TODO: See various Fixmes below.
65 ;; Fixme: This doesn't support (the nascent) Python 3 .
67 ;;; Code:
75 "Silly walks in the Python language."
79 \f
80 ;;;###autoload
82 ;;;###autoload
84 ;;;###autoload
86 \f
87 ;;;; Font lock
91 ;; From v 2.7 reference, § keywords.
92 ;; def and class dealt with separately below
97 ;; Not real keywords, but close enough to be fontified as such
99 ;; Python 3
101 symbol-end)
103 . font-lock-constant-face)
104 ;; Definitions
109 ;; Top-level assignments are worth highlighting.
113 ;; Decorators.
117 ;; Built-ins. (The next three blocks are from
118 ;; `__builtin__.__dict__.keys()' in Python 2.7) These patterns
119 ;; are debatable, but they at least help to spot possible
120 ;; shadowing of builtins.
122 ;; exceptions
137 ;; Python 2.7
139 . font-lock-type-face)
142 ;; callable built-ins, fontified when not appearing as
143 ;; object attributes
156 ;; Python 2.7.
161 ;; other built-ins
164 symbol-end)
165 . font-lock-builtin-face)))
168 ;; Make outer chars of matching triple-quote sequences into generic
169 ;; string delimiters. Fixme: Is there a better way?
170 ;; First avoid a sequence preceded by an odd number of backslashes.
176 ;; This doesn't really help.
177 ;;((rx (and ?\\ (group ?\n))) (1 " "))
178 ))
181 "Put `syntax-table' property correctly on triple quote.
182 Used for syntactic keywords. N is the match number (1, 2 or 3)."
183 ;; Given a triple quote, we have to check the context to know
184 ;; whether this is an opening or closing triple or whether it's
185 ;; quoted anyhow, and should be ignored. (For that we need to do
186 ;; the same job as `syntax-ppss' to be correct and it seems to be OK
187 ;; to use it here despite initial worries.) We also have to sort
188 ;; out a possible prefix -- well, we don't _have_ to, but I think it
189 ;; should be treated as part of the string.
191 ;; Test cases:
192 ;; ur"""ar""" x='"' # """
193 ;; x = ''' """ ' a
194 ;; '''
195 ;; x '"""' x """ \"""" x
201 ;; Consider property for the last char if in a fenced string.
204 ;; Is it a matching sequence?
209 ;; Consider property for initial char, accounting for prefixes.
213 ;; Consider property for initial char, accounting for prefixes.
216 )))
218 ;; This isn't currently in `font-lock-defaults' as probably not worth
219 ;; it -- we basically only mess with a few normally-symbol characters.
221 ;; (defun python-font-lock-syntactic-face-function (state)
222 ;; "`font-lock-syntactic-face-function' for Python mode.
223 ;; Returns the string or comment face as usual, with side effect of putting
224 ;; a `syntax-table' property on the inside of the string or comment which is
225 ;; the standard syntax table."
226 ;; (if (nth 3 state)
227 ;; (save-excursion
228 ;; (goto-char (nth 8 state))
229 ;; (condition-case nil
230 ;; (forward-sexp)
231 ;; (error nil))
232 ;; (put-text-property (1+ (nth 8 state)) (1- (point))
233 ;; 'syntax-table (standard-syntax-table))
234 ;; 'font-lock-string-face)
235 ;; (put-text-property (1+ (nth 8 state)) (line-end-position)
236 ;; 'syntax-table (standard-syntax-table))
237 ;; 'font-lock-comment-face))
238 \f
239 ;;;; Keymap and syntax
243 ;; Mostly taken from python-mode.el.
265 map global-map)
275 "-"
280 "-"
289 "-"
294 "-"
312 "-"
321 map))
322 ;; Fixme: add toolbar stuff for useful things like symbol help, send
323 ;; region, at least. (Shouldn't be specific to Python, obviously.)
324 ;; eric has items including: (un)indent, (un)comment, restart script,
325 ;; run script, debug script; also things for profiling, unit testing.
329 ;; Give punctuation syntax to ASCII that normally has symbol
330 ;; syntax or has word syntax and isn't a letter.
339 ;; exceptions
344 table))
345 \f
346 ;;;; Utility stuff
349 "Return non-nil if point is in a Python literal (a comment or string)."
350 ;; We don't need to save the match data.
356 table)
360 "Skip comments and blank lines.
361 BACKWARD non-nil means go backwards, otherwise go forwards.
362 Backslash is treated as whitespace so that continued blank lines
363 are skipped. Doesn't move out of comments -- should be outside
364 or at end of line."
366 ;; If we're in a comment (including on the trailing
367 ;; newline), forward-comment doesn't move backwards out
368 ;; of it. Don't set the syntax table round this bit!
378 "Non-nil if preceding line ends with backslash that is not in a comment."
383 "Return non-nil if current line continues a previous one.
384 The criteria are that the previous line ends in a backslash outside
385 comments and strings, or that point is within brackets/parens."
398 "Return non-nil if and only if current line has only a comment."
406 "Return non-nil if and only if current line is blank."
412 "Go to beginning of string around point.
413 Do nothing if not in string."
419 "Return non-nil if statement at point opens a block.
420 BOS non-nil means point is known to be at beginning of statement."
425 symbol-end)))))
428 "Return non-nil if current line is a statement closing a block.
429 BOS non-nil means point is at beginning of statement.
430 The criteria are that the line isn't a comment or in string and
431 starts with keyword `raise', `break', `continue' or `pass'."
436 symbol-end))))
439 "Return non-nil if current line should outdent a level."
443 symbol-end)))
445 ;; Ensure there's a previous statement and move to it.
448 ;; Fixme: check this
450 \f
451 ;;;; Indentation.
454 "Number of columns for a unit of indentation in Python mode.
461 "Non-nil means Python mode guesses `python-indent' for the buffer."
466 "Non-nil means indent contents of multi-line strings together.
467 This means indent them the same as the preceding non-blank line.
468 Otherwise preserve their indentation.
470 This only applies to `doc' strings, i.e. those that form statements;
471 the indentation is preserved in others."
477 "Non-nil means indent relative to preceding comment line.
478 Only do this for comments where the leading comment character is
479 followed by space. This doesn't apply to comment lines, which
480 are always indented in lines with preceding comments."
485 "Number of columns of additional indentation for continuation lines.
486 Continuation lines follow a backslash-terminated line starting a
487 statement."
493 "Controls whether the pdbtrack feature is enabled or not.
495 When non-nil, pdbtrack is enabled in all comint-based buffers,
496 e.g. shell interaction buffers and the *Python* buffer.
498 When using pdb to debug a Python program, pdbtrack notices the
499 pdb prompt and presents the line in the source file where the
500 program is stopped in a pop-up buffer. It's similar to what
501 gud-mode does for debugging C programs with gdb, but without
502 having to restart the program."
508 "Minor-mode sign to be displayed when pdbtrack is active."
512 ;; Add a designator to the minor mode strings
515 minor-mode-alist))
520 "Alist of Python input prompts.
521 Each element has the form (PROGRAM . REGEXP), where PROGRAM is
522 the value of `python-python-command' for the python process and
523 REGEXP is a regular expression matching the Python prompt.
524 PROGRAM can also be t, which specifies the default when no other
525 element matches `python-python-command'."
533 "Alist of Python continued-line prompts.
534 Each element has the form (PROGRAM . REGEXP), where PROGRAM is
535 the value of `python-python-command' for the python process and
536 REGEXP is a regular expression matching the Python prompt for
537 continued lines.
538 PROGRAM can also be t, which specifies the default when no other
539 element matches `python-python-command'."
557 "Guess step for indentation of current buffer.
558 Set `python-indent' locally to the value guessed."
568 line-end))
583 indent)))))
585 ;; Alist of possible indentations and start of statement they would
586 ;; close. Used in indentation cycling (below).
589 ;; Length of the above
592 ;; Current index into the alist.
597 "Calculate Python indentation for line at point."
603 start)
608 ;; Only respect `python-indent-string-contents' in doc
609 ;; strings (defined as those which form statements).
615 ;; Find indentation of preceding non-blank line within string.
627 ;; Inside bracketed expression.
630 ;; Look for first item in list (preceding point) and
631 ;; align with it, if found.
639 ;; Extra level if we're backslash-continued or
640 ;; following a key.
644 ;; Otherwise indent relative to statement start, one
645 ;; level per bracketing level.
649 ;; Otherwise backslash-continued.
652 ;; We're past first continuation line. Align with
653 ;; previous line.
655 ;; First continuation line. Indent one step, with an
656 ;; extra one if statement opens a block.
660 python-indent
663 ;; Fixme: Like python-mode.el; not convinced by this.
668 ;; Back over whitespace, newlines, non-indentable comments.
673 ;; Now at start of comment -- trailing one?
675 nil)
676 ;; Indentable comment, like python-mode.el?
681 ;; Else skip it (loop).
685 ;; Prefer to indent comments with an immediately-following
686 ;; statement, e.g.
687 ;; ...
688 ;; # ...
689 ;; def ...
700 ;;;; Cycling through the possible indentations with successive TABs.
702 ;; These don't need to be buffer-local since they're only relevant
703 ;; during a cycle.
706 "Text of line following indentation and ignoring any trailing comment."
721 "Alist of keyword matches.
722 The car of an element is a keyword introducing a statement which
726 "Return first word (actually symbol) on the line."
732 "Return a list of possible indentations for this line.
733 It is assumed not to be a continuation line or in a multi-line string.
734 Includes the default indentation and those which would close all
735 enclosing blocks. Elements of the list are actually pairs:
736 \(INDENTATION . TEXT), where TEXT is the initial text of the
737 corresponding block opening (or nil)."
740 levels indent)
741 ;; Only one possibility immediately following a block open
742 ;; statement, assuming it doesn't have a `suite' on the same line.
747 ;; Check we don't have something like:
748 ;; if ...: ...
754 ;; Only one possibility for comment line immediately following
755 ;; another.
761 ;; Fixme: Maybe have a case here which indents (only) first
762 ;; line after a lambda.
766 ;; Is this a valid indentation for the line of interest?
768 ;; Check for things like:
769 ;; if ...: ...
770 ;; else ...:
771 ;; where the second line need not be outdented.
774 python-block-pairs)))))
775 ;; Not sensible to indent to the same level as
776 ;; previous `return' &c.
779 levels))
785 levels))))))
790 ;; This is basically what `python-indent-line' would be if we didn't
791 ;; do the cycling.
793 "Subroutine of `python-indent-line'.
794 Does non-repeated indentation. LEAVE non-nil means leave
795 indentation if it is valid, i.e. one of the positions returned by
796 `python-calculate-indentation'."
800 ;; Maybe keep a valid indentation.
812 "Indent current line as Python code.
813 When invoked via `indent-for-tab-command', cycle through possible
814 indentations for current line. The cycle is broken by a command
815 different from `indent-for-tab-command', i.e. successive TABs do
816 the cycling."
829 python-indent-list))))
836 "`indent-region-function' for Python.
837 Leaves validly-indented lines alone, i.e. doesn't indent to
838 another valid position."
851 "Non-nil if this is a line in a statement closing a block,
852 or a blank line indented to where it would close a block."
859 \f
860 ;;;; Movement.
862 ;; Fixme: Define {for,back}ward-sexp-function? Maybe skip units like
863 ;; block, statement, depending on context.
866 "`beginning-of-defun-function' for Python.
867 Finds beginning of innermost nested class or method definition.
868 Returns the name of the definition found at the end, or nil if
869 reached start of buffer."
877 ;; Treat bol at beginning of function as outside function so
878 ;; that successive C-M-a makes progress backwards.
879 ;;(setq def-line (looking-at def-re))
883 ;; Must be less indented or matching top level, or
884 ;; equally indented if we started on a definition line.
888 ;; Not sure why it was like this -- fails in case of
889 ;; last internal function followed by first
890 ;; non-def statement of the main body.
891 ;; (and def-line (= in ci))
896 found))
899 "`end-of-defun-function' for Python.
900 Finds end of innermost nested class or method definition."
903 ;; Go to start of current block and check whether it's at top
904 ;; level. If it is, and not a block start, look forward for
905 ;; definition statement.
917 ;; Don't move before top-level statement that would end defun.
920 ;; If we got to the start of buffer, look forward for
921 ;; definition statement.
926 ;; We're at a definition statement (or end-of-buffer).
929 ;; Count trailing space in defun (but not trailing comments).
933 ;; Catch pathological cases like this, where the beginning-of-defun
934 ;; skips to a definition we're not in:
935 ;; if ...:
936 ;; ...
937 ;; else:
938 ;; ... # point here
939 ;; ...
940 ;; def ...
945 "Go to start of current statement.
946 Accounts for continuation lines, multi-line strings, and
947 multi-line bracketed expressions."
957 "Skip out of any nested brackets.
958 Skip forward if FORWARD is non-nil, else backward.
959 If SYNTAX is non-nil it is the state returned by `syntax-ppss' at point.
960 Return non-nil if and only if skipping was done."
961 ;; FIXME: Use syntax-ppss-toplevel-pos.
966 ;; Skip forward out of nested brackets.
970 ;; Invalid syntax (too many closed brackets).
971 ;; Skip out of as many as possible.
977 done)))))
980 "Go to the end of the current statement and return point.
981 Usually this is the start of the next line, but if this is a
982 multi-line statement we need to skip over the continuation lines.
983 On a comment line, go to end of line."
986 ;; Move past any enclosing strings and sexps, or stop if
987 ;; we're in a comment.
991 nil)
993 ;; Go to start of string and skip it.
998 ;; If there's a mismatched string, make sure
999 ;; we still overall move *forward*.
1010 "Go to start of previous statement.
1011 With argument COUNT, do it COUNT times. Stop at beginning of buffer.
1012 Return count of statements left to move."
1022 count))
1025 "Go to start of next statement.
1026 With argument COUNT, do it COUNT times. Stop at end of buffer.
1027 Return count of statements left to move."
1041 count))
1044 "Go to start of current block.
1045 With numeric arg, do it that many times. If ARG is negative, call
1046 `python-end-of-block' instead.
1047 If point is on the first line of a block, use its outer block.
1048 If current statement is in column zero, don't move and return nil.
1049 Otherwise return non-nil."
1064 ;; Look upwards for less indented statement.
1066 ;;; This is slower than the below.
1067 ;;; (while (zerop (python-previous-statement))
1068 ;;; (when (and (< (current-indentation) ci)
1069 ;;; (python-open-block-statement-p t))
1070 ;;; (beginning-of-line)
1071 ;;; (throw 'done t)))
1075 ;; Move to beginning to save effort in case
1076 ;; this is in string.
1085 "Go to end of current block.
1086 With numeric arg, do it that many times. If ARG is negative,
1087 call `python-beginning-of-block' instead.
1088 If current statement is in column zero and doesn't open a block,
1089 don't move and return nil. Otherwise return t."
1118 function-name))
1120 \f
1121 ;;;; Imenu.
1123 ;; For possibly speeding this up, here's the top of the ELP profile
1124 ;; for rescanning pydoc.py (2.2k lines, 90kb):
1125 ;; Function Name Call Count Elapsed Time Average Time
1126 ;; ==================================== ========== ============= ============
1127 ;; python-imenu-create-index 156 2.430906 0.0155827307
1128 ;; python-end-of-defun 155 1.2718260000 0.0082053290
1129 ;; python-end-of-block 155 1.1898689999 0.0076765741
1130 ;; python-next-statement 2970 1.024717 0.0003450225
1131 ;; python-end-of-statement 2970 0.4332190000 0.0001458649
1132 ;; python-beginning-of-defun 265 0.0918479999 0.0003465962
1133 ;; python-skip-comments/blanks 3125 0.0753319999 2.410...e-05
1137 "`imenu-create-index-function' for Python.
1139 Makes nested Imenu menus from nested `class' and `def' statements.
1140 The nested menus are headed by an item referencing the outer
1141 definition; it has a space prepended to the name so that it sorts
1142 first with `imenu--sort-by-name' (though, unfortunately, sub-menus
1143 precede it)."
1145 ;; Normal call from Imenu.
1147 ;; Without this, we can get an infloop if the buffer isn't all
1148 ;; fontified. I guess this is really a bug in syntax.el. OTOH,
1149 ;; _with_ this, imenu doesn't immediately work; I can't figure out
1150 ;; what's going on, but it must be something to do with timers in
1151 ;; font-lock.
1152 ;; This can't be right, especially not when jit-lock is not used. --Stef
1153 ;; (unless (get-text-property (1- (point-max)) 'fontified)
1154 ;; (font-lock-fontify-region (point-min) (point-max)))
1155 )
1161 nil t)
1176 ;; Look for module variables.
1181 nil t)
1184 vars)))
1189 index-alist))))
1190 index-alist))
1191 \f
1192 ;;;; `Electric' commands.
1195 "Insert a colon and maybe outdent the line if it is a statement like `else'.
1197 just insert a single colon."
1209 "Maybe delete a level of indentation on the current line.
1210 Do so if point is at the end of the line's indentation outside
1211 strings and comments.
1212 Otherwise just call `backward-delete-char-untabify'.
1213 Repeat ARG times."
1220 ;; Look for the largest valid indentation which is smaller than
1221 ;; the current indentation.
1225 initial)
1235 \f
1236 ;;;; pychecker
1239 "Command used to check a Python file."
1246 ;; After `sgml-validate-command'.
1248 "Check a Python file (default current buffer's file).
1249 Runs COMMAND, a shell command, as if by `compile'.
1250 See `python-check-command' for the default."
1263 compilation-error-regexp-alist)))
1265 \f
1266 ;;;; Inferior mode stuff (following cmuscheme).
1269 "Shell command to run Python interpreter.
1270 Any arguments can't contain whitespace."
1275 "Shell command to run Jython interpreter.
1276 Any arguments can't contain whitespace."
1281 "Actual command used to run Python.
1282 May be `python-python-command' or `python-jython-command', possibly
1283 modified by the user. Additional arguments are added when the command
1287 "The current Python process buffer.
1289 Commands that send text from source buffers to Python processes have
1290 to choose a process to send to. This is determined by buffer-local
1291 value of `python-buffer'. If its value in the current buffer,
1292 i.e. both any local value and the default one, is nil, `run-python'
1293 and commands that send to the Python process will start a new process.
1296 value of `python-buffer' to be the new process's buffer and sets the
1297 buffer-local value similarly if the current buffer is in Python mode
1298 or Inferior Python mode, so that source buffer stays associated with a
1299 specific sub-process.
1306 ;; FIXME: maybe these should move to compilation-error-regexp-alist-alist.
1307 ;; The first already is (for CAML), but the second isn't. Anyhow,
1308 ;; these are specific to the inferior buffer. -- fx
1316 ;; pdb stack trace
1324 ;; This will inherit from comint-mode-map.
1327 ;; Note that we _can_ still use these commands which send to the
1328 ;; Python process even at the prompt if we have a normal prompt,
1329 ;; i.e. '>>> ' and not '... '. See the comment before
1330 ;; python-send-region. Fixme: uncomment these if we address that.
1332 ;; (define-key map [(meta ?\t)] 'python-complete-symbol)
1333 ;; (define-key map "\C-c\C-f" 'python-describe-symbol)
1334 map))
1338 ;; Don't get confused by apostrophes in the process's output (e.g. if
1339 ;; you execute "help(os)").
1341 ;; Maybe we should do the same for double quotes?
1342 ;; (modify-syntax-entry ?\" "." st)
1343 st))
1345 ;; Autoloaded.
1352 python-shell-prompt-alist)
1355 python-shell-continuation-prompt-alist)
1365 ;; Fixme: This should inherit some stuff from `python-mode', but I'm
1366 ;; not sure how much: at least some keybindings, like C-c C-f;
1367 ;; syntax?; font-locking, e.g. for triple-quoted strings?
1369 "Major mode for interacting with an inferior Python process.
1372 Hooks `comint-mode-hook' and `inferior-python-mode-hook' are run in
1373 that order.
1375 You can send text to the inferior Python process from other buffers
1376 containing Python source.
1378 process buffer.
1381 after sending the text.
1382 For running multiple processes in multiple buffers, see `run-python' and
1383 `python-buffer'.
1390 nil t)
1393 python-compilation-regexp-alist)
1397 "Input matching this regexp is not saved on the history list.
1398 Default ignores all inputs of 0, 1, or 2 non-blank characters."
1403 "Whether to allow loading of Python modules from the current directory.
1404 If this is non-nil, Emacs removes '' from sys.path when starting
1405 an inferior Python process. This is the default, for security
1406 reasons, as it is easy for the Python process to be started
1407 without the user's realization (e.g. to perform completion)."
1413 "`comint-input-filter' function for inferior Python.
1414 Don't save anything for STR matching `inferior-python-filter-regexp'."
1417 ;; Fixme: Loses with quoted whitespace.
1436 ;; Using this stops us getting lines in the buffer like
1437 ;; >>> ... ... >>>
1438 ;; Also look for (and delete) an `_emacs_ok' string and call
1439 ;; `python-preoutput-continuation' if we get it.
1441 "`comint-preoutput-filter-functions' function: ignore prompts not at bol."
1447 ;; First process whole lines.
1450 ;; Skip prompt if needed.
1455 ;; Recognize special _emacs_out lines.
1462 ;; Then process the remaining partial line.
1465 ;; Drop this prompt if it follows an _emacs_out...
1467 ;; ... or if it's not gonna be inserted at BOL.
1468 ;; Maybe we could be more selective here.
1472 ;; The need for this seems to be system-dependent:
1473 ;; What is this all about, exactly? --Stef
1474 ;; (if (and (eq ?. (aref s 0)))
1475 ;; (accept-process-output (get-buffer-process (current-buffer)) 1))
1477 res)
1480 ;; The leftover string is a prefix of _emacs_out so we don't know
1481 ;; yet whether it's an _emacs_out or something else: wait until we
1482 ;; get more output so we can resolve this ambiguity.
1484 res)
1489 "Check that CMD runs a suitable version of Python."
1490 ;; Fixme: Check on Jython.
1493 cmd)))
1504 ;;;###autoload
1506 "Run an inferior Python process, input and output via buffer *Python*.
1507 CMD is the Python command to run. NOSHOW non-nil means don't
1508 show the buffer automatically.
1510 Interactively, a prefix arg means to prompt for the initial
1511 Python command line (default is `python-command').
1513 A new process is started if one isn't running attached to
1514 `python-buffer', or if called from Lisp with non-nil arg NEW.
1515 Otherwise, if a process is already running in `python-buffer',
1516 switch to that buffer.
1518 This command runs the hook `inferior-python-mode-hook' after
1520 process buffer for a list of commands.
1522 By default, Emacs inhibits the loading of Python modules from the
1523 current working directory, for security reasons. To disable this
1524 behavior, change `python-remove-cwd-from-path' to nil."
1531 ;; Fixme: Consider making `python-buffer' buffer-local as a buffer
1532 ;; (not a name) in Python buffers from which `run-python' &c is
1533 ;; invoked. Would support multiple processes better.
1544 data-directory)
1545 process-environment))
1546 ;; If we use a pipe, Unicode characters are not printed
1547 ;; correctly (Bug#5794) and IPython does not work at
1548 ;; all (Bug#5390).
1557 ;; Load function definitions we need.
1558 ;; Before the preoutput function was used, this was done via -c in
1559 ;; cmdlist, but that loses the banner and doesn't run the startup
1560 ;; file. The code might be inline here, but there's enough that it
1561 ;; seems worth putting in a separate file, and it's probably cleaner
1562 ;; to put it in a module.
1563 ;; Ensure we're at a prompt before doing anything else.
1565 ;; The following line was meant to ensure that we're at a prompt
1566 ;; before doing anything else. However, this can cause Emacs to
1567 ;; hang waiting for a response, if that Python function fails
1568 ;; (i.e. raises an exception).
1569 ;; (python-send-receive "print '_emacs_out ()'")
1570 ))
1573 ;; Without this, help output goes into the inferior python buffer if
1574 ;; the process isn't already running.
1579 "Like `python-send-string' but resets `compilation-shell-minor-mode'."
1588 "Send the region to the inferior Python process."
1589 ;; The region is evaluated from a temporary file. This avoids
1590 ;; problems with blank lines, which have different semantics
1591 ;; interactively and in files. It also saves the inferior process
1592 ;; buffer filling up with interpreter prompts. We need a Python
1593 ;; function to remove the temporary file when it has been evaluated
1594 ;; (though we could probably do it in Lisp with a Comint output
1595 ;; filter). This function also catches exceptions and truncates
1596 ;; tracebacks not to mention the frame of the function itself.
1597 ;;
1598 ;; The `compilation-shell-minor-mode' parsing takes care of relating
1599 ;; the reference to the temporary file to the source.
1600 ;;
1601 ;; Fixme: Write a `coding' header to the temp file if the region is
1602 ;; non-ASCII.
1606 ;; IPython puts the FakeModule module into __main__ so
1607 ;; emacs.eexecfile becomes useless.
1617 ;; Wrong if we had indented code at buffer start.
1623 ;; Tell compile.el to redirect error locations in file `f' to
1624 ;; positions past marker `orig-start'. It has to be done *after*
1625 ;; `python-send-command''s call to `compilation-forget-errors'.
1629 "Evaluate STRING in inferior Python process."
1633 ;; Make sure the text is properly LF-terminated.
1636 ;; If the string contains a final indented line, add a second newline so
1637 ;; as to make sure we terminate the multiline instruction.
1641 "Send the current buffer to the inferior Python process."
1645 ;; Fixme: Try to define the function or class within the relevant
1646 ;; module, not just at top level.
1648 "Send the current defun (class or method) to the inferior Python process."
1654 "Switch to the Python process buffer, maybe starting new process.
1655 With prefix arg, position cursor at end of buffer."
1663 "Send the region to the inferior Python process.
1664 Then switch to the process buffer."
1670 "Used to determine if a buffer contains Python source code.
1671 If a file is loaded into a buffer that is in one of these major modes,
1672 it is considered Python source by `python-load-file', which uses the
1673 value to determine defaults."
1678 "Caches (directory . file) pair used in the last `python-load-file' command.
1682 "Load a Python file FILE-NAME into the inferior Python process.
1683 If the file has extension `.py' import or reload it as a module.
1684 Treating it as a module keeps the global namespace clean, provides
1685 function location information for debugging, and supports users of
1686 module-qualified names."
1688 python-source-modes
1694 ;; Fixme: I'm not convinced by this logic from python-mode.el.
1705 "Return the current Python process.
1706 See variable `python-buffer'. Starts a new process if necessary."
1707 ;; Fixme: Maybe should look for another active process if there
1708 ;; isn't one for `python-buffer'.
1713 python-buffer)))
1716 "Set the default value of `python-buffer' to correspond to this buffer.
1717 If the current buffer has a local value of `python-buffer', set the
1718 default (global) value to that. The associated Python process is
1720 in a buffer that doesn't have a local value of `python-buffer'."
1725 \f
1726 ;;;; Context-sensitive help.
1732 table)
1733 "Syntax table giving `.' symbol syntax.
1741 ;; Fixme: Should this actually be used instead of info-look, i.e. be
1742 ;; bound to C-h S? [Probably not, since info-look may work in cases
1743 ;; where this doesn't.]
1745 "Get help on SYMBOL using `help'.
1746 Interactively, prompt for symbol.
1748 Symbol may be anything recognized by the interpreter's `help'
1749 command -- e.g. `CALLS' -- not just variables in scope in the
1750 interpreter. This only works for Python version 2.2 or newer
1751 since earlier interpreters don't support `help'.
1754 will."
1755 ;; Note that we do this in the inferior process, not a separate one, to
1756 ;; ensure the environment is appropriate.
1764 nil nil symbol))))
1766 ;; Ensure we have a suitable help buffer.
1767 ;; Fixme: Maybe process `Related help topics' a la help xrefs and
1768 ;; allow C-c C-f in help buffer.
1776 ;; Fixme: Is this actually useful?
1782 symbol python-imports)
1788 "Send STRING to inferior Python (if any) and return result.
1789 The result is what follows `_emacs_out' in the output.
1790 This is a no-op if `python-check-comint-prompt' returns nil."
1803 "Return non-nil if and only if there's a normal prompt in the inferior buffer.
1804 If there isn't, it's probably not appropriate to send input to return Eldoc
1805 information etc. If PROC is non-nil, check the buffer for that process."
1810 nil t)))))
1812 ;; Fixme: Is there anything reasonable we can do with random methods?
1813 ;; (Currently only works with functions.)
1815 "`eldoc-documentation-function' for Python.
1816 Only works when point is in a function name, not its arg list, for
1817 instance. Assumes an inferior Python is running."
1820 ;; This is run from timers, so inhibit-quit tends to be set.
1822 ;; First try the symbol we're on.
1825 symbol python-imports)))
1826 ;; Try moving to symbol before enclosing parens.
1839 python-imports))))))))))))
1840 \f
1841 ;;;; Info-look functionality.
1845 ;;;###autoload
1847 "Set up info-look for Python.
1848 Used with `eval-after-load'."
1853 ;; Whether info files have a Python version suffix, e.g. in Debian.
1858 ;; Don't use `info' because it would pop-up a *info* buffer.
1861 version))
1862 t)
1867 :doc-spec
1868 ;; Fixme: Can this reasonably be made specific to indices with
1869 ;; different rules? Is the order of indices optimal?
1870 ;; (Miscellaneous in -ref first prefers lookup of keywords, for
1871 ;; instance.)
1873 ;; The empty prefix just gets us highlighted terms.
1895 \f
1896 ;;;; Miscellany.
1899 "Packages implying `jython-mode'.
1900 If these are imported near the beginning of the buffer, `python-mode'
1901 actually punts to `jython-mode'."
1905 ;; Called from `python-mode', this causes a recursive call of the
1906 ;; mode. See logic there to break out of the recursion.
1908 "Invoke `jython-mode' if the buffer appears to contain Jython code.
1909 The criterion is either a match for `jython-mode' via
1910 `interpreter-mode-alist' or an import of a module from the list
1911 `python-jython-packages'."
1912 ;; The logic is taken from python-mode.el.
1921 interpreter)
1922 interpreter-mode-alist))))
1929 t)
1935 "`fill-paragraph-function' handling multi-line strings and possibly comments.
1936 If any of the current line is in or at the end of a multi-line string,
1937 fill the string or the paragraph of it that point is in, preserving
1938 the string's indentation."
1945 start end)
1949 ;; The `paragraph-start' and `paragraph-separate'
1950 ;; variables don't allow us to delimit the last
1951 ;; paragraph in a multi-line string properly, so narrow
1952 ;; to the string and then fill around (the end of) the
1953 ;; current line.
1972 ;; Avoid losing leading and trailing newlines in doc
1973 ;; strings written like:
1974 ;; """
1975 ;; ...
1976 ;; """
1978 ;; Note that the string could be part of an
1979 ;; expression, so it can have preceding and
1980 ;; trailing non-whitespace.
1983 ;; Opening triple quote without following text.
1987 ;; Fixme: Not sure about including
1988 ;; trailing whitespace.
1990 eol)
1991 ;; Closing trailing quote without preceding text.
1995 fill-paragraph-function)
1999 "Shift lines in region COUNT (the prefix arg) columns to the left.
2000 COUNT defaults to `python-indent'. If region isn't active, just shift
2001 current line. The region shifted includes the lines in which START and
2002 END lie. It is an error if any lines in the region are indented less than
2003 COUNT columns."
2024 "Shift lines in region COUNT (the prefix arg) columns to the right.
2025 COUNT defaults to `python-indent'. If region isn't active, just shift
2026 current line. The region shifted includes the lines in which START and
2027 END lie."
2038 "`outline-level' function for Python mode.
2039 The level is the number of `python-indent' steps of indentation
2040 of current line."
2043 ;; Fixme: Consider top-level assignments, imports, &c.
2045 "`add-log-current-defun-function' for Python."
2047 ;; Move up the tree of nested `class' and `def' blocks until we
2048 ;; get to zero indentation, accumulating the defined names.
2073 "Mark the block around point.
2074 Uses `python-beginning-of-block', `python-end-of-block'."
2082 ;; Fixme: Provide a find-function-like command to find source of a
2083 ;; definition (separate from BicycleRepairMan). Complicated by
2084 ;; finding the right qualified name.
2085 \f
2086 ;;;; Completion.
2088 ;; http://lists.gnu.org/archive/html/bug-gnu-emacs/2008-01/msg00076.html
2093 ;; Fixme: Should font-lock try to run this when it deals with an import?
2094 ;; Maybe not a good idea if it gets run multiple times when the
2095 ;; statement is being edited, and is more likely to end up with
2096 ;; something syntactically incorrect.
2097 ;; However, what we should do is to trundle up the block tree from point
2098 ;; to extract imports that appear to be in scope, and add those.
2100 "Find top-level imports, updating `python-imports'."
2108 ;; Skip over continued lines.
2111 t)
2113 lines))))
2117 ;; This is probably best left out since you're unlikely to need the
2118 ;; doc for a function in the buffer and the import will lose if the
2119 ;; Python sub-process' working directory isn't the same as the
2120 ;; buffer's.
2121 ;; (if buffer-file-name
2122 ;; (concat
2123 ;; "import "
2124 ;; (file-name-sans-extension
2125 ;; (file-name-nondirectory buffer-file-name))))
2130 ;; The output ends up in the wrong place if the string we
2131 ;; send contains newlines (from the imports).
2136 ;; Fixme: This fails the first time if the sub-process isn't already
2137 ;; running. Presumably a timing issue with i/o to the process.
2139 "Return a list of completions of the string SYMBOL from Python process.
2140 The list is sorted.
2141 Uses `python-imports' to load modules against which to complete."
2149 python-imports))))
2152 ;; We can get duplicates from the above -- don't know why.
2162 nil t)
2167 \f
2168 ;;;; FFAP support
2171 "Function for `ffap-alist' to return path to MODULE."
2176 \f
2177 ;;;; Find-function support
2179 ;; Fixme: key binding?
2182 "Find source of definition of function NAME.
2183 Interactively, prompt for name."
2191 nil nil symbol))))
2195 name python-imports)))
2204 \f
2205 ;;;; Skeletons
2208 "Non-nil means template skeletons will be automagically inserted.
2210 the if condition."
2215 "Abbrev table for Python mode."
2216 :case-fixed t
2217 ;; Allow / inside abbrevs.
2219 ;; Only expand in code.
2223 ;; Define a user-level skeleton and add it to the abbrev table.
2229 ;; Usual technique for inserting a skeleton, but expand
2230 ;; to the original abbrev instead if in a comment or string.
2233 ',function
2239 ;; From `skeleton-further-elements' set below:
2240 ;; `<': outdent a level;
2241 ;; `^': delete indentation on current line and also previous newline.
2242 ;; Not quite like `delete-indentation'. Assumes point is at
2243 ;; beginning of indentation.
2246 "Condition: "
2249 _ \n
2257 "Auxiliary skeleton."
2258 nil
2265 "Condition: "
2271 "Target, %s: "
2277 nil
2288 "Auxiliary skeleton."
2292 nil
2299 "Name: "
2306 "Name: "
2309 str)
2316 "Default template to expand by `python-expand-template'.
2320 "Expand template named NAME.
2321 Interactively, prompt for the name with completion."
2324 python-default-template)
2325 python-mode-abbrev-table nil t nil nil
2326 python-default-template)))
2334 \f
2335 ;;;; Bicycle Repair Man support
2341 ;; I'm not sure how useful BRM really is, and it's certainly dangerous
2342 ;; the way it modifies files outside Emacs... Also note that the
2343 ;; current BRM loses with tabs used for indentation -- I submitted a
2344 ;; fix <URL:http://www.loveshack.ukfsn.org/emacs/bikeemacs.py.diff>.
2346 "Set up Bicycle Repair Man refactoring tool (if available).
2348 Note that the `refactoring' features change files independently of
2349 Emacs and may modify and save the contents of the current buffer
2350 without confirmation."
2361 python-brm-menu python-mode-map
2362 "Bicycle Repair Man"
2365 "Queries"
2370 "-"
2371 "Refactoring"
2381 :help
2383 ;; Fixme: Should check for anything to revert.
2386 \f
2387 ;;;; Modes.
2389 ;; pdb tracking is alert once this file is loaded, but takes no action if
2390 ;; `python-pdbtrack-do-tracking-p' is nil.
2397 ;;;###autoload
2399 "Major mode for editing Python files.
2400 Turns on Font Lock mode unconditionally since it is currently required
2401 for correct parsing of the source.
2402 See also `jython-mode', which is actually invoked if the buffer appears to
2403 contain Jython code. See also `run-python' and associated Python mode
2404 commands for running Python under Emacs.
2407 with nested `def' and `class' blocks. They take the innermost one as
2408 current without distinguishing method and class definitions. Used multiple
2409 times, they move over others at the same indentation level until they reach
2410 the end of definitions at that level, when they move up a level.
2412 Colon is electric: it outdents the line if appropriate, e.g. for
2414 deletes a level of indentation to close the current block; otherwise it
2415 deletes a character backward. TAB indents the current line relative to
2416 the preceding code. Successive TABs, with no intervening command, cycle
2417 through the possibilities for indentation on the basis of enclosing blocks.
2420 effect outside them.
2422 Supports Eldoc mode (only for functions, using a Python process),
2423 Info-Look and Imenu. In Outline minor mode, `class' and `def'
2424 lines count as headers. Symbol completion is available in the
2425 same way as in the Python shell using the `rlcompleter' module
2426 and this is added to the Hippie Expand functions locally if
2427 Hippie Expand mode is turned on. Completion of symbols of the
2428 form x.y only works if the components are literal
2429 module/attribute names, not variables. An abbrev table is set up
2430 with skeleton expansions for compound statement templates.
2436 ;; This probably isn't worth it.
2437 ;; (font-lock-syntactic-face-function
2438 ;; . python-font-lock-syntactic-face-function)
2439 ))
2441 python-syntax-propertize-function)
2455 symbol-end))
2468 nil t)
2475 ;; Python defines TABs as being 8-char wide.
2478 ;; Let's make it harder for the user to shoot himself in the foot.
2487 ;; Not done automatically in Emacs 21 or 22.
2489 "Hook run when entering Python mode."
2495 "Turn off Indent Tabs mode."
2501 ;;;###autoload
2503 "Major mode for editing Jython files.
2504 Like `python-mode', but sets up parameters for Jython subprocesses.
2505 Runs `jython-mode-hook' after `python-mode-hook'."
2509 \f
2511 ;; pdbtrack features
2514 "Activate or deactivate arrow at beginning-of-line in current buffer."
2518 overlay-arrow-string "=>"
2519 python-pdbtrack-is-tracking-p t)
2524 python-pdbtrack-is-tracking-p nil)))
2527 "Show the file indicated by the pdb stack entry line, in a separate window.
2529 Activity is disabled if the buffer-local variable
2530 `python-pdbtrack-do-tracking-p' is nil.
2532 We depend on the pdb input prompt being a match for
2533 `python-pdbtrack-input-prompt'.
2535 If the traceback target file path is invalid, we look for the
2536 most recently visited python-mode buffer which either has the
2537 name of the current function or class, or which defines the
2538 function or class. This is to provide for scripts not in the
2539 local file system (e.g., Zope's 'Script \(Python)', but it's not
2540 Zope specific). If you put a copy of the script in a buffer
2541 named for the script and activate python-mode, then pdbtrack will
2542 find it."
2543 ;; Instead of trying to piece things together from partial text
2544 ;; (which can be almost useless depending on Emacs version), we
2545 ;; monitor to the point where we have the next pdb prompt, and then
2546 ;; check all text from comint-last-input-end to process-mark.
2547 ;;
2548 ;; Also, we're very conservative about clearing the overlay arrow,
2549 ;; to minimize residue. This means, for instance, that executing
2550 ;; other pdb commands wipe out the highlight. You can always do a
2551 ;; 'where' (aka 'w') PDB command to reveal the overlay arrow.
2562 python-pdbtrack-track-range))
2563 procmark))
2564 target target_fname target_lineno target_buffer)
2586 ;; in large shell buffers, above stuff may cause point to lag output
2588 )))))
2589 )
2592 "Return line number and buffer of code indicated by block's traceback text.
2594 We look first to visit the file indicated in the trace.
2596 Failing that, we look for the most recently visited python-mode buffer
2597 with the same name or having the named function.
2599 If we're unable find the source code we return a string describing the
2600 problem."
2604 "Traceback cue not found"
2611 funcbuffer)
2617 funcbuffer))
2624 ;; Add in number of lines for leading '##' comments:
2626 (+ lineno
2629 0
2636 )))))))
2645 "Find recent Python mode buffer named, or having function named FUNCNAME."
2647 buf
2648 got)
2661 got))
2663 ;; Python subprocess utilities and filters
2666 Make that process's buffer visible and force display. Also make
2667 comint believe the user typed this string so that
2668 `kill-output-from-shell' does The Right Thing."
2671 ; (comint-scroll-to-bottom-on-output t)
2673 ;; add some comment, so that we can filter it out of history
2687 ;; missing or 0 is toggle, >0 turn on, <0 turn off
2707 "Unload the Python library."
2710 minor-mode-alist))
2713 ;; continue standard unloading
2714 nil)
2716 ;;;; Finish up
2717 ;; Fixme: should be in hideshow. This seems to be of limited use
2718 ;; since it isn't (can't be) indentation-based. Also hide-level
2719 ;; doesn't seem to work properly.
2725 nil))
2730 ;;; python.el ends here