![[PukiWiki]](image/pukiwiki.png "[PukiWiki]")
* Using Python with Emacs [#ubab6009] [[Back>PythonForScience]] #contents ** Introduction [#rdea2d00] In this page, I will explain ''my'' emacs environment for programing and interactive session with Python. I put emphasis on ''my'' because this may not be the most elegant solution (and probably it isn't). The effectiveness of a human interface depends a lot on the user's preference. Therefore, the example shown here strongly reflects my personal preferences. You may want to change details of the behavior. You can do so but you have to know a bit about Emacs Lisp. Since I don't have a time to explain Emacs Lisp here, I will just refer you to two nice documents for learning Emacs Lisp, [[An Introduction to Programming in Emacs Lisp>http://www.gnu.org/software/emacs/emacs-lisp-intro/]] and [[GNU Emacs Lisp Reference Manual>http://www.gnu.org/software/emacs/manual/elisp.html]]. ** My computer environment [#y460d76c] Before going into the details of the emacs setting, I will list my computer environment as a reference. |Hardware| PC (Sony VAIO type Z)| |OS|Ubuntu 9.10 (x86-64)| ** Additional packages [#qd13cce5] In addition to Emacs, you need to install several packages. I took most of the information from [[here>http://www.emacswiki.org/emacs/PythonMode]]. - python-mode.el -- This is the main guy. It defines a major mode for python editing and interactive execution. We will add some tweaks to this mode later. It is a part of the python distribution. You can download it also from https://launchpad.net/python-mode . On Ubuntu, it is in the '''python-mode''' package. - IPython -- [[IPython>http://ipython.scipy.org/moin/]] is a better interactive shell for Python. It has a lot more functionalities than the standard python shell. We will use IPython as a Python shell in Emacs. You should check these [[video tutorials>http://showmedo.com/videotutorials/series?name=CnluURUTV]] for IPython as these are damn good. On Ubuntu, you can just download and install ipython package. You may have to manually put ipython.el to your site-lisp directory. - Folding-mode -- Folding mode is a minor mode to allow folding a region of Emacs buffer. I used this to implement cells. You can get more information about folding-mode from [[here>http://www.emacswiki.org/emacs-en/FoldingMode]] - ropemacs -- Rope is a refactoring library for Python. ropemacs enables you to use rope functionalities from emacs. ropemacs can be obtained from [[http://rope.sourceforge.net/ropemacs.html]]. You also need [[rope>http://rope.sf.net/]] and [[pymacs>http://pymacs.progiciels-bpi.ca/pymacs.html]] to use ropemacs. - ropemacs -- Rope is a refactoring library for Python. ropemacs enables you to use rope functionalities from emacs. ropemacs can be obtained from http://rope.sourceforge.net/ropemacs.html . You also need [[rope>http://rope.sf.net/]] and [[pymacs>http://pymacs.progiciels-bpi.ca/pymacs.html]] to use ropemacs. - pylint -- pylint is a grammar checker for python. To use it from emacs, you need epylint script, which may be provided with pylint. If not, get it from [[here>http://www.emacswiki.org/emacs/PythonMode#toc8]]. - auto-complete.el -- It provides intelligent automatic completion. Get is from [[here>http://www.emacswiki.org/emacs/AutoComplete]]. - yasnippet -- Code snippet insertion. [[http://code.google.com/p/yasnippet/]] - yasnippet -- Code snippet insertion. http://code.google.com/p/yasnippet/ ** .emacs file [#d98b50a0] Once you have installed the above packages, edit your .emacs file.~ Here is an example of [[.emacs>https://granite.phys.s.u-tokyo.ac.jp/wiki/Lab/index.php?plugin=attach&pcmd=open&file=dotemacs&refer=EmacsPython]] file. You can merge this file into your .emacs file. Please read the comments in the file to see what is going on. ** Usage [#x2b0c669] *** Notation [#q756e278] In this tutorial, key bindings are explained often. The notation for key strokes are in the following form. Example1:~ [C-c x] The square brackets [] indicate that this is a suit of key strokes. C-c means press c while holding Ctrl down. Therefore the meaning of the above example is to hit c with Ctrl pressed then hit x *without* Ctrl. Example2:~ [C-c C-x] In this case, you have to keep Ctrl pressed when you hit x. Example3:~ [M-x TAB] M indicates a meta key. On a PC, it is usually bound to Alt key. TAB is of courese the TAB key. Example4:~ [M-C-x] Here you are required to press Meta and Ctrl and x at the same time. Example5:~ "[M-x] emacs-function" [M-x] is used to invoke an emacs function. After pressing [M-x], you enter the name of the emacs function in the mini buffer. TAB completion is available. *** Starting up [#w72b1467] When you invoke Emacs, supply "-py" option. This is necessary because in my .emacs, this option is used to determine whether to load pymacs and ropemacs or not. pymacs and ropemacs are not loaded by default because it takes some time and delays the start up of Emacs. You do not want to load them unless you know you are going to use rope. If "-py" option is used, Emacs will load pymacs and ropemacs at the start up. If you did not specify "-py" but want to use rope later in the session, you can call my-pymacs-init (by typing "[M-x] my-pymacs-init") at any time. *** Python-mode [#aec8b956] If you open a file with an extension ".py", the python-mode will be automatically invoked. You will have nice syntax highlighting and automatic indentation. In addition, you can do the followings (and much more actually): - &color(green){Starting python shell:}; Hit [C-c !] to invoke a python shell. If you used my .emacs, ipython will be started instead of the standard python shell. - &color(green){Execute buffer:}; [C-c C-c]. The whole buffer is executed in the python shell. - &color(green){Execute a region:}; Select a region in the buffer of your python code. Then hit [C-c |]. It will invoke an emacs function py-execute-region. This function saves the current region to a temporary file and execute it in the python shell using execfile(). Therefore, objects defined in the region will be made available in the python shell. It is extremely useful as you can do introspections of the objects later. - &color(green){Execute a line:}; Hit [C-c l] to copy the current line to the python shell and execute it. This way, you can run your script line-by-line. - &color(green){Execute the current definition:}; [C-M-x]. Send the current function or class definition to the python shell. - &color(green){Execute cell:}; [C-c C-j]. Execute the current cell in the python shell. See below for more about cells. - &color(green){Indent region:}; [C-c TAB]. Indent a region at a time. - &color(green){Complete with ipython:}; [M-TAB]. Try to complete a word at the current cursor point using ipython's completion function. You have to have ipython running as your python shell. The completion is performed using the name space of the running ipython shell. Therefore, if you haven't executed your code in the shell (e.g. using [C-c C-c]), the completion candidates may not be useful. - &color(green){Comment/Uncomment region:}; [M-;]. You have to have transient-mark-mode turned on. - &color(green){Get help:}; [C-c C-h]. Run py-help-at-point. It is not that useful though. Use [C-c d] (rope-show-doc) instead. - &color(green){Get help on python-mode:}; Show help document for python-mode. *** Ropemacs [#b8f3880a] If you installed ropemacs, you have access to the following functionalities (and much more !): - &color(green){Completion with rope:}; [M-/]. Perform a word completion using rope. You are asked to indicate the project root directory, the first time you invoke this command (or any rope command actually). Usually you just have to accept the default directory indicated. This completion function is very robust and useful. - &color(green){Completion with rope feeling lucky:}; [M-?]. Complete a word without showing candidates. - &color(green){Get help:}; [C-c d]. Show the documentation of the object under the cursor. - &color(green){Go to the definition:}; [C-c g]. Open the source file in which the object under the cursor is defined. - &color(green){Rename object:}; [C-c r r]. Rename the object under the cursor using rope's refactoring capability. Since rope is a refactoring library, you can perform many refactoring operations. You can access those functionalities from the rope menu. *** Folding mode and cells [#b99ac7ca] I use folding-mode to realize cell functionality in emacs. A cell is defined as a region enclosed with #{{{ and #}}}. You can open and close cells using right-mouse-click or keyboard shortcuts explained below. You can also execute a cell by [C-c C-j]. Cells can be nested. You can specify the title of a cell after the opening parenthesis like this: #{{{ Cell title #}}} By using cells, you can improve the readability of your code. Also splitting scripts into small chunks of codes is useful for cut-and-try style work flow of scientific computing. ''Warning:'' Currently, folding-mode and ropemacs are not fully compatible. The rope functions often fail if the cells are closed. Hit [C-c C-f C-o] to open all the cells in the buffer, before using rope commands. - &color(green){Entering the folding mode}; "[M-x] folding-mode". Folding mode is on by default if you use my .emacs. - &color(green){Open a cell:}; [C-c C-f C-s] - &color(green){Close a cell:}; [C-c C-f C-x] - &color(green){Open all the cells in the buffer:}; [C-c C-f C-o] - &color(green){Close all the cells in the buffer:}; [C-c C-f C-w] - &color(green){Insert a blank cell:}; [C-c C-f C-c] *** Flymake and pylint [#z5c15d20] Flymake is a minor-mode to compile the current code on the fly in the background and report any compilation error on the buffer. In python, there is no compilation process, but you can check the syntax errors using various lint programs. My .emacs is configured to use flymake with pylint. The flymake mode is turned off by default. You can turn it on from the menubar [python] -> [Toggle flymake mode]. You can also toggle it by "[M-x] flymake-mode". *** Parentheses check [#tbf59015] To show the correspondence of parentheses, turn on the show-paren-mode by "[M-x] show-paren-mode". "[M-x] blink-matching-open" may be also useful. *** Window management [#x38ab5c9] An emacs frame (window in a usual sense) can be divided into several windows (frames in a usual sense). Those windows can be resized using mouse. But you may want to use keyboard shortcuts. - &color(green){Enlarge window vertically:}; [C-x ^] - &color(green){Enlarge window horizontally:}; [C-x }] - &color(green){Shrink window horizontally:}; [C-x {] - &color(green){Move to the next window:}; [C-x o] Additionally I added the following key bindings in my .emacs (global-set-key "\C-x7" 'shrink-window) (global-set-key "\C-xl" 'previous-multiframe-window) - &color(green){Shrink window vertically:}; [C-x 7] - &color(green){Move to the previous window:}; [C-x l] *** Debugger [#v5f11e2a] You can invoke python debugger (pdb) by "[M-x] pdb". You are asked to enter the arguments for pdb. Usually you just give the file name of your script. After running pdb, you will see a pdb prompt and the source of the file you are debugging in separate windows. You can set a break point in a file by going to the source file buffer and pressing [C-x SPACE].
