| blob | 19e9373a5ec0899b7751db8d1d07b79ca1030699 |
1 ;;; python.el --- silly walks for Python -*- coding: iso-8859-1 -*-
3 ;; Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008 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, or (at your option)
15 ;; 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; see the file COPYING. If not, write to the
24 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
25 ;; Boston, MA 02110-1301, USA.
27 ;;; Commentary:
29 ;; Major mode for editing Python, with support for inferior processes.
31 ;; There is another Python mode, python-mode.el, used by XEmacs and
32 ;; maintained with Python. That isn't covered by an FSF copyright
33 ;; assignment, unlike this code, and seems not to be well-maintained
34 ;; for Emacs (though I've submitted fixes). This mode is rather
35 ;; simpler and is better in other ways. In particular, using the
36 ;; syntax functions with text properties maintained by font-lock makes
37 ;; it more correct with 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, `c-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 ;;; Code:
76 "Silly walks in the Python language."
80 \f
81 ;;;###autoload
83 ;;;###autoload
85 ;;;###autoload
87 \f
88 ;;;; Font lock
92 ;; From v 2.5 reference, § keywords.
93 ;; def and class dealt with separately below
98 ;; Not real keywords, but close enough to be fontified as such
100 symbol-end)
102 . font-lock-constant-face)
103 ;; Definitions
108 ;; Top-level assignments are worth highlighting.
115 ;; Make outer chars of matching triple-quote sequences into generic
116 ;; string delimiters. Fixme: Is there a better way?
127 ;; This doesn't really help.
128 ;;; (,(rx (and ?\\ (group ?\n))) (1 " "))
129 ))
132 "Put `syntax-table' property correctly on triple quote.
133 Used for syntactic keywords. N is the match number (1, 2 or 3)."
134 ;; Given a triple quote, we have to check the context to know
135 ;; whether this is an opening or closing triple or whether it's
136 ;; quoted anyhow, and should be ignored. (For that we need to do
137 ;; the same job as `syntax-ppss' to be correct and it seems to be OK
138 ;; to use it here despite initial worries.) We also have to sort
139 ;; out a possible prefix -- well, we don't _have_ to, but I think it
140 ;; should be treated as part of the string.
142 ;; Test cases:
143 ;; ur"""ar""" x='"' # """
144 ;; x = ''' """ ' a
145 ;; '''
146 ;; x '"""' x """ \"""" x
147 ;; Fixme: """""" goes wrong (due to syntax-ppss not getting the string
148 ;; fence context).
152 ;; Consider property for the last char if in a fenced string.
159 ;; Is it a matching sequence?
162 ;; Consider property for initial char, accounting for prefixes.
170 ;; Otherwise (we're in a non-matching string) the property is
171 ;; nil, which is OK.
172 )))
174 ;; This isn't currently in `font-lock-defaults' as probably not worth
175 ;; it -- we basically only mess with a few normally-symbol characters.
177 ;; (defun python-font-lock-syntactic-face-function (state)
178 ;; "`font-lock-syntactic-face-function' for Python mode.
179 ;; Returns the string or comment face as usual, with side effect of putting
180 ;; a `syntax-table' property on the inside of the string or comment which is
181 ;; the standard syntax table."
182 ;; (if (nth 3 state)
183 ;; (save-excursion
184 ;; (goto-char (nth 8 state))
185 ;; (condition-case nil
186 ;; (forward-sexp)
187 ;; (error nil))
188 ;; (put-text-property (1+ (nth 8 state)) (1- (point))
189 ;; 'syntax-table (standard-syntax-table))
190 ;; 'font-lock-string-face)
191 ;; (put-text-property (1+ (nth 8 state)) (line-end-position)
192 ;; 'syntax-table (standard-syntax-table))
193 ;; 'font-lock-comment-face))
194 \f
195 ;;;; Keymap and syntax
199 ;; Mostly taken from python-mode.el.
220 map global-map)
230 "-"
235 "-"
244 "-"
251 "-"
269 "-"
276 map))
277 ;; Fixme: add toolbar stuff for useful things like symbol help, send
278 ;; region, at least. (Shouldn't be specific to Python, obviously.)
279 ;; eric has items including: (un)indent, (un)comment, restart script,
280 ;; run script, debug script; also things for profiling, unit testing.
284 ;; Give punctuation syntax to ASCII that normally has symbol
285 ;; syntax or has word syntax and isn't a letter.
294 ;; exceptions
299 table))
300 \f
301 ;;;; Utility stuff
304 "Return non-nil if point is in a Python literal (a comment or string)."
305 ;; We don't need to save the match data.
311 table)
315 "Skip comments and blank lines.
316 BACKWARD non-nil means go backwards, otherwise go forwards.
317 Backslash is treated as whitespace so that continued blank lines
318 are skipped. Doesn't move out of comments -- should be outside
319 or at end of line."
321 ;; If we're in a comment (including on the trailing
322 ;; newline), forward-comment doesn't move backwards out
323 ;; of it. Don't set the syntax table round this bit!
333 "Non-nil if preceding line ends with backslash that is not in a comment."
338 "Return non-nil if current line continues a previous one.
339 The criteria are that the previous line ends in a backslash outside
340 comments and strings, or that point is within brackets/parens."
353 "Return non-nil iff current line has only a comment."
361 "Return non-nil iff current line is blank."
367 "Go to beginning of string around point.
368 Do nothing if not in string."
374 "Return non-nil if statement at point opens a block.
375 BOS non-nil means point is known to be at beginning of statement."
380 symbol-end)))))
383 "Return non-nil if current line is a statement closing a block.
384 BOS non-nil means point is at beginning of statement.
385 The criteria are that the line isn't a comment or in string and
386 starts with keyword `raise', `break', `continue' or `pass'."
391 symbol-end))))
394 "Return non-nil if current line should outdent a level."
398 symbol-end)))
400 ;; Ensure there's a previous statement and move to it.
403 ;; Fixme: check this
405 \f
406 ;;;; Indentation.
409 "Number of columns for a unit of indentation in Python mode.
416 "Non-nil means Python mode guesses `python-indent' for the buffer."
421 "Non-nil means indent contents of multi-line strings together.
422 This means indent them the same as the preceding non-blank line.
423 Otherwise preserve their indentation.
425 This only applies to `doc' strings, i.e. those that form statements;
426 the indentation is preserved in others."
432 "Non-nil means indent relative to preceding comment line.
433 Only do this for comments where the leading comment character is
434 followed by space. This doesn't apply to comment lines, which
435 are always indented in lines with preceding comments."
440 "Number of columns of additional indentation for continuation lines.
441 Continuation lines follow a backslash-terminated line starting a
442 statement."
447 "Guess step for indentation of current buffer.
448 Set `python-indent' locally to the value guessed."
458 line-end))
473 indent)))))
475 ;; Alist of possible indentations and start of statement they would
476 ;; close. Used in indentation cycling (below).
479 ;; Length of the above
482 ;; Current index into the alist.
487 "Calculate Python indentation for line at point."
493 start)
498 ;; Only respect `python-indent-string-contents' in doc
499 ;; strings (defined as those which form statements).
505 ;; Find indentation of preceding non-blank line within string.
517 ;; Inside bracketed expression.
520 ;; Look for first item in list (preceding point) and
521 ;; align with it, if found.
529 ;; Extra level if we're backslash-continued or
530 ;; following a key.
534 ;; Otherwise indent relative to statement start, one
535 ;; level per bracketing level.
539 ;; Otherwise backslash-continued.
542 ;; We're past first continuation line. Align with
543 ;; previous line.
545 ;; First continuation line. Indent one step, with an
546 ;; extra one if statement opens a block.
550 python-indent
553 ;; Fixme: Like python-mode.el; not convinced by this.
558 ;; Back over whitespace, newlines, non-indentable comments.
562 ;; not at comment start
565 t)
566 ;; trailing comment
569 t)
570 ;; indentable comment like python-mode.el
576 ;; Prefer to indent comments with an immediately-following
577 ;; statement, e.g.
578 ;; ...
579 ;; # ...
580 ;; def ...
591 ;;;; Cycling through the possible indentations with successive TABs.
593 ;; These don't need to be buffer-local since they're only relevant
594 ;; during a cycle.
597 "Text of line following indentation and ignoring any trailing comment."
612 "Alist of keyword matches.
613 The car of an element is a keyword introducing a statement which
617 "Return first word (actually symbol) on the line."
623 "Return a list of possible indentations for this line.
624 It is assumed not to be a continuation line or in a multi-line string.
625 Includes the default indentation and those which would close all
626 enclosing blocks. Elements of the list are actually pairs:
627 \(INDENTATION . TEXT), where TEXT is the initial text of the
628 corresponding block opening (or nil)."
631 levels indent)
632 ;; Only one possibility immediately following a block open
633 ;; statement, assuming it doesn't have a `suite' on the same line.
638 ;; Check we don't have something like:
639 ;; if ...: ...
645 ;; Only one possibility for comment line immediately following
646 ;; another.
652 ;; Fixme: Maybe have a case here which indents (only) first
653 ;; line after a lambda.
657 ;; Is this a valid indentation for the line of interest?
659 ;; Check for things like:
660 ;; if ...: ...
661 ;; else ...:
662 ;; where the second line need not be outdented.
665 python-block-pairs)))))
666 ;; Not sensible to indent to the same level as
667 ;; previous `return' &c.
670 levels))
676 levels))))))
681 ;; This is basically what `python-indent-line' would be if we didn't
682 ;; do the cycling.
684 "Subroutine of `python-indent-line'.
685 Does non-repeated indentation. LEAVE non-nil means leave
686 indentation if it is valid, i.e. one of the positions returned by
687 `python-calculate-indentation'."
691 ;; Maybe keep a valid indentation.
703 "Indent current line as Python code.
704 When invoked via `indent-for-tab-command', cycle through possible
705 indentations for current line. The cycle is broken by a command
706 different from `indent-for-tab-command', i.e. successive TABs do
707 the cycling."
720 python-indent-list))))
727 "`indent-region-function' for Python.
728 Leaves validly-indented lines alone, i.e. doesn't indent to
729 another valid position."
742 "Non-nil if this is a line in a statement closing a block,
743 or a blank line indented to where it would close a block."
750 \f
751 ;;;; Movement.
753 ;; Fixme: Define {for,back}ward-sexp-function? Maybe skip units like
754 ;; block, statement, depending on context.
757 "`beginning-of-defun-function' for Python.
758 Finds beginning of innermost nested class or method definition.
759 Returns the name of the definition found at the end, or nil if
760 reached start of buffer."
768 ;; Treat bol at beginning of function as outside function so
769 ;; that successive C-M-a makes progress backwards.
770 ;;(setq def-line (looking-at def-re))
774 ;; Must be less indented or matching top level, or
775 ;; equally indented if we started on a definition line.
779 ;; Not sure why it was like this -- fails in case of
780 ;; last internal function followed by first
781 ;; non-def statement of the main body.
782 ;;(and def-line (= in ci))
789 "`end-of-defun-function' for Python.
790 Finds end of innermost nested class or method definition."
793 ;; Go to start of current block and check whether it's at top
794 ;; level. If it is, and not a block start, look forward for
795 ;; definition statement.
807 ;; Don't move before top-level statement that would end defun.
810 ;; If we got to the start of buffer, look forward for
811 ;; definition statement.
816 ;; We're at a definition statement (or end-of-buffer).
819 ;; Count trailing space in defun (but not trailing comments).
823 ;; Catch pathological cases like this, where the beginning-of-defun
824 ;; skips to a definition we're not in:
825 ;; if ...:
826 ;; ...
827 ;; else:
828 ;; ... # point here
829 ;; ...
830 ;; def ...
835 "Go to start of current statement.
836 Accounts for continuation lines, multi-line strings, and
837 multi-line bracketed expressions."
852 "Skip out of any nested brackets.
853 Skip forward if FORWARD is non-nil, else backward.
854 If SYNTAX is non-nil it is the state returned by `syntax-ppss' at point.
855 Return non-nil iff skipping was done."
860 ;; Skip forward out of nested brackets.
864 ;; Invalid syntax (too many closed brackets).
865 ;; Skip out of as many as possible.
871 done)))))
874 "Go to the end of the current statement and return point.
875 Usually this is the start of the next line, but if this is a
876 multi-line statement we need to skip over the continuation lines.
877 On a comment line, go to end of line."
880 ;; Move past any enclosing strings and sexps, or stop if
881 ;; we're in a comment.
885 nil)
887 ;; Go to start of string and skip it.
900 "Go to start of previous statement.
901 With argument COUNT, do it COUNT times. Stop at beginning of buffer.
902 Return count of statements left to move."
912 count))
915 "Go to start of next statement.
916 With argument COUNT, do it COUNT times. Stop at end of buffer.
917 Return count of statements left to move."
928 count))
931 "Go to start of current block.
932 With numeric arg, do it that many times. If ARG is negative, call
933 `python-end-of-block' instead.
934 If point is on the first line of a block, use its outer block.
935 If current statement is in column zero, don't move and return nil.
936 Otherwise return non-nil."
951 ;; Look upwards for less indented statement.
953 ;;; This is slower than the below.
954 ;;; (while (zerop (python-previous-statement))
955 ;;; (when (and (< (current-indentation) ci)
956 ;;; (python-open-block-statement-p t))
957 ;;; (beginning-of-line)
958 ;;; (throw 'done t)))
962 ;; Move to beginning to save effort in case
963 ;; this is in string.
972 "Go to end of current block.
973 With numeric arg, do it that many times. If ARG is negative,
974 call `python-beginning-of-block' instead.
975 If current statement is in column zero and doesn't open a block,
976 don't move and return nil. Otherwise return t."
987 opoint)
1002 \f
1003 ;;;; Imenu.
1007 "`imenu-create-index-function' for Python.
1009 Makes nested Imenu menus from nested `class' and `def' statements.
1010 The nested menus are headed by an item referencing the outer
1011 definition; it has a space prepended to the name so that it sorts
1012 first with `imenu--sort-by-name' (though, unfortunately, sub-menus
1013 precede it)."
1015 ;; Normal call from Imenu.
1017 ;; Without this, we can get an infloop if the buffer isn't all
1018 ;; fontified. I guess this is really a bug in syntax.el. OTOH,
1019 ;; _with_ this, imenu doesn't immediately work; I can't figure out
1020 ;; what's going on, but it must be something to do with timers in
1021 ;; font-lock.
1022 ;; This can't be right, especially not when jit-lock is not used. --Stef
1023 ;; (unless (get-text-property (1- (point-max)) 'fontified)
1024 ;; (font-lock-fontify-region (point-min) (point-max)))
1025 )
1031 nil t)
1046 ;; Look for module variables.
1051 nil t)
1054 vars)))
1059 index-alist))))
1060 index-alist))
1061 \f
1062 ;;;; `Electric' commands.
1065 "Insert a colon and maybe outdent the line if it is a statement like `else'.
1067 just insert a single colon."
1079 "Maybe delete a level of indentation on the current line.
1080 Do so if point is at the end of the line's indentation outside
1081 strings and comments.
1082 Otherwise just call `backward-delete-char-untabify'.
1083 Repeat ARG times."
1090 ;; Look for the largest valid indentation which is smaller than
1091 ;; the current indentation.
1095 initial)
1105 \f
1106 ;;;; pychecker
1109 "Command used to check a Python file."
1116 ;; After `sgml-validate-command'.
1118 "Check a Python file (default current buffer's file).
1119 Runs COMMAND, a shell command, as if by `compile'.
1120 See `python-check-command' for the default."
1133 compilation-error-regexp-alist)))
1135 \f
1136 ;;;; Inferior mode stuff (following cmuscheme).
1138 ;; Fixme: Make sure we can work with IPython.
1141 "Shell command to run Python interpreter.
1142 Any arguments can't contain whitespace.
1143 Note that IPython may not work properly; it must at least be used
1144 with the `-cl' flag, i.e. use `ipython -cl'."
1149 "Shell command to run Jython interpreter.
1150 Any arguments can't contain whitespace."
1155 "Actual command used to run Python.
1156 May be `python-python-command' or `python-jython-command', possibly
1157 modified by the user. Additional arguments are added when the command
1161 "*The current Python process buffer.
1163 Commands that send text from source buffers to Python processes have
1164 to choose a process to send to. This is determined by buffer-local
1165 value of `python-buffer'. If its value in the current buffer,
1166 i.e. both any local value and the default one, is nil, `run-python'
1167 and commands that send to the Python process will start a new process.
1170 value of `python-buffer' to be the new process's buffer and sets the
1171 buffer-local value similarly if the current buffer is in Python mode
1172 or Inferior Python mode, so that source buffer stays associated with a
1173 specific sub-process.
1180 ;; FIXME: maybe these should move to compilation-error-regexp-alist-alist.
1181 ;; The first already is (for CAML), but the second isn't. Anyhow,
1182 ;; these are specific to the inferior buffer. -- fx
1190 ;; pdb stack trace
1198 ;; This will inherit from comint-mode-map.
1201 ;; Note that we _can_ still use these commands which send to the
1202 ;; Python process even at the prompt iff we have a normal prompt,
1203 ;; i.e. '>>> ' and not '... '. See the comment before
1204 ;; python-send-region. Fixme: uncomment these if we address that.
1206 ;; (define-key map [(meta ?\t)] 'python-complete-symbol)
1207 ;; (define-key map "\C-c\C-f" 'python-describe-symbol)
1208 map))
1212 ;; Don't get confused by apostrophes in the process's output (e.g. if
1213 ;; you execute "help(os)").
1215 ;; Maybe we should do the same for double quotes?
1216 ;; (modify-syntax-entry ?\" "." st)
1217 st))
1219 ;; Fixme: This should inherit some stuff from `python-mode', but I'm
1220 ;; not sure how much: at least some keybindings, like C-c C-f;
1221 ;; syntax?; font-locking, e.g. for triple-quoted strings?
1223 "Major mode for interacting with an inferior Python process.
1226 Hooks `comint-mode-hook' and `inferior-python-mode-hook' are run in
1227 that order.
1229 You can send text to the inferior Python process from other buffers
1230 containing Python source.
1232 process buffer.
1235 after sending the text.
1236 For running multiple processes in multiple buffers, see `run-python' and
1237 `python-buffer'.
1244 nil t)
1245 ;; Still required by `comint-redirect-send-command', for instance
1246 ;; (and we need to match things like `>>> ... >>> '):
1250 python-compilation-regexp-alist)
1254 "Input matching this regexp is not saved on the history list.
1255 Default ignores all inputs of 0, 1, or 2 non-blank characters."
1260 "`comint-input-filter' function for inferior Python.
1261 Don't save anything for STR matching `inferior-python-filter-regexp'."
1264 ;; Fixme: Loses with quoted whitespace.
1280 ;; Using this stops us getting lines in the buffer like
1281 ;; >>> ... ... >>>
1283 "`comint-preoutput-filter-functions' function: ignore prompts not at bol."
1289 ;; First process whole lines.
1292 ;; Skip prompt if needed.
1297 ;; Recognize special _emacs_out lines.
1304 ;; Then process the remaining partial line.
1307 ;; Drop this prompt if it follows an _emacs_out...
1309 ;; ... or if it's not gonna be inserted at BOL.
1310 ;; Maybe we could be more selective here.
1314 ;; The need for this seems to be system-dependent:
1315 ;; What is this all about, exactly? --Stef
1316 ;; (if (and (eq ?. (aref s 0)))
1317 ;; (accept-process-output (get-buffer-process (current-buffer)) 1))
1319 res)
1322 ;; The leftover string is a prefix of _emacs_out so we don't know
1323 ;; yet whether it's an _emacs_out or something else: wait until we
1324 ;; get more output so we can resolve this ambiguity.
1326 res)
1331 ;;;###autoload
1333 "Run an inferior Python process, input and output via buffer *Python*.
1334 CMD is the Python command to run. NOSHOW non-nil means don't show the
1335 buffer automatically.
1337 Normally, if there is a process already running in `python-buffer',
1338 switch to that buffer. Interactively, a prefix arg allows you to edit
1339 the initial command line (default is `python-command'); `-i' etc. args
1340 will be added to this as appropriate. A new process is started if:
1341 one isn't running attached to `python-buffer', or interactively the
1342 default `python-command', or argument NEW is non-nil. See also the
1343 documentation for `python-buffer'.
1345 Runs the hook `inferior-python-mode-hook' \(after the
1347 buffer for a list of commands.)"
1353 ;; Fixme: Consider making `python-buffer' buffer-local as a buffer
1354 ;; (not a name) in Python buffers from which `run-python' &c is
1355 ;; invoked. Would support multiple processes better.
1363 process-environment)))
1371 ;; Load function definitions we need.
1372 ;; Before the preoutput function was used, this was done via -c in
1373 ;; cmdlist, but that loses the banner and doesn't run the startup
1374 ;; file. The code might be inline here, but there's enough that it
1375 ;; seems worth putting in a separate file, and it's probably cleaner
1376 ;; to put it in a module.
1377 ;; Ensure we're at a prompt before doing anything else.
1381 ;; Without this, help output goes into the inferior python buffer if
1382 ;; the process isn't already running.
1386 ;; Fixme: We typically lose if the inferior isn't in the normal REPL,
1387 ;; e.g. prompt is `help> '. Probably raise an error if the form of
1388 ;; the prompt is unexpected. Actually, it needs to be `>>> ', not
1389 ;; `... ', i.e. we're not inputting a block &c. However, this may not
1390 ;; be the place to check it, e.g. we might actually want to send
1391 ;; commands having set up such a state.
1394 "Like `python-send-string' but resets `compilation-shell-minor-mode'.
1395 COMMAND should be a single statement."
1396 ;; (assert (not (string-match "\n" command)))
1397 ;; (let ((end (marker-position (process-mark (python-proc)))))
1403 ;; No idea what this is for but it breaks the call to
1404 ;; compilation-fake-loc in python-send-region. -- Stef
1405 ;; Must wait until this has completed before re-setting variables below.
1406 ;; (python-send-receive "print '_emacs_out ()'")
1407 ;; (with-current-buffer python-buffer
1408 ;; (set-marker compilation-parsing-end end))
1412 "Send the region to the inferior Python process."
1413 ;; The region is evaluated from a temporary file. This avoids
1414 ;; problems with blank lines, which have different semantics
1415 ;; interactively and in files. It also saves the inferior process
1416 ;; buffer filling up with interpreter prompts. We need a Python
1417 ;; function to remove the temporary file when it has been evaluated
1418 ;; (though we could probably do it in Lisp with a Comint output
1419 ;; filter). This function also catches exceptions and truncates
1420 ;; tracebacks not to mention the frame of the function itself.
1421 ;;
1422 ;; The `compilation-shell-minor-mode' parsing takes care of relating
1423 ;; the reference to the temporary file to the source.
1424 ;;
1425 ;; Fixme: Write a `coding' header to the temp file if the region is
1426 ;; non-ASCII.
1436 ;; Wrong if we had indented code at buffer start.
1442 ;; Tell compile.el to redirect error locations in file `f' to
1443 ;; positions past marker `orig-start'. It has to be done *after*
1444 ;; `python-send-command''s call to `compilation-forget-errors'.
1448 "Evaluate STRING in inferior Python process."
1452 ;; Make sure the text is properly LF-terminated.
1455 ;; If the string contains a final indented line, add a second newline so
1456 ;; as to make sure we terminate the multiline instruction.
1460 "Send the current buffer to the inferior Python process."
1464 ;; Fixme: Try to define the function or class within the relevant
1465 ;; module, not just at top level.
1467 "Send the current defun (class or method) to the inferior Python process."
1473 "Switch to the Python process buffer, maybe starting new process.
1474 With prefix arg, position cursor at end of buffer."
1482 "Send the region to the inferior Python process.
1483 Then switch to the process buffer."
1489 "Used to determine if a buffer contains Python source code.
1490 If a file is loaded into a buffer that is in one of these major modes,
1491 it is considered Python source by `python-load-file', which uses the
1492 value to determine defaults."
1497 "Caches (directory . file) pair used in the last `python-load-file' command.
1503 "Load a Python file FILE-NAME into the inferior Python process.
1504 If the file has extension `.py' import or reload it as a module.
1505 Treating it as a module keeps the global namespace clean, provides
1506 function location information for debugging, and supports users of
1507 module-qualified names."
1509 python-source-modes
1515 ;; Fixme: I'm not convinced by this logic from python-mode.el.
1526 "Return the current Python process.
1527 See variable `python-buffer'. Starts a new process if necessary."
1528 ;; Fixme: Maybe should look for another active process if there
1529 ;; isn't one for `python-buffer'.
1534 python-buffer)))
1537 "Set the default value of `python-buffer' to correspond to this buffer.
1538 If the current buffer has a local value of `python-buffer', set the
1539 default (global) value to that. The associated Python process is
1541 in a buffer that doesn't have a local value of `python-buffer'."
1546 \f
1547 ;;;; Context-sensitive help.
1553 table)
1554 "Syntax table giving `.' symbol syntax.
1562 ;; Fixme: Should this actually be used instead of info-look, i.e. be
1563 ;; bound to C-h S? [Probably not, since info-look may work in cases
1564 ;; where this doesn't.]
1566 "Get help on SYMBOL using `help'.
1567 Interactively, prompt for symbol.
1569 Symbol may be anything recognized by the interpreter's `help'
1570 command -- e.g. `CALLS' -- not just variables in scope in the
1571 interpreter. This only works for Python version 2.2 or newer
1572 since earlier interpreters don't support `help'.
1575 will."
1576 ;; Note that we do this in the inferior process, not a separate one, to
1577 ;; ensure the environment is appropriate.
1585 nil nil symbol))))
1587 ;; Ensure we have a suitable help buffer.
1588 ;; Fixme: Maybe process `Related help topics' a la help xrefs and
1589 ;; allow C-c C-f in help buffer.
1597 ;; Fixme: Is this actually useful?
1602 symbol python-imports)
1608 "Send STRING to inferior Python (if any) and return result.
1609 The result is what follows `_emacs_out' in the output."
1620 ;; Fixme: Is there anything reasonable we can do with random methods?
1621 ;; (Currently only works with functions.)
1623 "`eldoc-documentation-function' for Python.
1624 Only works when point is in a function name, not its arg list, for
1625 instance. Assumes an inferior Python is running."
1628 ;; This is run from timers, so inhibit-quit tends to be set.
1630 ;; First try the symbol we're on.
1633 symbol python-imports)))
1634 ;; Try moving to symbol before enclosing parens.
1647 python-imports))))))))))))
1648 \f
1649 ;;;; Info-look functionality.
1652 "Set up info-look for Python.
1653 Used with `eval-after-load'."
1658 ;; Whether info files have a Python version suffix, e.g. in Debian.
1663 ;; Don't use `info' because it would pop-up a *info* buffer.
1666 version))
1667 t)
1672 :doc-spec
1673 ;; Fixme: Can this reasonably be made specific to indices with
1674 ;; different rules? Is the order of indices optimal?
1675 ;; (Miscellaneous in -ref first prefers lookup of keywords, for
1676 ;; instance.)
1678 ;; The empty prefix just gets us highlighted terms.
1700 \f
1701 ;;;; Miscellany.
1704 "Packages implying `jython-mode'.
1705 If these are imported near the beginning of the buffer, `python-mode'
1706 actually punts to `jython-mode'."
1710 ;; Called from `python-mode', this causes a recursive call of the
1711 ;; mode. See logic there to break out of the recursion.
1713 "Invoke `jython-mode' if the buffer appears to contain Jython code.
1714 The criterion is either a match for `jython-mode' via
1715 `interpreter-mode-alist' or an import of a module from the list
1716 `python-jython-packages'."
1717 ;; The logic is taken from python-mode.el.
1726 interpreter)
1727 interpreter-mode-alist))))
1734 t)
1740 "`fill-paragraph-function' handling multi-line strings and possibly comments.
1741 If any of the current line is in or at the end of a multi-line string,
1742 fill the string or the paragraph of it that point is in, preserving
1743 the strings's indentation."
1750 start end)
1754 ;; The `paragraph-start' and `paragraph-separate'
1755 ;; variables don't allow us to delimit the last
1756 ;; paragraph in a multi-line string properly, so narrow
1757 ;; to the string and then fill around (the end of) the
1758 ;; current line.
1777 ;; Avoid losing leading and trailing newlines in doc
1778 ;; strings written like:
1779 ;; """
1780 ;; ...
1781 ;; """
1787 ; opening quotes
1793 "Shift lines in region COUNT (the prefix arg) columns to the left.
1794 COUNT defaults to `python-indent'. If region isn't active, just shift
1795 current line. The region shifted includes the lines in which START and
1796 END lie. It is an error if any lines in the region are indented less than
1797 COUNT columns."
1817 "Shift lines in region COUNT (the prefix arg) columns to the right.
1818 COUNT defaults to `python-indent'. If region isn't active, just shift
1819 current line. The region shifted includes the lines in which START and
1820 END lie."
1830 "`outline-level' function for Python mode.
1831 The level is the number of `python-indent' steps of indentation
1832 of current line."
1835 ;; Fixme: Consider top-level assignments, imports, &c.
1837 "`add-log-current-defun-function' for Python."
1839 ;; Move up the tree of nested `class' and `def' blocks until we
1840 ;; get to zero indentation, accumulating the defined names.
1842 accum)
1854 "Mark the block around point.
1855 Uses `python-beginning-of-block', `python-end-of-block'."
1863 ;; Fixme: Provide a find-function-like command to find source of a
1864 ;; definition (separate from BicycleRepairMan). Complicated by
1865 ;; finding the right qualified name.
1866 \f
1867 ;;;; Completion.
1869 ;; http://lists.gnu.org/archive/html/bug-gnu-emacs/2008-01/msg00076.html
1874 ;; Fixme: Should font-lock try to run this when it deals with an import?
1875 ;; Maybe not a good idea if it gets run multiple times when the
1876 ;; statement is being edited, and is more likely to end up with
1877 ;; something syntactically incorrect.
1878 ;; However, what we should do is to trundle up the block tree from point
1879 ;; to extract imports that appear to be in scope, and add those.
1881 "Find top-level imports, updating `python-imports'."
1889 ;; Skip over continued lines.
1893 lines))))
1897 ;; This is probably best left out since you're unlikely to need the
1898 ;; doc for a function in the buffer and the import will lose if the
1899 ;; Python sub-process' working directory isn't the same as the
1900 ;; buffer's.
1901 ;; (if buffer-file-name
1902 ;; (concat
1903 ;; "import "
1904 ;; (file-name-sans-extension
1905 ;; (file-name-nondirectory buffer-file-name))))
1910 ;; The output ends up in the wrong place if the string we
1911 ;; send contains newlines (from the imports).
1916 ;; Fixme: This fails the first time if the sub-process isn't already
1917 ;; running. Presumably a timing issue with i/o to the process.
1919 "Return a list of completions of the string SYMBOL from Python process.
1920 The list is sorted.
1921 Uses `python-imports' to load modules against which to complete."
1930 ;; We can get duplicates from the above -- don't know why.
1935 "Return the partial symbol before point (for completion)."
1941 nil t)
1946 "Perform completion on the Python symbol preceding point.
1947 Repeating the command scrolls the completion window."
1959 ;; Do completion.
1980 "Completion function for Python for use with `hippie-expand'."
1995 t)
1997 nil)))
1998 \f
1999 ;;;; FFAP support
2002 "Function for `ffap-alist' to return path to MODULE."
2007 \f
2008 ;;;; Skeletons
2011 "Non-nil means template skeletons will be automagically inserted.
2013 the if condition."
2018 "Alist of named skeletons for Python mode.
2022 "Abbrev table for Python mode.
2027 ;; Define a user-level skeleton and add it to `python-skeletons' and
2028 ;; the abbrev table.
2041 ;; From `skeleton-further-elements':
2042 ;; `<': outdent a level;
2043 ;; `^': delete indentation on current line and also previous newline.
2044 ;; Not quote like `delete-indentation'. Assumes point is at
2045 ;; beginning of indentation.
2048 "Condition: "
2058 "Auxiliary skeleton."
2059 nil
2066 "Condition: "
2072 "Target, %s: "
2078 nil
2089 "Auxiliary skeleton."
2093 nil
2100 "Name: "
2107 "Name: "
2110 str)
2117 "Default template to expand by `python-expand-template'.
2121 "Expand template named NAME.
2122 Interactively, prompt for the name with completion."
2125 python-default-template)
2126 python-skeletons nil t)))
2134 \f
2135 ;;;; Bicycle Repair Man support
2140 ;; I'm not sure how useful BRM really is, and it's certainly dangerous
2141 ;; the way it modifies files outside Emacs... Also note that the
2142 ;; current BRM loses with tabs used for indentation -- I submitted a
2143 ;; fix <URL:http://www.loveshack.ukfsn.org/emacs/bikeemacs.py.diff>.
2145 "Set up Bicycle Repair Man refactoring tool (if available).
2147 Note that the `refactoring' features change files independently of
2148 Emacs and may modify and save the contents of the current buffer
2149 without confirmation."
2160 python-brm-menu python-mode-map
2161 "Bicycle Repair Man"
2164 "Queries"
2169 "-"
2170 "Refactoring"
2180 :help
2182 ;; Fixme: Should check for anything to revert.
2185 \f
2186 ;;;; Modes.
2191 ;; Stuff to allow expanding abbrevs with non-word constituents.
2193 "Set the syntax table before possibly expanding abbrevs."
2202 "Reset the syntax table after possibly expanding abbrevs."
2209 ;;;###autoload
2211 "Major mode for editing Python files.
2212 Font Lock mode is currently required for correct parsing of the source.
2213 See also `jython-mode', which is actually invoked if the buffer appears to
2214 contain Jython code. See also `run-python' and associated Python mode
2215 commands for running Python under Emacs.
2218 with nested `def' and `class' blocks. They take the innermost one as
2219 current without distinguishing method and class definitions. Used multiple
2220 times, they move over others at the same indentation level until they reach
2221 the end of definitions at that level, when they move up a level.
2223 Colon is electric: it outdents the line if appropriate, e.g. for
2225 deletes a level of indentation to close the current block; otherwise it
2226 deletes a character backward. TAB indents the current line relative to
2227 the preceding code. Successive TABs, with no intervening command, cycle
2228 through the possibilities for indentation on the basis of enclosing blocks.
2231 effect outside them.
2233 Supports Eldoc mode (only for functions, using a Python process),
2234 Info-Look and Imenu. In Outline minor mode, `class' and `def'
2235 lines count as headers. Symbol completion is available in the
2236 same way as in the Python shell using the `rlcompleter' module
2237 and this is added to the Hippie Expand functions locally if
2238 Hippie Expand mode is turned on. Completion of symbols of the
2239 form x.y only works if the components are literal
2240 module/attribute names, not variables. An abbrev table is set up
2241 with skeleton expansions for compound statement templates.
2248 . python-font-lock-syntactic-keywords)
2249 ;; This probably isn't worth it.
2250 ;; (font-lock-syntactic-face-function
2251 ;; . python-font-lock-syntactic-face-function)
2252 ))
2266 symbol-end))
2279 nil t)
2280 ;; Fixme: should be in hideshow. This seems to be of limited use
2281 ;; since it isn't (can't be) indentation-based. Also hide-level
2282 ;; doesn't seem to work properly.
2288 nil))
2294 ;; Let's not mess with hippie-expand. Symbol-completion should rather be
2295 ;; bound to another key, since it has different performance requirements.
2296 ;; (if (featurep 'hippie-exp)
2297 ;; (set (make-local-variable 'hippie-expand-try-functions-list)
2298 ;; (cons 'python-try-complete hippie-expand-try-functions-list)))
2299 ;; Python defines TABs as being 8-char wide.
2302 ;; Let's make it harder for the user to shoot himself in the foot.
2314 "Turn off Indent Tabs mode."
2320 ;;;###autoload
2322 "Major mode for editing Jython files.
2323 Like `python-mode', but sets up parameters for Jython subprocesses.
2324 Runs `jython-mode-hook' after `python-mode-hook'."
2330 ;; arch-tag: 6fce1d99-a704-4de9-ba19-c6e4912b0554
2331 ;;; python.el ends here