(concat "Value: " (prin1-to-string (symbol-value func)))))) (t ; unexpected (error "Error in py-dump-help-string, tag `%s'" funckind))) (princ (format "\n-> %s:\t%s\t%s\n\n" (if (equal funckind "c") "Command" "Variable") funcname keys)) (princ funcdoc) (terpri) (setq start end)) (princ (substitute-command-keys (substring str start)))) (print-help-return-message))) (defun py-describe-mode () "Dump long form of Python-mode docs." (interactive) (py-dump-help-string "Major mode for editing Python files.Knows about Python indentation, tokens, comments and continuation lines.Paragraphs are separated by blank lines only. Major sections below begin with the string `@'; specific function andvariable docs begin with `->'. @EXECUTING PYTHON CODE \\[py-execute-import-or-reload]\timports or reloads the file in the Python interpreter\\[py-execute-buffer]\tsends the entire buffer to the Python interpreter\\[py-execute-region]\tsends the current region\\[py-execute-def-or-class]\tsends the current function or class definition\\[py-execute-string]\tsends an arbitrary string\\[py-shell]\tstarts a Python interpreter window; this will be used by\tsubsequent Python execution commands%c:py-execute-import-or-reload%c:py-execute-buffer%c:py-execute-region%c:py-execute-def-or-class%c:py-execute-string%c:py-shell @VARIABLES py-indent-offset\tindentation incrementpy-block-comment-prefix\tcomment string used by comment-region py-python-command\tshell command to invoke Python interpreterpy-temp-directory\tdirectory used for temp files (if needed) py-beep-if-tab-change\tring the bell if tab-width is changed%v:py-indent-offset%v:py-block-comment-prefix%v:py-python-command%v:py-temp-directory%v:py-beep-if-tab-change @KINDS OF LINES Each physical line in the file is either a `continuation line' (thepreceding line ends with a backslash that's not part of a comment, orthe paren/bracket/brace nesting level at the start of the line isnon-zero, or both) or an `initial line' (everything else). An initial line is in turn a `blank line' (contains nothing exceptpossibly blanks or tabs), a `comment line' (leftmost non-blankcharacter is `#'), or a `code line' (everything else). Comment Lines Although all comment lines are treated alike by Python, Python moderecognizes two kinds that act differently with respect to indentation. An `indenting comment line' is a comment line with a blank, tab ornothing after the initial `#'. The indentation commands (see below)treat these exactly as if they were code lines: a line following anindenting comment line will be indented like the comment line. Allother comment lines (those with a non-whitespace character immediatelyfollowing the initial `#') are `non-indenting comment lines', andtheir indentation is ignored by the indentation commands. Indenting comment lines are by far the usual case, and should be usedwhenever possible. Non-indenting comment lines are useful in caseslike these: \ta = b # a very wordy single-line comment that ends up being\t #... continued onto another line \tif a == b:##\t\tprint 'panic!' # old code we've `commented out'\t\treturn a Since the `#...' and `##' comment lines have a non-whitespacecharacter following the initial `#', Python mode ignores them whencomputing the proper indentation for the next line. Continuation Lines and Statements The Python-mode commands generally work on statements instead of onindividual lines, where a `statement' is a comment or blank line, or acode line and all of its following continuation lines (if any)considered as a single logical unit. The commands in this modegenerally (when it makes sense) automatically move to the start of thestatement containing point, even if point happens to be in the middleof some continuation line. @INDENTATION Primarily for entering new code:\t\\[indent-for-tab-command]\t indent line appropriately\t\\[py-newline-and-indent]\t insert newline, then indent\t\\[py-electric-backspace]\t reduce indentation, or delete single character Primarily for reindenting existing code:\t\\[py-guess-indent-offset]\t guess py-indent-offset from file content; change locally\t\\[universal-argument] \\[py-guess-indent-offset]\t ditto, but change globally \t\\[py-indent-region]\t reindent region to match its context\t\\[py-shift-region-left]\t shift region left by py-indent-offset\t\\[py-shift-region-right]\t shift region right by py-indent-offset Unlike most programming languages, Python uses indentation, and onlyindentation, to specify block structure. Hence the indentation suppliedautomatically by Python-mode is just an educated guess: only you knowthe block structure you intend, so only you can supply correctindentation. The \\[indent-for-tab-command] and \\[py-newline-and-indent] keys try to suggest plausible indentation, based onthe indentation of preceding statements. E.g., assumingpy-indent-offset is 4, after you enter\tif a > 0: \\[py-newline-and-indent]the cursor will be moved to the position of the `_' (_ is not acharacter in the file, it's just used here to indicate the location ofthe cursor):\tif a > 0:\t _If you then enter `c = d' \\[py-newline-and-indent], the cursor will moveto\tif a > 0:\t c = d\t _Python-mode cannot know whether that's what you intended, or whether\tif a > 0:\t c = d\t_was your intent. In general, Python-mode either reproduces theindentation of the (closest code or indenting-comment) precedingstatement, or adds an extra py-indent-offset blanks if the precedingstatement has `:' as its last significant (non-whitespace and non-comment) character. If the suggested indentation is too much, use\\[py-electric-backspace] to reduce it. Continuation lines are given extra indentation. If you don't like thesuggested indentation, change it to something you do like, and Python-mode will strive to indent later lines of the statement in the same way. If a line is a continuation line by virtue of being in an unclosedparen/bracket/brace structure (`list', for short), the suggestedindentation depends on whether the current line contains the first itemin the list. If it does, it's indented py-indent-offset columns beyondthe indentation of the line containing the open bracket. If you don'tlike that, change it by hand. The remaining items in the list will mimicwhatever indentation you give to the first item. If a line is a continuation line because the line preceding it ends witha backslash, the third and following lines of the statement inherit theirindentation from the line preceding them. The indentation of the secondline in the statement depends on the form of the first (base) line: ifthe base line is an assignment statement with anything more interestingthan the backslash following the leftmost assigning `=', the second lineis indented two columns beyond that `='. Else it's indented to twocolumns beyond the leftmost solid chunk of non-whitespace characters onthe base line. Warning: indent-region should not normally be used! It calls \\[indent-for-tab-command]repeatedly, and as explained above, \\[indent-for-tab-command] can't guess the blockstructure you intend.%c:indent-for-tab-command%c:py-newline-and-indent%c:py-electric-backspace The next function may be handy when editing code you didn't write:%c:py-guess-indent-offset The remaining `indent' functions apply to a region of Python code. Theyassume the block structure (equals indentation, in Python) of the regionis correct, and alter the indentation in various ways while preservingthe block structure:%c:py-indent-region%c:py-shift-region-left%c:py-shift-region-right @MARKING & MANIPULATING REGIONS OF CODE \\[py-mark-block]\t mark block of lines\\[py-mark-def-or-class]\t mark smallest enclosing def\\[universal-argument] \\[py-mark-def-or-class]\t mark smallest enclosing class\\[comment-region]\t comment out region of code\\[universal-argument] \\[comment-region]\t uncomment region of code%c:py-mark-block%c:py-mark-def-or-class%c:comment-region @MOVING POINT \\[py-previous-statement]\t move to statement preceding point\\[py-next-statement]\t move to statement following point\\[py-goto-block-up]\t move up to start of current block\\[py-beginning-of-def-or-class]\t move to start of def\\[universal-argument] \\[py-beginning-of-def-or-class]\t move to start of class\\[py-end-of-def-or-class]\t move to end of def\\[universal-argument] \\[py-end-of-def-or-class]\t move to end of class The first two move to one statement beyond the statement that containspoint. A numeric prefix argument tells them to move that manystatements instead. Blank lines, comment lines, and continuation linesdo not count as `statements' for these commands. So, e.g., you can goto the first code statement in a file by entering\t\\[beginning-of-buffer]\t to move to the top of the file\t\\[py-next-statement]\t to skip over initial comments and blank linesOr do `\\[py-previous-statement]' with a huge prefix argument.%c:py-previous-statement%c:py-next-statement%c:py-goto-block-up%c:py-beginning-of-def-or-class%c:py-end-of-def-or-class @LITTLE-KNOWN EMACS COMMANDS PARTICULARLY USEFUL IN PYTHON MODE `\\[indent-new-comment-line]' is handy for entering a multi-line comment. `\\[set-selective-display]' with a `small' prefix arg is ideally suited for viewing theoverall class and def structure of a module. `\\[back-to-indentation]' moves point to a line's first non-blank character. `\\[indent-relative]' is handy for creating odd indentation. @OTHER EMACS HINTS If you don't like the default value of a variable, change its value towhatever you do like by putting a `setq' line in your .emacs file.E.g., to set the indentation increment to 4, put this line in your.emacs:\t(setq py-indent-offset 4)To see the value of a variable, do `\\[describe-variable]' and enter the variablename at the prompt. When entering a key sequence like `C-c C-n', it is not necessary torelease the CONTROL key after doing the `C-c' part -- it suffices topress the CONTROL key, press and release `c' (while still holding downCONTROL), press and release `n' (while still holding down CONTROL), &then release CONTROL. Entering Python mode calls with no arguments the value of the variable`python-mode-hook', if that value exists and is not nil; for backwardcompatibility it also tries `py-mode-hook'; see the `Hooks' section ofthe Elisp manual for details. Obscure: When python-mode is first loaded, it looks for all bindingsto newline-and-indent in the global keymap, and shadows them withlocal bindings to py-newline-and-indent.")) (require 'info-look);; The info-look package does not always provide this function (it;; appears this is the case with XEmacs 21.1)(when (fboundp 'info-lookup-maybe-add-help) (info-lookup-maybe-add-help :mode 'python-mode :regexp "[a-zA-Z0-9_]+" :doc-spec '(("(python-lib)Module Index") ("(python-lib)Class-Exception-Object Index") ("(python-lib)Function-Method-Variable Index") ("(python-lib)Miscellaneous Index"))) ) ;; Helper functions(defvar py-parse-state-re (concat "^[ \t]*\\(elif\\|else\\|while\\|def\\|class\\)\\>" "\\|" "^[^ #\t\n]")) (defun py-parse-state () "Return the parse state at point (see `parse-partial-sexp' docs)." (save-excursion (let ((here (point)) pps done) (while (not done) ;; back up to the first preceding line (if any; else start of ;; buffer) that begins with a popular Python keyword, or a ;; non- whitespace and non-comment character. These are good ;; places to start parsing to see whether where we started is ;; at a non-zero nesting level. It may be slow for people who ;; write huge code blocks or huge lists ... tough beans. (re-search-backward py-parse-state-re nil 'move) (beginning-of-line) ;; In XEmacs, we have a much better way to test for whether ;; we're in a triple-quoted string or not. Emacs does not ;; have this built-in function, which is its loss because ;; without scanning from the beginning of the buffer, there's ;; no accurate way to determine this otherwise. (save-excursion (setq pps (parse-partial-sexp (point) here))) ;; make sure we don't land inside a triple-quoted string (setq done (or (not (nth 3 pps)) (bobp))) ;; Just go ahead and short circuit the test back to the ;; beginning of the buffer. This will be slow, but not ;; nearly as slow as looping through many ;; re-search-backwards. (if (not done) (goto-char (point-min)))) pps))) (defun py-nesting-level () "Return the buffer position of the last unclosed enclosing list.If nesting level is zero, return nil." (let ((status (py-parse-state))) (if (zerop (car status)) nil ; not in a nest (car (cdr status))))) ; char# of open bracket (defun py-backslash-continuation-line-p () "Return t iff preceding line ends with backslash that is not in a comment." (save-excursion (beginning-of-line) (and ;; use a cheap test first to avoid the regexp if possible ;; use 'eq' because char-after may return nil (eq (char-after (- (point) 2)) ?\\ ) ;; make sure; since eq test passed, there is a preceding line (forward-line -1) ; always true -- side effect (looking-at py-continued-re)))) (defun py-continuation-line-p () "Return t iff current line is a continuation line." (save-excursion (beginning-of-line) (or (py-backslash-continuation-line-p) (py-nesting-level)))) (defun py-goto-beginning-of-tqs (delim) "Go to the beginning of the triple quoted string we find ourselves in.DELIM is the TQS string delimiter character we're searching backwardsfor." (let ((skip (and delim (make-string 1 delim))) (continue t)) (when skip (save-excursion (while continue (py-safe (search-backward skip)) (setq continue (and (not (bobp)) (= (char-before) ?\\)))) (if (and (= (char-before) delim) (= (char-before (1- (point))) delim)) (setq skip (make-string 3 delim)))) ;; we're looking at a triple-quoted string (py-safe (search-backward skip))))) (defun py-goto-initial-line () "Go to the initial line of the current statement.Usually this is the line we're on, but if we're on the 2nd orfollowing lines of a continuation block, we need to go up to the firstline of the block." ;; Tricky: We want to avoid quadratic-time behavior for long ;; continued blocks, whether of the backslash or open-bracket ;; varieties, or a mix of the two. The following manages to do that ;; in the usual cases. ;; ;; Also, if we're sitting inside a triple quoted string, this will ;; drop us at the line that begins the string. (let (open-bracket-pos) (while (py-continuation-line-p) (beginning-of-line) (if (py-backslash-continuation-line-p) (while (py-backslash-continuation-line-p) (forward-line -1)) ;; else zip out of nested brackets/braces/parens (while (setq open-bracket-pos (py-nesting-level)) (goto-char open-bracket-pos))))) (beginning-of-line)) (defun py-goto-beyond-final-line () "Go to the point just beyond the fine line of the current statement.Usually this is the start of the next line, but if this is amulti-line statement we need to skip over the continuation lines." ;; Tricky: Again we need to be clever to avoid quadratic time ;; behavior. ;; ;; XXX: Not quite the right solution, but deals with multi-line doc ;; strings (if (looking-at (concat "[ \t]*\\(" py-stringlit-re "\\)")) (goto-char (match-end 0))) ;; (forward-line 1) (let (state) (while (and (py-continuation-line-p) (not (eobp))) ;; skip over the backslash flavor (while (and (py-backslash-continuation-line-p) (not (eobp))) (forward-line 1)) ;; if in nest, zip to the end of the nest (setq state (py-parse-state)) (if (and (not (zerop (car state))) (not (eobp))) (progn (parse-partial-sexp (point) (point-max) 0 nil state) (forward-line 1)))))) (defun py-statement-opens-block-p () "Return t iff the current statement opens a block.I.e., iff it ends with a colon that is not in a comment. Point should be at the start of a statement." (save-excursion (let ((start (point)) (finish (progn (py-goto-beyond-final-line) (1- (point)))) (searching t) (answer nil) state) (goto-char start) (while searching ;; look for a colon with nothing after it except whitespace, and ;; maybe a comment (if (re-search-forward ":\\([ \t]\\|\\\\\n\\)*\\(#.*\\)?$" finish t) (if (eq (point) finish) ; note: no `else' clause; just ; keep searching if we're not at ; the end yet ;; sure looks like it opens a block -- but it might ;; be in a comment (progn (setq searching nil) ; search is done either way (setq state (parse-partial-sexp start (match-beginning 0))) (setq answer (not (nth 4 state))))) ;; search failed: couldn't find another interesting colon (setq searching nil))) answer))) (defun py-statement-closes-block-p () "Return t iff the current statement closes a block.I.e., if the line starts with `return', `raise', `break', `continue',and `pass'. This doesn't catch embedded statements." (let ((here (point))) (py-goto-initial-line) (back-to-indentation) (prog1 (looking-at (concat py-block-closing-keywords-re "\\>")) (goto-char here)))) (defun py-goto-beyond-block () "Go to point just beyond the final line of block begun by the current line.This is the same as where `py-goto-beyond-final-line' goes unlesswe're on colon line, in which case we go to the end of the block.Assumes point is at the beginning of the line." (if (py-statement-opens-block-p) (py-mark-block nil 'just-move) (py-goto-beyond-final-line))) (defun py-goto-statement-at-or-above () "Go to the start of the first statement at or preceding point.Return t if there is such a statement, otherwise nil. `Statement'does not include blank lines, comments, or continuation lines." (py-goto-initial-line) (if (looking-at py-blank-or-comment-re) ;; skip back over blank & comment lines ;; note: will skip a blank or comment line that happens to be ;; a continuation line too (if (re-search-backward "^[ \t]*[^ \t#\n]" nil t) (progn (py-goto-initial-line) t) nil) t)) (defun py-goto-statement-below () "Go to start of the first statement following the statement containing point.Return t if there is such a statement, otherwise nil. `Statement'does not include blank lines, comments, or continuation lines." (beginning-of-line) (let ((start (point))) (py-goto-beyond-final-line) (while (and (or (looking-at py-blank-or-comment-re) (py-in-literal)) (not (eobp))) (forward-line 1)) (if (eobp) (progn (goto-char start) nil) t))) (defun py-go-up-tree-to-keyword (key) "Go to begining of statement starting with KEY, at or preceding point. KEY is a regular expression describing a Python keyword. Skip blanklines and non-indenting comments. If the statement found starts withKEY, then stop, otherwise go back to first enclosing block startingwith KEY. If successful, leave point at the start of the KEY line and return t. Otherwise, leav point at an undefined place and return nil."Lines 3001–3500 of 3768. Previous lines Load more
(concat "Value: " (prin1-to-string (symbol-value func)))))) (t ; unexpected (error "Error in py-dump-help-string, tag `%s'" funckind))) (princ (format "\n-> %s:\t%s\t%s\n\n" (if (equal funckind "c") "Command" "Variable") funcname keys)) (princ funcdoc) (terpri) (setq start end)) (princ (substitute-command-keys (substring str start)))) (print-help-return-message))) (defun py-describe-mode () "Dump long form of Python-mode docs." (interactive) (py-dump-help-string "Major mode for editing Python files. Knows about Python indentation, tokens, comments and continuation lines. Paragraphs are separated by blank lines only. Major sections below begin with the string `@'; specific function and variable docs begin with `->'. @EXECUTING PYTHON CODE \\[py-execute-import-or-reload]\timports or reloads the file in the Python interpreter \\[py-execute-buffer]\tsends the entire buffer to the Python interpreter \\[py-execute-region]\tsends the current region \\[py-execute-def-or-class]\tsends the current function or class definition \\[py-execute-string]\tsends an arbitrary string \\[py-shell]\tstarts a Python interpreter window; this will be used by \tsubsequent Python execution commands %c:py-execute-import-or-reload %c:py-execute-buffer %c:py-execute-region %c:py-execute-def-or-class %c:py-execute-string %c:py-shell @VARIABLES py-indent-offset\tindentation increment py-block-comment-prefix\tcomment string used by comment-region py-python-command\tshell command to invoke Python interpreter py-temp-directory\tdirectory used for temp files (if needed) py-beep-if-tab-change\tring the bell if tab-width is changed %v:py-indent-offset %v:py-block-comment-prefix %v:py-python-command %v:py-temp-directory %v:py-beep-if-tab-change @KINDS OF LINES Each physical line in the file is either a `continuation line' (the preceding line ends with a backslash that's not part of a comment, or the paren/bracket/brace nesting level at the start of the line is non-zero, or both) or an `initial line' (everything else). An initial line is in turn a `blank line' (contains nothing except possibly blanks or tabs), a `comment line' (leftmost non-blank character is `#'), or a `code line' (everything else). Comment Lines Although all comment lines are treated alike by Python, Python mode recognizes two kinds that act differently with respect to indentation. An `indenting comment line' is a comment line with a blank, tab or nothing after the initial `#'. The indentation commands (see below) treat these exactly as if they were code lines: a line following an indenting comment line will be indented like the comment line. All other comment lines (those with a non-whitespace character immediately following the initial `#') are `non-indenting comment lines', and their indentation is ignored by the indentation commands. Indenting comment lines are by far the usual case, and should be used whenever possible. Non-indenting comment lines are useful in cases like these: \ta = b # a very wordy single-line comment that ends up being \t #... continued onto another line \tif a == b: ##\t\tprint 'panic!' # old code we've `commented out' \t\treturn a Since the `#...' and `##' comment lines have a non-whitespace character following the initial `#', Python mode ignores them when computing the proper indentation for the next line. Continuation Lines and Statements The Python-mode commands generally work on statements instead of on individual lines, where a `statement' is a comment or blank line, or a code line and all of its following continuation lines (if any) considered as a single logical unit. The commands in this mode generally (when it makes sense) automatically move to the start of the statement containing point, even if point happens to be in the middle of some continuation line. @INDENTATION Primarily for entering new code: \t\\[indent-for-tab-command]\t indent line appropriately \t\\[py-newline-and-indent]\t insert newline, then indent \t\\[py-electric-backspace]\t reduce indentation, or delete single character Primarily for reindenting existing code: \t\\[py-guess-indent-offset]\t guess py-indent-offset from file content; change locally \t\\[universal-argument] \\[py-guess-indent-offset]\t ditto, but change globally \t\\[py-indent-region]\t reindent region to match its context \t\\[py-shift-region-left]\t shift region left by py-indent-offset \t\\[py-shift-region-right]\t shift region right by py-indent-offset Unlike most programming languages, Python uses indentation, and only indentation, to specify block structure. Hence the indentation supplied automatically by Python-mode is just an educated guess: only you know the block structure you intend, so only you can supply correct indentation. The \\[indent-for-tab-command] and \\[py-newline-and-indent] keys try to suggest plausible indentation, based on the indentation of preceding statements. E.g., assuming py-indent-offset is 4, after you enter \tif a > 0: \\[py-newline-and-indent] the cursor will be moved to the position of the `_' (_ is not a character in the file, it's just used here to indicate the location of the cursor): \tif a > 0: \t _ If you then enter `c = d' \\[py-newline-and-indent], the cursor will move to \tif a > 0: \t c = d \t _ Python-mode cannot know whether that's what you intended, or whether \tif a > 0: \t c = d \t_ was your intent. In general, Python-mode either reproduces the indentation of the (closest code or indenting-comment) preceding statement, or adds an extra py-indent-offset blanks if the preceding statement has `:' as its last significant (non-whitespace and non- comment) character. If the suggested indentation is too much, use \\[py-electric-backspace] to reduce it. Continuation lines are given extra indentation. If you don't like the suggested indentation, change it to something you do like, and Python- mode will strive to indent later lines of the statement in the same way. If a line is a continuation line by virtue of being in an unclosed paren/bracket/brace structure (`list', for short), the suggested indentation depends on whether the current line contains the first item in the list. If it does, it's indented py-indent-offset columns beyond the indentation of the line containing the open bracket. If you don't like that, change it by hand. The remaining items in the list will mimic whatever indentation you give to the first item. If a line is a continuation line because the line preceding it ends with a backslash, the third and following lines of the statement inherit their indentation from the line preceding them. The indentation of the second line in the statement depends on the form of the first (base) line: if the base line is an assignment statement with anything more interesting than the backslash following the leftmost assigning `=', the second line is indented two columns beyond that `='. Else it's indented to two columns beyond the leftmost solid chunk of non-whitespace characters on the base line. Warning: indent-region should not normally be used! It calls \\[indent-for-tab-command] repeatedly, and as explained above, \\[indent-for-tab-command] can't guess the block structure you intend. %c:indent-for-tab-command %c:py-newline-and-indent %c:py-electric-backspace The next function may be handy when editing code you didn't write: %c:py-guess-indent-offset The remaining `indent' functions apply to a region of Python code. They assume the block structure (equals indentation, in Python) of the region is correct, and alter the indentation in various ways while preserving the block structure: %c:py-indent-region %c:py-shift-region-left %c:py-shift-region-right @MARKING & MANIPULATING REGIONS OF CODE \\[py-mark-block]\t mark block of lines \\[py-mark-def-or-class]\t mark smallest enclosing def \\[universal-argument] \\[py-mark-def-or-class]\t mark smallest enclosing class \\[comment-region]\t comment out region of code \\[universal-argument] \\[comment-region]\t uncomment region of code %c:py-mark-block %c:py-mark-def-or-class %c:comment-region @MOVING POINT \\[py-previous-statement]\t move to statement preceding point \\[py-next-statement]\t move to statement following point \\[py-goto-block-up]\t move up to start of current block \\[py-beginning-of-def-or-class]\t move to start of def \\[universal-argument] \\[py-beginning-of-def-or-class]\t move to start of class \\[py-end-of-def-or-class]\t move to end of def \\[universal-argument] \\[py-end-of-def-or-class]\t move to end of class The first two move to one statement beyond the statement that contains point. A numeric prefix argument tells them to move that many statements instead. Blank lines, comment lines, and continuation lines do not count as `statements' for these commands. So, e.g., you can go to the first code statement in a file by entering \t\\[beginning-of-buffer]\t to move to the top of the file \t\\[py-next-statement]\t to skip over initial comments and blank lines Or do `\\[py-previous-statement]' with a huge prefix argument. %c:py-previous-statement %c:py-next-statement %c:py-goto-block-up %c:py-beginning-of-def-or-class %c:py-end-of-def-or-class @LITTLE-KNOWN EMACS COMMANDS PARTICULARLY USEFUL IN PYTHON MODE `\\[indent-new-comment-line]' is handy for entering a multi-line comment. `\\[set-selective-display]' with a `small' prefix arg is ideally suited for viewing the overall class and def structure of a module. `\\[back-to-indentation]' moves point to a line's first non-blank character. `\\[indent-relative]' is handy for creating odd indentation. @OTHER EMACS HINTS If you don't like the default value of a variable, change its value to whatever you do like by putting a `setq' line in your .emacs file. E.g., to set the indentation increment to 4, put this line in your .emacs: \t(setq py-indent-offset 4) To see the value of a variable, do `\\[describe-variable]' and enter the variable name at the prompt. When entering a key sequence like `C-c C-n', it is not necessary to release the CONTROL key after doing the `C-c' part -- it suffices to press the CONTROL key, press and release `c' (while still holding down CONTROL), press and release `n' (while still holding down CONTROL), & then release CONTROL. Entering Python mode calls with no arguments the value of the variable `python-mode-hook', if that value exists and is not nil; for backward compatibility it also tries `py-mode-hook'; see the `Hooks' section of the Elisp manual for details. Obscure: When python-mode is first loaded, it looks for all bindings to newline-and-indent in the global keymap, and shadows them with local bindings to py-newline-and-indent.")) (require 'info-look) ;; The info-look package does not always provide this function (it ;; appears this is the case with XEmacs 21.1) (when (fboundp 'info-lookup-maybe-add-help) (info-lookup-maybe-add-help :mode 'python-mode :regexp "[a-zA-Z0-9_]+" :doc-spec '(("(python-lib)Module Index") ("(python-lib)Class-Exception-Object Index") ("(python-lib)Function-Method-Variable Index") ("(python-lib)Miscellaneous Index"))) ) ;; Helper functions (defvar py-parse-state-re (concat "^[ \t]*\\(elif\\|else\\|while\\|def\\|class\\)\\>" "\\|" "^[^ #\t\n]")) (defun py-parse-state () "Return the parse state at point (see `parse-partial-sexp' docs)." (save-excursion (let ((here (point)) pps done) (while (not done) ;; back up to the first preceding line (if any; else start of ;; buffer) that begins with a popular Python keyword, or a ;; non- whitespace and non-comment character. These are good ;; places to start parsing to see whether where we started is ;; at a non-zero nesting level. It may be slow for people who ;; write huge code blocks or huge lists ... tough beans. (re-search-backward py-parse-state-re nil 'move) (beginning-of-line) ;; In XEmacs, we have a much better way to test for whether ;; we're in a triple-quoted string or not. Emacs does not ;; have this built-in function, which is its loss because ;; without scanning from the beginning of the buffer, there's ;; no accurate way to determine this otherwise. (save-excursion (setq pps (parse-partial-sexp (point) here))) ;; make sure we don't land inside a triple-quoted string (setq done (or (not (nth 3 pps)) (bobp))) ;; Just go ahead and short circuit the test back to the ;; beginning of the buffer. This will be slow, but not ;; nearly as slow as looping through many ;; re-search-backwards. (if (not done) (goto-char (point-min)))) pps))) (defun py-nesting-level () "Return the buffer position of the last unclosed enclosing list. If nesting level is zero, return nil." (let ((status (py-parse-state))) (if (zerop (car status)) nil ; not in a nest (car (cdr status))))) ; char# of open bracket (defun py-backslash-continuation-line-p () "Return t iff preceding line ends with backslash that is not in a comment." (save-excursion (beginning-of-line) (and ;; use a cheap test first to avoid the regexp if possible ;; use 'eq' because char-after may return nil (eq (char-after (- (point) 2)) ?\\ ) ;; make sure; since eq test passed, there is a preceding line (forward-line -1) ; always true -- side effect (looking-at py-continued-re)))) (defun py-continuation-line-p () "Return t iff current line is a continuation line." (save-excursion (beginning-of-line) (or (py-backslash-continuation-line-p) (py-nesting-level)))) (defun py-goto-beginning-of-tqs (delim) "Go to the beginning of the triple quoted string we find ourselves in. DELIM is the TQS string delimiter character we're searching backwards for." (let ((skip (and delim (make-string 1 delim))) (continue t)) (when skip (save-excursion (while continue (py-safe (search-backward skip)) (setq continue (and (not (bobp)) (= (char-before) ?\\)))) (if (and (= (char-before) delim) (= (char-before (1- (point))) delim)) (setq skip (make-string 3 delim)))) ;; we're looking at a triple-quoted string (py-safe (search-backward skip))))) (defun py-goto-initial-line () "Go to the initial line of the current statement. Usually this is the line we're on, but if we're on the 2nd or following lines of a continuation block, we need to go up to the first line of the block." ;; Tricky: We want to avoid quadratic-time behavior for long ;; continued blocks, whether of the backslash or open-bracket ;; varieties, or a mix of the two. The following manages to do that ;; in the usual cases. ;; ;; Also, if we're sitting inside a triple quoted string, this will ;; drop us at the line that begins the string. (let (open-bracket-pos) (while (py-continuation-line-p) (beginning-of-line) (if (py-backslash-continuation-line-p) (while (py-backslash-continuation-line-p) (forward-line -1)) ;; else zip out of nested brackets/braces/parens (while (setq open-bracket-pos (py-nesting-level)) (goto-char open-bracket-pos))))) (beginning-of-line)) (defun py-goto-beyond-final-line () "Go to the point just beyond the fine line of the current statement. Usually this is the start of the next line, but if this is a multi-line statement we need to skip over the continuation lines." ;; Tricky: Again we need to be clever to avoid quadratic time ;; behavior. ;; ;; XXX: Not quite the right solution, but deals with multi-line doc ;; strings (if (looking-at (concat "[ \t]*\\(" py-stringlit-re "\\)")) (goto-char (match-end 0))) ;; (forward-line 1) (let (state) (while (and (py-continuation-line-p) (not (eobp))) ;; skip over the backslash flavor (while (and (py-backslash-continuation-line-p) (not (eobp))) (forward-line 1)) ;; if in nest, zip to the end of the nest (setq state (py-parse-state)) (if (and (not (zerop (car state))) (not (eobp))) (progn (parse-partial-sexp (point) (point-max) 0 nil state) (forward-line 1)))))) (defun py-statement-opens-block-p () "Return t iff the current statement opens a block. I.e., iff it ends with a colon that is not in a comment. Point should be at the start of a statement." (save-excursion (let ((start (point)) (finish (progn (py-goto-beyond-final-line) (1- (point)))) (searching t) (answer nil) state) (goto-char start) (while searching ;; look for a colon with nothing after it except whitespace, and ;; maybe a comment (if (re-search-forward ":\\([ \t]\\|\\\\\n\\)*\\(#.*\\)?$" finish t) (if (eq (point) finish) ; note: no `else' clause; just ; keep searching if we're not at ; the end yet ;; sure looks like it opens a block -- but it might ;; be in a comment (progn (setq searching nil) ; search is done either way (setq state (parse-partial-sexp start (match-beginning 0))) (setq answer (not (nth 4 state))))) ;; search failed: couldn't find another interesting colon (setq searching nil))) answer))) (defun py-statement-closes-block-p () "Return t iff the current statement closes a block. I.e., if the line starts with `return', `raise', `break', `continue', and `pass'. This doesn't catch embedded statements." (let ((here (point))) (py-goto-initial-line) (back-to-indentation) (prog1 (looking-at (concat py-block-closing-keywords-re "\\>")) (goto-char here)))) (defun py-goto-beyond-block () "Go to point just beyond the final line of block begun by the current line. This is the same as where `py-goto-beyond-final-line' goes unless we're on colon line, in which case we go to the end of the block. Assumes point is at the beginning of the line." (if (py-statement-opens-block-p) (py-mark-block nil 'just-move) (py-goto-beyond-final-line))) (defun py-goto-statement-at-or-above () "Go to the start of the first statement at or preceding point. Return t if there is such a statement, otherwise nil. `Statement' does not include blank lines, comments, or continuation lines." (py-goto-initial-line) (if (looking-at py-blank-or-comment-re) ;; skip back over blank & comment lines ;; note: will skip a blank or comment line that happens to be ;; a continuation line too (if (re-search-backward "^[ \t]*[^ \t#\n]" nil t) (progn (py-goto-initial-line) t) nil) t)) (defun py-goto-statement-below () "Go to start of the first statement following the statement containing point. Return t if there is such a statement, otherwise nil. `Statement' does not include blank lines, comments, or continuation lines." (beginning-of-line) (let ((start (point))) (py-goto-beyond-final-line) (while (and (or (looking-at py-blank-or-comment-re) (py-in-literal)) (not (eobp))) (forward-line 1)) (if (eobp) (progn (goto-char start) nil) t))) (defun py-go-up-tree-to-keyword (key) "Go to begining of statement starting with KEY, at or preceding point. KEY is a regular expression describing a Python keyword. Skip blank lines and non-indenting comments. If the statement found starts with KEY, then stop, otherwise go back to first enclosing block starting with KEY. If successful, leave point at the start of the KEY line and return t. Otherwise, leav point at an undefined place and return nil."