;;; python-mode.el --- Major mode for editing Python programs

;; Copyright (C) 1992,1993,1994  Tim Peters

;; Author: 2003-2007 http://sf.net/projects/python-mode

;;         1995-2002 Barry A. Warsaw

;;         1992-1994 Tim Peters

;; Maintainer: python-mode@python.org

;; Created:    Feb 1992

;; Keywords:   python languages oop

(defconst py-version "$Revision: 60587 $"

  "`python-mode' version number.")

;; This software is provided as-is, without express or implied

;; warranty.  Permission to use, copy, modify, distribute or sell this

;; software, without fee, for any purpose and by any individual or

;; organization, is hereby granted, provided that the above copyright

;; notice and this paragraph appear in all copies.

;;; Commentary:

;; This is a major mode for editing Python programs.  It was developed by Tim

;; Peters after an original idea by Michael A. Guravage.  Tim subsequently

;; left the net and in 1995, Barry Warsaw inherited the mode.  Tim's now back

;; but disavows all responsibility for the mode.  In fact, we suspect he

;; doesn't even use Emacs any more.  In 2003, python-mode.el was moved to its

;; own SourceForge project apart from the Python project, and now is

;; maintained by the volunteers at the python-mode@python.org mailing list.

;; pdbtrack support contributed by Ken Manheimer, April 2001.  Skip Montanaro

;; has also contributed significantly to python-mode's development.

;; Please use the SourceForge Python project to submit bugs or

;; patches:

;;

;;     http://sourceforge.net/projects/python

;; INSTALLATION:

;; To install, just drop this file into a directory on your load-path and

;; byte-compile it.  To set up Emacs to automatically edit files ending in

;; ".py" using python-mode add the following to your ~/.emacs file (GNU

;; Emacs) or ~/.xemacs/init.el file (XEmacs):

;;    (setq auto-mode-alist (cons '("\\.py$" . python-mode) auto-mode-alist))

;;    (setq interpreter-mode-alist (cons '("python" . python-mode)

;;                                       interpreter-mode-alist))

;;    (autoload 'python-mode "python-mode" "Python editing mode." t)

;;

;; In XEmacs syntax highlighting should be enabled automatically.  In GNU

;; Emacs you may have to add these lines to your ~/.emacs file:

;;    (global-font-lock-mode t)

;;    (setq font-lock-maximum-decoration t)

;; FOR MORE INFORMATION:

;; There is some information on python-mode.el at

;;     http://www.python.org/emacs/python-mode/

;;

;; It does contain links to other packages that you might find useful,

;; such as pdb interfaces, OO-Browser links, etc.

;; BUG REPORTING:

;; As mentioned above, please use the SourceForge Python project for

;; submitting bug reports or patches.  The old recommendation, to use

;; C-c C-b will still work, but those reports have a higher chance of

;; getting buried in my mailbox.  Please include a complete, but

;; concise code sample and a recipe for reproducing the bug.  Send

;; suggestions and other comments to python-mode@python.org.

;; When in a Python mode buffer, do a C-h m for more help.  It's

;; doubtful that a texinfo manual would be very useful, but if you

;; want to contribute one, I'll certainly accept it!

;;; Code:

(require 'comint)

(require 'custom)

(require 'cl)

(require 'compile)

(require 'ansi-color)

;; user definable variables

;; vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv

(defgroup python nil

  "Support for the Python programming language, <http://www.python.org/>"

  :group 'languages

  :prefix "py-")

(defcustom py-tab-always-indent t

  "*Non-nil means TAB in Python mode should always reindent the current line,

regardless of where in the line point is when the TAB command is used."

  :type 'boolean

  :group 'python)

(defcustom py-python-command "python"

  "*Shell command used to start Python interpreter."

  :type 'string

  :group 'python)

(make-obsolete-variable 'py-jpython-command 'py-jython-command)

(defcustom py-jython-command "jython"

  "*Shell command used to start the Jython interpreter."

  :type 'string

  :group 'python

  :tag "Jython Command")

(defcustom py-default-interpreter 'cpython

  "*Which Python interpreter is used by default.

The value for this variable can be either `cpython' or `jython'.

When the value is `cpython', the variables `py-python-command' and

`py-python-command-args' are consulted to determine the interpreter

and arguments to use.

When the value is `jython', the variables `py-jython-command' and

`py-jython-command-args' are consulted to determine the interpreter

and arguments to use.

Note that this variable is consulted only the first time that a Python

mode buffer is visited during an Emacs session.  After that, use

\\[py-toggle-shells] to change the interpreter shell."

  :type '(choice (const :tag "Python (a.k.a. CPython)" cpython)

		 (const :tag "Jython" jython))

  :group 'python)

(defcustom py-python-command-args '("-i")

  "*List of string arguments to be used when starting a Python shell."

  :type '(repeat string)

  :group 'python)

(make-obsolete-variable 'py-jpython-command-args 'py-jython-command-args)

(defcustom py-jython-command-args '("-i")

  "*List of string arguments to be used when starting a Jython shell."

  :type '(repeat string)

  :group 'python

  :tag "Jython Command Args")

(defcustom py-indent-offset 4

  "*Amount of offset per level of indentation.

`\\[py-guess-indent-offset]' can usually guess a good value when

you're editing someone else's Python code."

  :type 'integer

  :group 'python)

(defcustom py-continuation-offset 4

  "*Additional amount of offset to give for some continuation lines.

Continuation lines are those that immediately follow a backslash

terminated line.  Only those continuation lines for a block opening

statement are given this extra offset."

  :type 'integer

  :group 'python)

(defcustom py-smart-indentation t

  "*Should `python-mode' try to automagically set some indentation variables?

When this variable is non-nil, two things happen when a buffer is set

to `python-mode':

    1. `py-indent-offset' is guessed from existing code in the buffer.

       Only guessed values between 2 and 8 are considered.  If a valid

       guess can't be made (perhaps because you are visiting a new

       file), then the value in `py-indent-offset' is used.

    2. `indent-tabs-mode' is turned off if `py-indent-offset' does not

       equal `tab-width' (`indent-tabs-mode' is never turned on by

       Python mode).  This means that for newly written code, tabs are

       only inserted in indentation if one tab is one indentation

       level, otherwise only spaces are used.

Note that both these settings occur *after* `python-mode-hook' is run,

so if you want to defeat the automagic configuration, you must also

set `py-smart-indentation' to nil in your `python-mode-hook'."

  :type 'boolean

  :group 'python)

(defcustom py-align-multiline-strings-p t

  "*Flag describing how multi-line triple quoted strings are aligned.

When this flag is non-nil, continuation lines are lined up under the

preceding line's indentation.  When this flag is nil, continuation

lines are aligned to column zero."

  :type '(choice (const :tag "Align under preceding line" t)

		 (const :tag "Align to column zero" nil))

  :group 'python)

(defcustom py-block-comment-prefix "##"

  "*String used by \\[comment-region] to comment out a block of code.

This should follow the convention for non-indenting comment lines so

that the indentation commands won't get confused (i.e., the string

should be of the form `#x...' where `x' is not a blank or a tab, and

`...' is arbitrary).  However, this string should not end in whitespace."

  :type 'string

  :group 'python)

(defcustom py-honor-comment-indentation t

  "*Controls how comment lines influence subsequent indentation.

When nil, all comment lines are skipped for indentation purposes, and

if possible, a faster algorithm is used (i.e. X/Emacs 19 and beyond).

When t, lines that begin with a single `#' are a hint to subsequent

line indentation.  If the previous line is such a comment line (as

opposed to one that starts with `py-block-comment-prefix'), then its

indentation is used as a hint for this line's indentation.  Lines that

begin with `py-block-comment-prefix' are ignored for indentation

purposes.

When not nil or t, comment lines that begin with a single `#' are used

as indentation hints, unless the comment character is in column zero."

  :type '(choice

	  (const :tag "Skip all comment lines (fast)" nil)

	  (const :tag "Single # `sets' indentation for next line" t)

	  (const :tag "Single # `sets' indentation except at column zero"

		 other)

	  )

  :group 'python)

(defcustom py-temp-directory

  (let ((ok '(lambda (x)

	       (and x

		    (setq x (expand-file-name x)) ; always true

		    (file-directory-p x)

		    (file-writable-p x)

		    x))))

    (or (funcall ok (getenv "TMPDIR"))

	(funcall ok "/usr/tmp")

	(funcall ok "/tmp")

	(funcall ok "/var/tmp")

	(funcall ok  ".")

	(error

	 "Couldn't find a usable temp directory -- set `py-temp-directory'")))

  "*Directory used for temporary files created by a *Python* process.

By default, the first directory from this list that exists and that you

can write into: the value (if any) of the environment variable TMPDIR,

/usr/tmp, /tmp, /var/tmp, or the current directory."

  :type 'string

  :group 'python)

(defcustom py-beep-if-tab-change t

  "*Ring the bell if `tab-width' is changed.

If a comment of the form

  \t# vi:set tabsize=<number>:

is found before the first code line when the file is entered, and the

current value of (the general Emacs variable) `tab-width' does not

equal <number>, `tab-width' is set to <number>, a message saying so is

displayed in the echo area, and if `py-beep-if-tab-change' is non-nil

the Emacs bell is also rung as a warning."

  :type 'boolean

  :group 'python)

(defcustom py-jump-on-exception t

  "*Jump to innermost exception frame in *Python Output* buffer.

When this variable is non-nil and an exception occurs when running

Python code synchronously in a subprocess, jump immediately to the

source code of the innermost traceback frame."

  :type 'boolean

  :group 'python)

(defcustom py-ask-about-save t

  "If not nil, ask about which buffers to save before executing some code.

Otherwise, all modified buffers are saved without asking."

  :type 'boolean

  :group 'python)

(defcustom py-backspace-function 'backward-delete-char-untabify

  "*Function called by `py-electric-backspace' when deleting backwards."

  :type 'function

  :group 'python)

(defcustom py-delete-function 'delete-char

  "*Function called by `py-electric-delete' when deleting forwards."

  :type 'function

  :group 'python)

(defcustom py-imenu-show-method-args-p nil

  "*Controls echoing of arguments of functions & methods in the Imenu buffer.

When non-nil, arguments are printed."

  :type 'boolean

  :group 'python)

(make-variable-buffer-local 'py-indent-offset)

(defcustom py-pdbtrack-do-tracking-p t

  "*Controls whether the pdbtrack feature is enabled or not.

When non-nil, pdbtrack is enabled in all comint-based buffers,

e.g. shell buffers and the *Python* buffer.  When using pdb to debug a

Python program, pdbtrack notices the pdb prompt and displays the

source file and line that the program is stopped at, much the same way

as gud-mode does for debugging C programs with gdb."

  :type 'boolean

  :group 'python)

(make-variable-buffer-local 'py-pdbtrack-do-tracking-p)

(defcustom py-pdbtrack-minor-mode-string " PDB"

  "*String to use in the minor mode list when pdbtrack is enabled."

  :type 'string

  :group 'python)

(defcustom py-import-check-point-max

  20000

  "Maximum number of characters to search for a Java-ish import statement.

When `python-mode' tries to calculate the shell to use (either a

CPython or a Jython shell), it looks at the so-called `shebang' line

-- i.e. #! line.  If that's not available, it looks at some of the

file heading imports to see if they look Java-like."

  :type 'integer

  :group 'python

  )

(make-obsolete-variable 'py-jpython-packages 'py-jython-packages)

(defcustom py-jython-packages

  '("java" "javax" "org" "com")

  "Imported packages that imply `jython-mode'."

  :type '(repeat string)

  :group 'python)

;; Not customizable

(defvar py-master-file nil

  "If non-nil, execute the named file instead of the buffer's file.

The intent is to allow you to set this variable in the file's local

variable section, e.g.:

    # Local Variables:

    # py-master-file: \"master.py\"

    # End:

so that typing \\[py-execute-buffer] in that buffer executes the named

master file instead of the buffer's file.  If the file name has a

relative path, the value of variable `default-directory' for the

buffer is prepended to come up with a file name.")

(make-variable-buffer-local 'py-master-file)

(defcustom py-pychecker-command "pychecker"

  "*Shell command used to run Pychecker."

  :type 'string

  :group 'python

  :tag "Pychecker Command")

(defcustom py-pychecker-command-args '("--stdlib")

  "*List of string arguments to be passed to pychecker."

  :type '(repeat string)

  :group 'python

  :tag "Pychecker Command Args")

(defvar py-shell-alist

  '(("jython" . 'jython)

    ("python" . 'cpython))

  "*Alist of interpreters and python shells. Used by `py-choose-shell'

to select the appropriate python interpreter mode for a file.")

(defcustom py-shell-input-prompt-1-regexp "^>>> "

  "*A regular expression to match the input prompt of the shell."

  :type 'string

  :group 'python)

(defcustom py-shell-input-prompt-2-regexp "^[.][.][.] "

  "*A regular expression to match the input prompt of the shell after the

  first line of input."

  :type 'string

  :group 'python)

(defcustom py-shell-switch-buffers-on-execute t

  "*Controls switching to the Python buffer where commands are

  executed.  When non-nil the buffer switches to the Python buffer, if

  not no switching occurs."

  :type 'boolean

  :group 'python)

;; ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

;; NO USER DEFINABLE VARIABLES BEYOND THIS POINT

(defvar py-line-number-offset 0

  "When an exception occurs as a result of py-execute-region, a

subsequent py-up-exception needs the line number where the region

started, in order to jump to the correct file line.  This variable is

set in py-execute-region and used in py-jump-to-exception.")

(defconst py-emacs-features

  (let (features)

   features)

  "A list of features extant in the Emacs you are using.

There are many flavors of Emacs out there, with different levels of

support for features needed by `python-mode'.")

;; Face for None, True, False, self, and Ellipsis

(defvar py-pseudo-keyword-face 'py-pseudo-keyword-face

  "Face for pseudo keywords in Python mode, like self, True, False, Ellipsis.")

(make-face 'py-pseudo-keyword-face)

;; PEP 318 decorators

(defvar py-decorators-face 'py-decorators-face

  "Face method decorators.")

(make-face 'py-decorators-face)

;; Face for builtins

(defvar py-builtins-face 'py-builtins-face

  "Face for builtins like TypeError, object, open, and exec.")

(make-face 'py-builtins-face)

;; XXX, TODO, and FIXME comments and such

(defvar py-XXX-tag-face 'py-XXX-tag-face

  "Face for XXX, TODO, and FIXME tags")

(make-face 'py-XXX-tag-face)

(defun py-font-lock-mode-hook ()

  (or (face-differs-from-default-p 'py-pseudo-keyword-face)

      (copy-face 'font-lock-keyword-face 'py-pseudo-keyword-face))

  (or (face-differs-from-default-p 'py-builtins-face)

      (copy-face 'font-lock-keyword-face 'py-builtins-face))

  (or (face-differs-from-default-p 'py-decorators-face)

      (copy-face 'py-pseudo-keyword-face 'py-decorators-face))

  (or (face-differs-from-default-p 'py-XXX-tag-face)

      (copy-face 'font-lock-comment-face 'py-XXX-tag-face))

  )

(add-hook 'font-lock-mode-hook 'py-font-lock-mode-hook)

(defvar python-font-lock-keywords

  (let ((kw1 (mapconcat 'identity

			'("and"      "assert"   "break"   "class"

			  "continue" "def"      "del"     "elif"

			  "else"     "except"   "exec"    "for"

			  "from"     "global"   "if"      "import"

			  "in"       "is"       "lambda"  "not"

			  "or"       "pass"     "print"   "raise"

			  "return"   "while"    "with"    "yield"

			  )

			"\\|"))

	(kw2 (mapconcat 'identity

			'("else:" "except:" "finally:" "try:")

			"\\|"))

	(kw3 (mapconcat 'identity

			;; Don't include True, False, None, or

			;; Ellipsis in this list, since they are

			;; already defined as pseudo keywords.

			'("__debug__"

			  "__import__" "__name__" "abs" "apply" "basestring"

			  "bool" "buffer" "callable" "chr" "classmethod"

			  "cmp" "coerce" "compile" "complex" "copyright"

			  "delattr" "dict" "dir" "divmod"

			  "enumerate" "eval" "execfile" "exit" "file"

			  "filter" "float" "getattr" "globals" "hasattr"

			  "hash" "hex" "id" "input" "int" "intern"

			  "isinstance" "issubclass" "iter" "len" "license"

			  "list" "locals" "long" "map" "max" "min" "object"

			  "oct" "open" "ord" "pow" "property" "range"

			  "raw_input" "reduce" "reload" "repr" "round"

			  "setattr" "slice" "staticmethod" "str" "sum"

			  "super" "tuple" "type" "unichr" "unicode" "vars"

			  "xrange" "zip")

			"\\|"))

	(kw4 (mapconcat 'identity

			;; Exceptions and warnings

			'("ArithmeticError" "AssertionError"

			  "AttributeError" "DeprecationWarning" "EOFError"

			  "EnvironmentError" "Exception"

			  "FloatingPointError" "FutureWarning" "IOError"

			  "ImportError" "IndentationError" "IndexError"

			  "KeyError" "KeyboardInterrupt" "LookupError"

			  "MemoryError" "NameError" "NotImplemented"

			  "NotImplementedError" "OSError" "OverflowError"

			  "OverflowWarning" "PendingDeprecationWarning"

			  "ReferenceError" "RuntimeError" "RuntimeWarning"

			  "StandardError" "StopIteration" "SyntaxError"

			  "SyntaxWarning" "SystemError" "SystemExit"

			  "TabError" "TypeError" "UnboundLocalError"

			  "UnicodeDecodeError" "UnicodeEncodeError"

			  "UnicodeError" "UnicodeTranslateError"

			  "UserWarning" "ValueError" "Warning"

			  "ZeroDivisionError")

			"\\|"))

	)

    (list

     '("^[ \t]*\\(@.+\\)" 1 'py-decorators-face)

     ;; keywords

     (cons (concat "\\<\\(" kw1 "\\)\\>[ \n\t(]") 1)

     ;; builtins when they don't appear as object attributes

     (list (concat "\\([^. \t]\\|^\\)[ \t]*\\<\\(" kw3 "\\)\\>[ \n\t(]") 2

	   'py-builtins-face)

     ;; block introducing keywords with immediately following colons.

     ;; Yes "except" is in both lists.

     (cons (concat "\\<\\(" kw2 "\\)[ \n\t(]") 1)

     ;; Exceptions

     (list (concat "\\<\\(" kw4 "\\)[ \n\t:,(]") 1 'py-builtins-face)

     ;; `as' but only in "import foo as bar" or "with foo as bar"

     '("[ \t]*\\(\\<from\\>.*\\)?\\<import\\>.*\\<\\(as\\)\\>" . 2)

     '("[ \t]*\\<with\\>.*\\<\\(as\\)\\>" . 1)

     ;; classes

     '("\\<class[ \t]+\\([a-zA-Z_]+[a-zA-Z0-9_]*\\)" 1 font-lock-type-face)

     ;; functions

     '("\\<def[ \t]+\\([a-zA-Z_]+[a-zA-Z0-9_]*\\)"

       1 font-lock-function-name-face)

     ;; pseudo-keywords

     '("\\<\\(self\\|None\\|True\\|False\\|Ellipsis\\)\\>"

       1 py-pseudo-keyword-face)

     ;; XXX, TODO, and FIXME tags

     '("XXX\\|TODO\\|FIXME" 0 py-XXX-tag-face t)

     ))

  "Additional expressions to highlight in Python mode.")

(put 'python-mode 'font-lock-defaults '(python-font-lock-keywords))

;; have to bind py-file-queue before installing the kill-emacs-hook

(defvar py-file-queue nil

  "Queue of Python temp files awaiting execution.

Currently-active file is at the head of the list.")

(defvar py-pdbtrack-is-tracking-p nil)

(defvar py-pychecker-history nil)

;; Constants

(defconst py-stringlit-re

  (concat

   ;; These fail if backslash-quote ends the string (not worth

   ;; fixing?).  They precede the short versions so that the first two

   ;; quotes don't look like an empty short string.

   ;;

   ;; (maybe raw), long single quoted triple quoted strings (SQTQ),

   ;; with potential embedded single quotes

   "[rR]?'''[^']*\\(\\('[^']\\|''[^']\\)[^']*\\)*'''"

   "\\|"